HTML Öğeleri

Nette\Utils\Html sınıfı, Siteler Arası Komut Dosyası (XSS) güvenlik açığını önleyen HTML kodu oluşturmaya yönelik bir yardımcıdır.

Nesneleri HTML öğelerini temsil edecek şekilde çalışır, parametrelerini ayarlarız ve render edilmelerine izin veririz:

$el = Html::el('img'); // <img> öğesini oluşturur
$el->src = 'image.jpg'; // src özniteliğini ayarlar
echo $el; // '<img src="image.jpg">' yazdırır

Kurulum:

composer require nette/utils

Tüm örnekler aşağıdaki sınıf takma adının tanımlandığını varsayar:

use Nette\Utils\Html;

HTML Öğesi Oluşturma

Eleman Html::el() yöntemi kullanılarak oluşturulur:

$el = Html::el('img'); // <img> öğesini oluşturur

Adın yanı sıra, HTML sözdiziminde başka nitelikler de girebilirsiniz:

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

Ya da bunları ikinci parametreye ilişkisel bir dizi olarak aktarın:

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

Bir öğe adını değiştirmek ve döndürmek için:

$el->setName('img');
$el->getName(); // 'img'
$el->isEmpty(); // true, <img> boş bir eleman olduğu için

HTML Nitelikleri

Bireysel HTML niteliklerini üç şekilde ayarlayabilir ve alabilirsiniz, hangisini daha çok seveceğiniz size kalmış. Birincisi özellikler aracılığıyla:

$el->src = 'image.jpg'; // src özniteliğini ayarlar

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

unset($el->src); // özniteliği kaldırır
// veya $el->src = null;

İkinci yol, özellikleri ayarlamanın aksine, birbirlerine zincirleme bağlayabileceğimiz yöntemleri çağırmaktır:

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

$el->alt(null); // özniteliği kaldırır

Üçüncü yol ise en konuşkan olanıdır:

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

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

$el->removeAttribute('alt');

Toplu olarak, öznitelikler addAttributes(array $attrs) ile ayarlanabilir ve removeAttributes(array $attrNames) ile silinebilir.

Bir özniteliğin değeri yalnızca bir dize olmak zorunda değildir, mantıksal öznitelikler için mantıksal değerler de kullanılabilir:

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

Bir nitelik, örneğin CSS sınıfları için uygun olan, boşluklarla ayrılmış olarak listelenen bir belirteç dizisi de olabilir:

$el = Html::el('input');
$el->class[] = 'active';
$el->class[] = null; // null göz ardı edilir
$el->class[] = 'top';
echo $el; // '<input class="active top">'

Bir alternatif, değerlerin anahtarın listelenip listelenmeyeceğini belirttiği bir ilişkisel dizidir:

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

CSS stilleri ilişkisel diziler şeklinde yazılabilir:

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

Şimdi özellikleri kullandık, ancak aynı şey yöntemler kullanılarak da yapılabilir:

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

Ya da en konuşkan şekilde bile:

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

Son bir şey: href() yöntemi, bir URL'de sorgu parametreleri oluşturmayı kolaylaştırabilir:

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

Veri Öznitelikleri

Veri nitelikleri özel bir desteğe sahiptir. Adları tire içerdiğinden, özellikler ve yöntemler aracılığıyla erişim çok zarif değildir, bu nedenle data() yöntemi vardır:

$el = Html::el('input');
$el->{'data-max-size'} = '500x300'; // pek şık değil
$el->data('max-size', '500x300'); // zarif
echo $el; // '<input data-max-size="500x300">'

Veri özniteliğinin değeri bir dizi ise, otomatik olarak JSON'a serileştirilir:

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

Element İçeriği

Öğenin iç içeriği setHtml() veya setText() yöntemleri tarafından ayarlanır. İlkini yalnızca parametreye güvenli bir HTML dizesi aktardığınızı biliyorsanız kullanın.

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

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

Tersine, iç içerik getHtml() veya getText() yöntemleriyle elde edilir. İkincisi, HTML çıktısından etiketleri kaldırır ve HTML varlıklarını karakterlere dönüştürür.

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

Çocuk Düğümleri

Bir elemanın iç içeriği bir çocuk dizisi de olabilir. Bunların her biri bir dize ya da başka bir Html öğesi olabilir. Bunlar addHtml() veya addText() kullanılarak eklenir:

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

Yeni bir Html düğümü oluşturmanın ve eklemenin başka bir yolu:

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

Düğümlerle dizi öğeleriymiş gibi çalışabilirsiniz. Yani köşeli parantez kullanarak tek tek olanlara erişin, count() ile sayın ve üzerlerinde yineleyin:

$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

insert(?int $index, $child, bool $replace = false) kullanılarak belirli bir konuma yeni bir düğüm eklenebilir. $replace = false ise, öğeyi $index konumuna ekler ve diğerlerini taşır. Eğer $index = null ise, sonuna bir eleman ekler.

// öğeyi ilk konuma ekler ve diğerlerini ilerletir
$el->insert(0, Html::el('span'));

Tüm düğümler getChildren() yöntemi ile döndürülür ve removeChildren() yöntemi ile kaldırılır.

Belge Parçası Oluşturma

Bir dizi düğümle çalışmak istiyorsanız ve sarmalayan öğeyle ilgilenmiyorsanız, öğe adı yerine null adresini geçerek document fragment oluşturabilirsiniz:

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

fromHtml() ve fromText() yöntemleri bir parça oluşturmak için daha hızlı bir yol sunar:

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

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

HTML Çıktısı Oluşturma

Bir HTML öğesi oluşturmanın en kolay yolu echo adresini kullanmak veya bir nesneyi (string) adresine atamaktır. Ayrıca açılış veya kapanış etiketlerini ve niteliklerini ayrı ayrı yazdırabilirsiniz:

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

Önemli bir özellik de Çapraz Site Komut Dosyalarına (XSS) karşı otomatik korumadır. setText() veya addText() kullanılarak eklenen tüm öznitelik değerleri veya içerik güvenilir bir şekilde önlenir:

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

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

HTML ↔ Metin Dönüştürme

HTML'yi metne dönüştürmek için htmlToText() statik yöntemini kullanabilirsiniz:

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

HtmlStringable

Nette\Utils\Html nesnesi, örneğin Latte veya formların HTML kodu döndüren __toString() yöntemine sahip nesneleri ayırt etmek için kullandığı Nette\HtmlStringable arabirimini uygular. Dolayısıyla, örneğin şablondaki nesneyi {$el} kullanarak yazdırırsak çift kaçış oluşmaz.