html-elements.texy

HTML elementy
*************

.[perex]
Třída [Nette\Utils\Html |api:] je pomocník pro generování HTML kódu.

/--php
use Nette\Utils\Html;

$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
\--

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

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

Téhož lze dosáhnout i voláním metod. V takovém případě lze využít zřetězených volání (fluent interfaces):

/--php
// <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:

/--php
$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,
]);
\--

Důležitým rysem je automatická ochrana proti [Cross Site Scriptingu (XSS) |vulnerability-protection#toc-cross-site-scripting-xss]:

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

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

/--php
$checkbox = Html::el('input')->type('checkbox');
$checkbox->checked = TRUE; // <input type="checkbox" checked="checked" />
$checkbox->checked = FALSE; // <input type="checkbox" />

// použití pole
$el->class[] = $active ? 'active' : NULL; // NULL se ignoruje
$el->class[] = 'top';
// alternativně $el->class['top'] = TRUE; nebo $el->class('top', TRUE);

$el->style['color'] = 'green'; // obdobně $el->style('color', 'green');
$el->style['display'] = 'block';

echo $el;
// <input class="active top" style="color: green; display: block" />
\--


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

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


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

/---html
<img src="img.jpg" data-max-size="500x300" />
\---

Obvykle pak hodnoty těchto atributů využívá JavaScript. A fungují ve všech prohlížečích.

Třída Html disponuje přímou podporou pro datové atributy z HTML5:

/--php
$el = Html::el('img');
$el->data['max-size'] = '500x300';
// nebo
$el->data('max-size', '500x300');
\--


Obsah elementů
--------------

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

/--php
echo Html::el('a')->href('#')->setText('link<br>');
// <a href="#">link&lt;br&gt;</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 textový obsah elementu lze metodami `getText()` či `getHtml()`.

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

/--php
$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->add( Html::el('br') ); // $el[] = Html::el('br');

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

// vložíme do <div> textový uzel
$el->add('<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:

/--php
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:

/--php
$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>
\--


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

/--php
$el = Html::el('input')->disabled(TRUE);
echo $el; // <input disabled>
Html::$xhtml = TRUE;
echo $el; // <input disabled="disabled" />
\--


{{toc: title}}
{{composer: nette/utils}}