diff --git a/docs/guide-es/README.md b/docs/guide-es/README.md index bd8132d39b..e93845c140 100644 --- a/docs/guide-es/README.md +++ b/docs/guide-es/README.md @@ -197,6 +197,6 @@ Clases auxiliares * **TBD** [Información general](helper-overview.md) * **TBD** [ArrayHelper](helper-array.md) -* **TBD** [Html](helper-html.md) +* [Html](helper-html.md) * [Url](helper-url.md) * **TBD** [Security](helper-security.md) diff --git a/docs/guide-es/helper-html.md b/docs/guide-es/helper-html.md new file mode 100644 index 0000000000..fa588c3968 --- /dev/null +++ b/docs/guide-es/helper-html.md @@ -0,0 +1,377 @@ +Clase auxiliar Html (Html helper) +================================= + +Todas las aplicaciones web generan grandes cantidades de marcado HTML (HTML markup). Si el marcado es estático, se +puede realizar de forma efectiva +[mezclando PHP y HTML en un mismo archivo](http://php.net/manual/es/language.basic-syntax.phpmode.php) pero cuando se +generan dinámicamente empieza a complicarse su gestion sin ayuda extra. Yii proporciona esta ayuda que proporciona un +conjunto de métodos estáticos para gestionar las etiquetas HTML usadas más comúnmente, sus opciones y contenidos. + +> Nota: Si el marcado es casi estático, es preferible usar HTML directamente. No es necesario encapsularlo todo con +llamadas a la clase auxiliar Html. + +Lo fundamental +-------------- + +Teniendo en cuenta que la construcción de HTML dinámico mediante la concatenación de cadenas de texto se complica +rápidamente, Yii proporciona un conjunto de métodos para manipular las opciones de etiquetas y la construcción de las +mismas basadas en estas opciones. + +### Generación de etiquetas + +El código de generación de etiquetas es similar al siguiente: + +```php +name), ['class' => 'username']) ?> +``` + +El primer argumento es el nombre de la etiqueta. El segundo es el contenido que se ubicara entre la etiqueta de +apertura y la de cierre. Hay que tener en cuenta que estamos usando `Html::encode`. Esto es debido a que el contenido +no se codifica automáticamente para permitir usar HTML cuando se necesite. La tercera opción es un array de opciones +HTML o, en otras palabras, los atributos de las etiquetas. En este array la clave representa el nombre del atributo +como podría ser `class`, `href` o `target` y el valor es su valor. + +El código anterior generara el siguiente HTML: + +```html +

samdark

+``` + +Si se necesita solo la apertura o el cierre de una etiqueta, se pueden usar los métodos `Html::beginTag()` y +`Html::endTag()`. + +Las opciones se usan en muchos métodos de la clase auxiliar Html y en varios widgets. En todos estos casos hay cierta +gestión adicional que se debe conocer: + +- Si un valor es `null`, el correspondiente atributo no se renderizará. +- Los atributos cuyos valores son de tipo booleano serán tratados como + [atributos booleanos](http://www.w3.org/TR/html5/infrastructure.html#boolean-attributes). +- Los valores de los atributos se codificaran en HTML usando [[yii\helpers\Html::encode()|Html::encode()]]. +- El atributo "data" puede recibir un array. En este caso, se "expandirá" y se renderizará una lista de atributos + `data` p. ej. `'data' => ['id' => 1, 'name' => 'yii']` se convierte en `data-id="1" data-name="yii"`. +- El atributo "data" puede recibir JSON. Se gestionará de la misma manera que un array p. ej. + `'data' => ['params' => ['id' => 1, 'name' => 'yii'], 'status' => 'ok']` se convierte en + `data-params='{"id":1,"name":"yii"}' data-status="ok"`. + +### Formación de clases y estilos dinámicamente + +Cuando se construyen opciones para etiquetas HTML, a menudo nos encontramos con valores predeterminados que hay que +modificar. Para añadir o eliminar clases CSS se puede usar el siguiente ejemplo: + +```php +$options = ['class' => 'btn btn-default']; + +if ($type === 'success') { + Html::removeCssClass($options, 'btn-default'); + Html::addCssClass($options, 'btn-success'); +} + +echo Html::tag('div', 'Pwede na', $options); + +// cuando $type sea 'success' se renderizará +//
Pwede na
+``` + +Para hacer lo mismo con los estilos para el atributo `style`: + +```php +$options = ['style' => ['width' => '100px', 'height' => '100px']]; + +// devuelve style="width: 100px; height: 200px; position: absolute;" +Html::addCssStyle($options, 'height: 200px; positon: absolute;'); + +// devuelve style="position: absolute;" +Html::removeCssStyle($options, ['width', 'height']); +``` + +Cuando se usa [[yii\helpers\Html::addCssStyle()|addCssStyle()]] se puede especificar si un array de pares clave-valor +corresponde a nombres y valores de la propiedad CSS correspondiente o a una cadena de texto como por ejemplo +`width: 100px; height: 200px;`. Estos formatos se pueden "hacer" y "deshacer" usando +[[yii\helpers\Html::cssStyleFromArray()|cssStyleFromArray()]] y +[[yii\helpers\Html::cssStyleToArray()|cssStyleToArray()]]. El método +[[yii\helpers\Html::removeCssStyle()|removeCssStyle()]] un array de propiedades que se eliminarán. Si sólo se +eliminará una propiedad, se puede especificar como una cadena de texto. + +Codificación y Descodificación de contenido +------------------------------------------- + +Para que el contenido se muestre correctamente y de forma segura en caracteres especiales HTML el contenido debe ser +codificado. En PHP esto se hace con [htmlspecialchars](http://www.php.net/manual/en/function.htmlspecialchars.php) y +[htmlspecialchars_decode](http://www.php.net/manual/en/function.htmlspecialchars-decode.php). El problema con el uso +de estos métodos directamente es que se tiene que especificar la codificación y opciones extra cada vez. Ya que las +opciones siempre son las mismas y la codificación debe coincidir con la de la aplicación para prevenir problemas de +seguridad, Yii proporciona dos métodos simples y compactos: + +```php +$userName = Html::encode($user->name); +echo $userName; + +$decodedUserName = Html::decode($userName); +``` + +Formularios +----------- + +El trato con el marcado de formularios es una tarea repetitiva y propensa a errores. Por esto hay un grupo de métodos +para ayudar a gestionarlos. + +> Nota: hay que considerar la opción de usar [[yii\widgets\ActiveForm|ActiveForm]] en caso que se gestionen +formularios que requieran validaciones. + +### Abrir y cerrar un formulario + +Se puede abrir un formulario con el metodo [[yii\helpers\Html::beginForm()|beginForm()]] como se muestra a +continuación: + +```php + $id], 'post', ['enctype' => 'multipart/form-data']) ?> +``` + +El primer argumento es la URL a la que se enviaran los datos del formulario. Se puede especificar en formato de ruta +de Yii con los parámetros aceptados por [[yii\helpers\Url::to()|Url::to()]]. El segundo es el método que se usara. +`post` es el método predeterminado. El tercero es un array de opciones para la etiqueta `form`. En este caso cambiamos +el método de codificación del formulario de `data` en una petición POST a `multipart/form-data`. Esto se requiere +cuando se quieren subir archivos. + +El cierre de la etiqueta `form` es simple: + +```php + +``` + +### Botones + +Para generar botones se puede usar el siguiente código: + +```php + 'teaser']) ?> + 'submit']) ?> + 'reset']) ?> +``` + +El primer argumento para los tres métodos es el titulo del botón y el segundo son las opciones. El titulo no esta +codificado pero si se usan datos recibidos por el usuario, deben codificarse mediante +[[yii\helpers\Html::encode()|Html::encode()]]. + +### Inputs + +Hay dos grupos en los métodos input. Unos empiezan con `active` y se llaman inputs activos y los otros no empiezan +así. Los inputs activos obtienen datos del modelo y del atributo especificado y los datos de los inputs normales se +especifica directamente. + +Los métodos más genéricos son: + +```php +// type, input name, input value, options +name, ['class' => $username]) ?> + +// type, model, model attribute name, options + $username]) ?> +``` + +Si se conoce el tipo de input de antemano, es conveniente usar los atajos de métodos: + +- [[yii\helpers\Html::buttonInput()]] +- [[yii\helpers\Html::submitInput()]] +- [[yii\helpers\Html::resetInput()]] +- [[yii\helpers\Html::textInput()]], [[yii\helpers\Html::activeTextInput()]] +- [[yii\helpers\Html::hiddenInput()]], [[yii\helpers\Html::activeHiddenInput()]] +- [[yii\helpers\Html::passwordInput()]] / [[yii\helpers\Html::activePasswordInput()]] +- [[yii\helpers\Html::fileInput()]], [[yii\helpers\Html::activeFileInput()]] +- [[yii\helpers\Html::textarea()]], [[yii\helpers\Html::activeTextarea()]] + +Los botones de opción (Radios) y las casillas de verificación (checkboxes) se especifican de forma un poco diferente: + +```php + 'I agree']); + 'agreement']) + + 'I agree']); + 'agreement']) +``` + +Las listas desplegables (dropdown list) se pueden renderizar como se muestra a continuación: + +```php + + + + + +``` + +El primer argumento es el nombre del input, el segundo es el valor seleccionado actualmente y el tercero es el array +de pares clave-valor donde la clave es al lista de valores y el valor del array es la lista a mostrar. + +Si se quiere habilitar la selección múltiple, se puede usar la lista seleccionable (checkbox list): + +```php + + +``` + +Si no, se puede usar la lista de opciones (radio list): + +```php + + +``` + +### Labels y errores + +De forma parecida que en los imputs hay dos métodos para generar labels. El activo que obtiene los datos del modelo y +el no-activo que acepta datos directamente: + +```php + 'label username']) ?> + 'label username']) +``` + +Para mostrar los errores de un modelo o más en forma de resumen: + +```php + 'errors']) ?> +``` + +Para mostrar un error individual: + +```php + 'error']) ?> +``` + +### Nombres y valores + +Existen métodos para obtener nombres, IDs y valores para los campos de entrada (inputs) basados en el modelo. Estos se +usan principalmente internamente pero a veces pueden resultar prácticos: + +```php +// Post[title] +echo Html::getInputName($post, 'title'); + +// post-title +echo Html::getInputId($post, 'title'); + +// mi primer post +echo Html::getAttributeValue($post, 'title'); + +// $post->authors[0] +echo Html::getAttributeValue($post, '[0]authors[0]'); +``` + +En el ejemplo anterior, el primer argumento es el modelo y el segundo es el atributo de expresión. En su forma más +simple es su nombre de atributo pero podría ser un nombre de atributo prefijado y/o añadido como sufijo con los +indices de un array, esto se usa principalmente para mostrar inputs en formatos de tablas: + +- `[0]content` se usa en campos de entrada de datos en formato de tablas para representar el atributo "content" para + el primer modelo del input en formato de tabla; +- `dates[0]` representa el primer elemento del array del atributo "dates"; +- `[0]dates[0]` representa el primer elemento del array del atributo "dates" para el primer modelo en formato de tabla. + +Para obtener el nombre de atributo sin sufijos o prefijos se puede usar el siguiente código: + +```php +// dates +echo Html::getAttributeName('dates[0]'); +``` + +Estilos y scripts +----------------- + +Existen dos métodos para generar etiquetas que envuelvan estilos y scripts incrustados (embebbed): + +```php + + +// Genera + + + + true]); + +// Genera + + +``` + +Si se quiere enlazar un estilo externo desde un archivo CSS: + +```php + 'IE 5']) ?> + +// genera + + +``` + +El primer argumento es la URL. El segundo es un array de opciones. Adicionalmente, para regular las opciones se puede +especificar: + +- `condition` para envolver `` por lo que el sólo se + incluirá si el navegador no soporta JavaScript o si lo ha deshabilitado el usuario. + +Para enlazar un archivo JavaScript: + +```php + +``` + +Es igual que con las CSS, el primer argumento especifica el enlace al fichero que se quiere incluir. Las opciones se +pueden pasar como segundo argumento. En las opciones se puede especificar `condition` del mismo modo que se puede usar +para `cssFile`. + +Enlaces +------- + +Existe un método para generar hipervínculos a conveniencia: + +```php + $id], ['class' => 'profile-link']) ?> +``` + +El primer argumento es el titulo. No está codificado por lo que si se usan datos enviados por el usuario se tienen que +codificar usando `Html::encode()`. El segundo argumento es el que se introducirá en `href` de la etiqueta ` +``` + +Imagenes +-------- + +Para generar una etiqueta de tipo imagen se puede usar el siguiente ejemplo: + +```php + 'My logo']) ?> + +// genera + +My logo +``` + +Aparte de los [aliases](concept-aliases.md) el primer argumento puede aceptar rutas, parámetros y URLs. Del mismo modo +que [Url::to()](helper-url.md). + +Listas +------ + +Las listas desordenadas se puede generar como se muestra a continuación: + +```php + function($item, $index) { + return Html::tag( + 'li', + $this->render('post', ['item' => $item]), + ['class' => 'post'] + ); +}]) ?> +``` + +Para generar listas ordenadas se puede usar `Html::ol()` en su lugar.