HTML elemek

Data attribútumok

A data attribútumok speciális támogatást élveznek. Mivel nevük kötőjeleket tartalmaz, a property-ken és metódusokon keresztüli hozzáférés nem olyan elegáns, ezért létezik a data() metódus:

$el = Html::el('input');
$el->{'data-max-size'} = '500x300'; // nem annyira elegáns
$el->data('max-size', '500x300'); // elegáns
echo $el; // '<input data-max-size="500x300">'

Ha a data attribútum értéke tömb, automatikusan JSON-ba szerializálódik:

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

Elem tartalma

Az elem belső tartalmát a setHtml() vagy setText() metódusokkal állítjuk be. Az elsőt csak abban az esetben használja, ha biztosan tudja, hogy a paraméterben megbízhatóan biztonságos HTML stringet ad át.

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

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

És fordítva, a belső tartalmat a getHtml() vagy getText() metódusokkal kapjuk meg. A második eltávolítja a HTML tageket a kimenetből, és a HTML entitásokat karakterekké konvertálja.

echo $el->getHtml(); // '10 < 20'
echo $el->getText(); // '10 < 20'

Gyermek csomópontok

Az elem belseje lehet gyermek (children) csomópontok tömbje is. Mindegyikük lehet string vagy egy másik Html elem. Az addHtml() vagy addText() segítségével illesztjük be őket:

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

Egy másik mód új Html csomópont létrehozására és beillesztésére:

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

A csomópontokkal ugyanúgy lehet dolgozni, mintha tömbről lenne szó. Azaz hozzáférni az egyes elemekhez szögletes zárójelekkel, megszámolni őket a count() segítségével, és iterálni rajtuk:

$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

Új csomópontot lehet egy konkrét helyre beilleszteni az insert(?int $index, $child, bool $replace = false) segítségével. Ha a $replace = false, beilleszti az elemet az $index pozícióra, és a többit eltolja. Ha az $index = null, hozzáadja az elemet a végére.

// beilleszti az elemet az első pozícióra és a többit eltolja
$el->insert(0, Html::el('span'));

Az összes csomópontot a getChildren() metódussal kapjuk meg, és eltávolítjuk őket a removeChildren() metódussal.

Dokumentum fragmentum létrehozása

Ha csomópontok tömbjével akarunk dolgozni, és nem érdekel minket a burkoló elem, létrehozhatunk egy ún. dokumentum fragmentumot null átadásával az elem neve helyett:

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

Gyorsabb módot kínálnak a fragmentum létrehozására a fromHtml() és fromText() metódusok:

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

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

HTML kimenet generálása

A legegyszerűbb módja egy HTML elem kiírásának az echo használata vagy az objektum (string)-gé típuskonvertálása. Külön is kiírhatók a nyitó vagy záró tagek és attribútumok:

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

echo $el;               // '<div class="header">hello</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"'

Fontos jellemző az automatikus védelem a Cross Site Scripting (XSS) ellen. Minden attribútumérték vagy a setText() vagy addText() keresztül beillesztett tartalom megbízhatóan escapelve van:

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

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

HTML ↔ Szöveg konverzió

HTML szöveggé alakításához használhatja a htmlToText() statikus metódust:

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

HtmlStringable

A Nette\Utils\Html objektum implementálja a Nette\HtmlStringable interfészt, amellyel például a Latte vagy az űrlapok megkülönböztetik azokat az objektumokat, amelyek rendelkeznek a __toString() metódussal, amely HTML kódot ad vissza. Így nem történik dupla escapelés, ha például az objektumot kiírjuk a sablonban a {$el} segítségével.