Elementos HTML
**************

.[perex]
La clase [api:Nette\Utils\Html] es una ayuda para generar código HTML que previene la vulnerabilidad Cross Site Scripting (XSS).


Funciona de tal forma que sus objetos representan elementos HTML, establecemos sus parámetros y dejamos que se rendericen:

```php
$el = Html::el('img');  // crea el elemento <img>.
$el->src = 'image.jpg'; // establece el atributo src
echo $el;               // imprime '<img src="imagen.jpg">'
```

Instalación:

```shell
composer require nette/utils
```

Todos los ejemplos asumen que el siguiente alias de clase está definido:

```php
use Nette\Utils\Html;
```


Creación de un elemento HTML .[#toc-creating-an-html-element]
=============================================================

El elemento se crea utilizando el método `Html::el()`:

```php
$el = Html::el('img'); // crea el elemento <img>
```

Además del nombre, puede introducir otros atributos en la sintaxis HTML:

```php
$el = Html::el('input type=text class="red important"');
```

O pasarlos como un array asociativo al segundo parámetro:

```php
$el = Html::el('input', [
	'type' => 'text',
	'class' => 'important',
]);
```

Para cambiar y devolver el nombre de un elemento:

```php
$el->setName('img');
$el->getName(); // 'img'
$el->isEmpty(); // true, as <img> is void element
```


Atributos HTML .[#toc-html-attributes]
======================================

Puedes establecer y obtener atributos HTML individuales de tres maneras, depende de quién te guste más. La primera es a través de las propiedades:

```php
$el->src = 'image.jpg'; // establece el atributo src

echo $el->src; // 'image.jpg'

unset($el->src);  // elimina el atributo
// or $el->src = null;
```

La segunda forma es llamar a métodos que, a diferencia de establecer propiedades, podemos encadenar:

```php
$el = Html::el('img')->src('image.jpg')->alt('photo');
// <img src="image.jpg" alt="photo">

$el->alt(null); // elimina el atributo
```

Y la tercera forma es la más locuaz:

```php
$el = Html::el('img')
	->setAttribute('src', 'image.jpg')
	->setAttribute('alt', 'photo');

echo $el->getAttribute('src'); // 'image.jpg'

$el->removeAttribute('alt');
```

En bloque, los atributos pueden fijarse con `addAttributes(array $attrs)` y borrarse con `removeAttributes(array $attrNames)`.

El valor de un atributo no tiene por qué ser sólo una cadena, también pueden utilizarse valores lógicos para atributos lógicos:

```php
$checkbox = Html::el('input')->type('checkbox');
$checkbox->checked = true;  // <input type="checkbox" checked>
$checkbox->checked = false; // <input type="checkbox">
```

Un atributo también puede ser una matriz de tokens, que se enumeran separados por espacios, lo que es adecuado para las clases CSS, por ejemplo:

```php
$el = Html::el('input');
$el->class[] = 'active';
$el->class[] = null; // se ignora null
$el->class[] = 'top';
echo $el; // '<input class="active top">'
```

Una alternativa es un array asociativo, donde los valores dicen si la clave debe ser listada:

```php
$el = Html::el('input');
$el->class['active'] = true;
$el->class['top'] = false;
echo $el; // '<input class="active">'
```

Los estilos CSS pueden escribirse en forma de matrices asociativas:

```php
$el = Html::el('input');
$el->style['color'] = 'green';
$el->style['display'] = 'block';
echo $el; // '<input style="color: green; display: block">'
```

Ahora hemos utilizado propiedades, pero se puede hacer lo mismo utilizando los métodos:

```php
$el = Html::el('input');
$el->style('color', 'green');
$el->style('display', 'block');
echo $el; // '<input style="color: green; display: block">'
```

O incluso de la forma más locuaz:

```php
$el = Html::el('input');
$el->appendAttribute('style', 'color', 'green');
$el->appendAttribute('style', 'display', 'block');
echo $el; // '<input style="color: green; display: block">'
```

Una última cosa: el método `href()` puede facilitar la composición de los parámetros de consulta en una URL:

```php
echo Html::el('a')->href('index.php', [
	'id' => 10,
	'lang' => 'en',
]);
// '<a href="index.php?id=10&amp;lang=en"></a>'
```


Atributos de datos .[#toc-data-attributes]
------------------------------------------

Los atributos de datos tienen un soporte especial. Debido a que sus nombres contienen guiones, el acceso a través de propiedades y métodos no es tan elegante, por lo que existe un método `data()`:

```php
$el = Html::el('input');
$el->{'data-max-size'} = '500x300'; // not so elegant
$el->data('max-size', '500x300'); // is elegant
echo $el; // '<input data-max-size="500x300">'
```

Si el valor del atributo de datos es un array, se serializa automáticamente a JSON:

```php
$el = Html::el('input');
$el->data('items', [1,2,3]);
echo $el; // '<input data-items="[1,2,3]">'
```


Contenido del elemento .[#toc-element-content]
==============================================

El contenido interno del elemento se establece mediante los métodos `setHtml()` o `setText()`. Utilice el primero sólo si sabe que está pasando de forma fiable una cadena HTML segura en el parámetro.

```php
echo Html::el('span')->setHtml('hello<br>');
// '<span>hello<br></span>'

echo Html::el('span')->setText('10 < 20');
// '<span>10 &lt; 20</span>'
```

Por el contrario, el contenido interno se obtiene mediante los métodos `getHtml()` o `getText()`. El segundo elimina las etiquetas de la salida HTML y convierte las entidades HTML en caracteres.

```php
echo $el->getHtml(); // '10 &lt; 20'
echo $el->getText(); // '10 < 20'
```


Nodos hijos .[#toc-child-nodes]
-------------------------------

El contenido interno de un elemento también puede ser un array de hijos. Cada uno de ellos puede ser una cadena u otro elemento de `Html`. Se insertan utilizando `addHtml()` o `addText()`:

```php
$el = Html::el('span')
	->addHtml('hello<br>')
	->addText('10 < 20')
	->addHtml( Html::el('br') );
// <span>hello<br>10 &lt; 20<br></span>
```

Otra forma de crear e insertar un nuevo nodo `Html`:

```php
$ul = Html::el('ul');
$ul->create('li', ['class' => 'first'])
	->setText('hello');
// <ul><li class="first">hello</li></ul>
```

Puedes trabajar con nodos como si fueran elementos de un array. Así que accede a los individuales usando corchetes, cuéntalos con `count()` e itera sobre ellos:

```php
$el = Html::el('div');
$el[] = '<b>hello</b>';
$el[] = Html::el('span');
echo $el[1]; // '<span></span>'

foreach ($el as $child) { /* ... */ }

echo count($el); // 2
```

Se puede insertar un nuevo nodo en una posición específica utilizando `insert(?int $index, $child, bool $replace = false)`. Si `$replace = false`, inserta el elemento en la posición `$index` y desplaza los demás. Si `$index = null`, añadirá un elemento al final.

```php
// inserta el elemento en la primera posición y avanza los demás
$el->insert(0, Html::el('span'));
```

Todos los nodos son devueltos por el método `getChildren()` y eliminados por el método `removeChildren()`.


Creación de un fragmento de documento .[#toc-creating-a-document-fragment]
--------------------------------------------------------------------------

Si desea trabajar con una matriz de nodos y no está interesado en el elemento envolvente, puede crear un llamado *fragmento de documento* pasando `null` en lugar del nombre del elemento:

```php
$el = Html::el(null)
	->addHtml('hello<br>')
	->addText('10 < 20')
	->addHtml( Html::el('br') );
// hello<br>10 &lt; 20<br>
```

Los métodos `fromHtml()` y `fromText()` ofrecen una forma más rápida de crear un fragmento:

```php
$el = Html::fromHtml('hello<br>');
echo $el; // 'hello<br>'

$el = Html::fromText('10 < 20');
echo $el; // '10 &lt; 20'
```


Generar salida HTML .[#toc-generating-html-output]
==================================================

La forma más sencilla de generar un elemento HTML es utilizar `echo` o lanzar un objeto a `(string)`. También puede imprimir etiquetas de apertura o cierre y atributos por separado:

```php
$el = Html::el('div class=header')->setText('hello');

echo $el;               // '<div class="header"></div>'
$s = (string) $el;      // '<div class="header">hello</div>'
$s = $el->toHtml();     // '<div class="header">hello</div>'
$s = $el->toText();     // 'hello'
echo $el->startTag();   // '<div class="header">'
echo $el->endTag();     // '</div>'
echo $el->attributes(); // 'class="header"'
```

Una característica importante es la protección automática contra [Cross Site Scripting (XSS) |nette:glossary#cross-site-scripting-xss]. Todos los valores de atributos o contenidos insertados mediante `setText()` o `addText()` se escapan de forma fiable:

```php
echo Html::el('div')
	->title('" onmouseover="bad()')
	->setText('<script>bad()</script>');

// <div title='" onmouseover="bad()'>&lt;script&gt;bad()&lt;/script&gt;</div>
```


Conversión HTML ↔ Texto .[#toc-conversion-html-text]
====================================================

Puede utilizar el método estático `htmlToText()` para convertir HTML en texto:

```php
echo Html::htmlToText('<span>One &amp; Two</span>'); // 'One & Two'
```


HtmlStringable .[#toc-htmlstringable]
=====================================

El objeto `Nette\Utils\Html` implementa la interfaz `Nette\HtmlStringable`, que, por ejemplo, Latte o forms utilizan para distinguir los objetos que tienen un método `__toString()` que devuelve código HTML. Así, el doble escape no se produce si, por ejemplo, imprimimos el objeto en la plantilla utilizando `{$el}`.