HTML elementy

Třída Nette\Utils\Html je pomocník pro generování HTML kódu, který nedovolí vznik zranitelnosti Cross Site Scripting (XSS).

Instalace:

composer require nette/utils

Všechny příklady předpokládají vytvořený alias:

use Nette\Utils\Html;

Základní použití

$el = Html::el('img'); // vytvoří element <img>
$el->src = 'image.jpg'; // nastaví atribut src
echo $el; // vypíše <img src="image.jpg">

echo $el->getName(); // vrací 'img', název elementu
echo $el->isEmpty(); // vrací true, jelikož <img> je prázdný element

HTML atributy

Měnit a číst atributy HTML elementu je možné skrze properties objektu. Zrušit je můžeme funkcí unset nebo přiřazením hodnoty null:

$el->src = 'image.jpg'; // nastaví atribut src
echo $el->src; // vypíše 'image.jpg'
unset($el->src); // nebo $el->src = null; - zruší atribut src

Druhou možností je volání metod:

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

Atributy lze také nastavit hromadně, dokonce přímo při vytváření elementu těmito způsoby:

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

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

$el->addAttributes([ // hromadné nastavení dalších atributů
	'value' => $val,
	'required' => true,
]);

Hodnotou atributu nemusí být jen řetězec, lze používat i logické hodnoty:

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

nebo také pole:

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

// alternativně:
$el = Html::el('input');
$el->class['active'] = (bool) $active;
$el->class['top'] = true; // nebo $el->class('top', true);
echo $el; // <input class="active top">

// další příklad:
$el = Html::el('input');
$el->style['color'] = 'green';
$el->style['display'] = 'block';
echo $el; // <input style="color: green; display: block">

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

V HTML5 lze používat tzv. datové atributy pro uživatelská data:

$el = Html::el('input');
$el->{'data-max-size'} = '500x300';
// nebo
$el->data('max-size', '500x300');

echo $el; // <input data-max-size="500x300">

Pokud je hodnotou datového attributu pole, automaticky se serializuje do JSONu:

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

Metoda href() umí usnadnit skládání URL:

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

Obsah elementů

Obsah elementu můžeme nastavit metodami setText() či setHtml() nebo přímo při vytváření elementu:

echo Html::el('a')->href('#')->setText('jedna < dva');
// <a href="#">jedna &lt; dva</a>

echo Html::el('a')->href('#')->setHtml('link<br>');
// <a href="#">link<br></a>

echo Html::el('strong', 'Nette');
// <strong>Nette</strong> odpovídá použití setText()

Získat obsah elementu lze metodami getText() či getHtml().

Obsahem však mohou být i další elementy:

$el = Html::el('div');

// vložíme do <div> nový element <strong>
$strong = $el->create('strong', 'Nette');
// nebo $el->create('strong')->setText('Nette')

// vložíme do <div> hotový Html object
$el->addHtml( Html::el('br') ); // $el[] = Html::el('br');

echo $el; // <div><strong>Nette</strong><br></div>

// vložíme do <div> textový uzel
$el->addHtml('<i>Yes!</i>'); // na rozdíl od setHtml() nesmaže obsah elementu

$el->insert(0, Html::el('span')); // vloží prvek na první pozici

Všechny prvky odstraní metoda removeChildren().

S dětmi lze pracovat stejně, jako by se jednalo o pole. Včetně iterace:

echo $el[2]; // <br>

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

echo count($el); // 4 - počet dětí

Generování HTML výstupu

Nejjednodušším způsobem, jak vypsat HTML element, je použít echo nebo objekt přetypovat na řetězec operátorem (string). Lze také samostatně vypsat otevírací nebo uzavírací značky:

$el = Html::el('div class=header');

echo $el; // <div class="header"></div>
$s = (string) $el; // vloží do $s řetězec '<div class="header"></div>'
echo $el->startTag(); // <div class="header">
echo $el->endTag(); // </div>

Důležitým rysem je automatická ochrana proti Cross Site Scriptingu (XSS):

echo Html::el('input')->value('<script>alert()</script>');
// <input value="&lt;script&gt;alert()&lt;/script&gt;">

Výstupní formát určuje statická proměnná Html::$xhtml. Výchozím nastavením je false, tj. HTML výstup.

$el = Html::el('input')->disabled(true);
echo $el; // <input disabled>
Html::$xhtml = true;
echo $el; // <input disabled="disabled" />s

Konverze HTML ↔ text

Převod z HTML do textu:

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