Spanish guide Html helper

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)

docs/guide-es/helper-html.md

+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 <a name="basics"></a>
+----------------------------
+
+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
+<?= Html::tag('p', Html::encode($user->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
+<p class="username">samdark</p>
+```
+
+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á 
+// <div class="btn btn-success">Pwede na</div>
+```
+
+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 <a name="encoding-and-decoding-content"></a>
+-------------------------------------------
+
+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
+<?= Html::beginForm(['order/update', 'id' => $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
+<?= Html::endForm() ?>
+```
+
+### Botones
+
+Para generar botones se puede usar el siguiente código:
+
+```php
+<?= Html::button('Press me!', ['class' => 'teaser']) ?>
+<?= Html::submitButton('Submit', ['class' => 'submit']) ?>
+<?= Html::resetButton('Reset', ['class' => '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
+<?= Html::input('text', 'username', $user->name, ['class' => $username]) ?>
+
+// type, model, model attribute name, options
+<?= Html::activeInput('text', $user, 'name', ['class' => $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
+<?= Html::radio('agree', true, ['label' => 'I agree']);
+<?= Html::activeRadio($model, 'agree', ['class' => 'agreement'])
+
+<?= Html::checkbox('agree', true, ['label' => 'I agree']);
+<?= Html::activeCheckbox($model, 'agree', ['class' => 'agreement'])
+```
+
+Las listas desplegables (dropdown list) se pueden renderizar como se muestra a continuación:
+
+```php
+<?= Html::dropDownList('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?>
+<?= Html::activeDropDownList($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>
+
+<?= Html::listBox('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?>
+<?= Html::activeListBox($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>
+```
+
+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
+<?= Html::checkboxList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?>
+<?= Html::activeCheckboxList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>
+```
+
+Si no, se puede usar la lista de opciones (radio list):
+
+```php
+<?= Html::radioList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?>
+<?= Html::activeRadioList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>
+```
+
+### 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
+<?= Html::label('User name', 'username', ['class' => 'label username']) ?>
+<?= Html::activeLabel($user, 'username', ['class' => 'label username'])
+```
+
+Para mostrar los errores de un modelo o más en forma de resumen:
+
+```php
+<?= Html::errorSummary($posts, ['class' => 'errors']) ?>
+```
+
+Para mostrar un error individual:
+
+```php
+<?= Html::error($post, 'title', ['class' => '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
+<?= Html::style('.danger { color: #f00; }') ?>
+
+// Genera
+
+<style>.danger { color: #f00; }</style>
+
+<?= Html::script('alert("Hello!");', ['defer' => true]);
+
+// Genera
+
+<script defer>alert("Hello!");</script>
+```
+
+Si se quiere enlazar un estilo externo desde un archivo CSS:
+
+```php
+<?= Html::cssFile('@web/css/ie5.css', ['condition' => 'IE 5']) ?>
+
+// genera
+
+<!--[if IE 5]>
+    <link href="http://example.com/css/ie5.css" />
+<![endif]-->
+```
+
+El primer argumento es la URL. El segundo es un array de opciones. Adicionalmente, para regular las opciones se puede 
+especificar:
+
+- `condition` para envolver `<link` con los comentarios condicionales con condiciones especificas. Esperamos que sean 
+  necesarios los comentarios condicionales ;)
+- `noscript` se puede establecer como `true` para envolver `<link` con la etiqueta `<noscript>` 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
+<?= Html::jsFile('@web/js/main.js') ?>
+```
+
+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
+<?= Html::a('Profile', ['user/view', 'id' => $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 `<a`. Se 
+puede revisar [Url::to()](helper-url.md) para obtener más detalles de los valores que acepta. El tercer argumento es 
+un array de las propiedades de la etiqueta.
+
+Si se requiere generar enlaces de tipo `mailto` se puede usar el siguiente código:
+
+```php
+<?= Html::mailto('Contact us', 'admin@example.com') ?>
+```
+
+Imagenes
+--------
+
+Para generar una etiqueta de tipo imagen se puede usar el siguiente ejemplo:
+
+```php
+<?= Html::img('@web/images/logo.png', ['alt' => 'My logo']) ?>
+
+// genera
+
+<img src="http://example.com/images/logo.png" alt="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
+<?= Html::ul($posts, ['item' => 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.
\ No newline at end of file