Elemente HTML
*************

.[perex]
Clasa [api:Nette\Utils\Html] este un ajutor pentru generarea de cod HTML care previne vulnerabilitatea Cross Site Scripting (XSS).


Funcționează în așa fel încât obiectele sale reprezintă elemente HTML, le setăm parametrii și le lăsăm să se redea:

```php
$el = Html::el('img');  // creează elementul <img>
$el->src = 'image.jpg'; // stabilește atributul src
echo $el;               // tipărește '<img src="image.jpg">'
```

Instalare:

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

Toate exemplele presupun că este definit următorul alias de clasă:

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


Crearea unui element HTML .[#toc-creating-an-html-element]
==========================================================

Elementul este creat folosind metoda `Html::el()`:

```php
$el = Html::el('img'); // creează elementul <img>
```

În plus față de nume, puteți introduce și alte atribute în sintaxa HTML:

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

Sau treceți-le ca o matrice asociativă la al doilea parametru:

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

Pentru a modifica și a returna un nume de element:

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


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

Puteți seta și obține atribute HTML individuale în trei moduri, depinde de dumneavoastră care vă place mai mult. Primul este prin intermediul proprietăților:

```php
$el->src = 'image.jpg'; // stabilește atributul src

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

unset($el->src);  // elimină atributul
// sau $el->src = null;
```

Al doilea mod este de a apela metode care, spre deosebire de setarea proprietăților, putem să le înlănțuim:

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

$el->alt(null); // elimină atributul
```

Iar al treilea mod este cel mai vorbăreț:

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

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

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

În bloc, atributele pot fi setate cu `addAttributes(array $attrs)` și șterse cu `removeAttributes(array $attrNames)`.

Valoarea unui atribut nu trebuie să fie neapărat un șir de caractere, ci se pot utiliza și valori logice pentru atributele logice:

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

Un atribut poate fi, de asemenea, o matrice de simboluri, care sunt listate separate prin spații, ceea ce este potrivit pentru clasele CSS, de exemplu:

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

O alternativă este un tablou asociativ, în care valorile indică dacă cheia trebuie să fie listată sau nu:

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

Stilurile CSS pot fi scrise sub formă de tablouri asociative:

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

Am folosit acum proprietățile, dar același lucru se poate face și cu ajutorul metodelor:

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

Sau chiar în cel mai vorbăreț mod:

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

Un ultim lucru: metoda `href()` poate facilita compunerea parametrilor de interogare într-un URL:

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


Atribute de date .[#toc-data-attributes]
----------------------------------------

Atributele de date au un suport special. Deoarece numele lor conțin cratime, accesul prin intermediul proprietăților și metodelor nu este atât de elegant, așa că există o metodă `data()`:

```php
$el = Html::el('input');
$el->{'data-max-size'} = '500x300'; // nu atât de elegant
$el->data('max-size', '500x300'); // este elegant
echo $el; // '<input data-max-size="500x300">'
```

Dacă valoarea atributului de date este o matrice, aceasta este serializată automat în JSON:

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


Conținutul elementului .[#toc-element-content]
==============================================

Conținutul interior al elementului este stabilit prin metodele `setHtml()` sau `setText()`. Folosiți prima metodă numai dacă știți că transmiteți în mod fiabil un șir HTML securizat în parametru.

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

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

Dimpotrivă, conținutul interior este obținut prin metodele `getHtml()` sau `getText()`. Cea de-a doua elimină etichetele din ieșirea HTML și convertește entitățile HTML în caractere.

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


Noduri copil .[#toc-child-nodes]
--------------------------------

Conținutul interior al unui element poate fi, de asemenea, o matrice de copii. Fiecare dintre ei poate fi fie un șir de caractere, fie un alt element `Html`. Aceștia sunt introduși cu ajutorul `addHtml()` sau `addText()`:

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

O altă modalitate de a crea și insera un nou nod `Html`:

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

Puteți lucra cu nodurile ca și cum ar fi elemente de matrice. Deci, accesați-le pe cele individuale folosind paranteze pătrate, numărați-le cu `count()` și iterați peste ele:

```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
```

Un nou nod poate fi inserat într-o anumită poziție folosind `insert(?int $index, $child, bool $replace = false)`. Dacă `$replace = false`, se inserează elementul la poziția `$index` și se mută celelalte. În cazul în care `$index = null`, se adaugă un element la sfârșit.

```php
// inserează elementul în prima poziție și avansează celelalte.
$el->insert(0, Html::el('span'));
```

Toate nodurile sunt returnate prin metoda `getChildren()` și eliminate prin metoda `removeChildren()`.


Crearea unui fragment de document .[#toc-creating-a-document-fragment]
----------------------------------------------------------------------

Dacă doriți să lucrați cu o matrice de noduri și nu vă interesează elementul de înfășurare, puteți crea un așa-numit *fragment de document*, trecând `null` în locul numelui elementului:

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

Metodele `fromHtml()` și `fromText()` oferă o modalitate mai rapidă de a crea un fragment:

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

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


Generarea de ieșire HTML .[#toc-generating-html-output]
=======================================================

Cel mai simplu mod de a genera un element HTML este de a utiliza `echo` sau de a transforma un obiect în `(string)`. De asemenea, puteți imprima separat etichetele și atributele de deschidere sau de închidere:

```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"'
```

O caracteristică importantă este protecția automată împotriva [Cross Site Scripting (XSS |nette:glossary#cross-site-scripting-xss]). Toate valorile atributului sau conținutul inserat folosind `setText()` sau `addText()` sunt scăpate în mod fiabil:

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

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


Conversie HTML ↔ Text .[#toc-conversion-html-text]
==================================================

Puteți utiliza metoda statică `htmlToText()` pentru a converti HTML în text:

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


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

Obiectul `Nette\Utils\Html` implementează interfața `Nette\HtmlStringable`, pe care, de exemplu, Latte sau formularele o folosesc pentru a distinge obiectele care au o metodă `__toString()` care returnează codul HTML. Astfel, scăparea dublă nu apare dacă, de exemplu, imprimăm obiectul din șablon folosind `{$el}`.