HTML Öğeleri
************

.[perex]
[api: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:

```php
$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:

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

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

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


HTML Öğesi Oluşturma .[#toc-creating-an-html-element]
=====================================================

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

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

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

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

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

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

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

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


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

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

```php
$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:

```php
$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:

```php
$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:

```php
$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:

```php
$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:

```php
$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:

```php
$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:

```php
$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:

```php
$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:

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


Veri Öznitelikleri .[#toc-data-attributes]
------------------------------------------

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:

```php
$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:

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


Element İçeriği .[#toc-element-content]
=======================================

Öğ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.

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

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


Çocuk Düğümleri .[#toc-child-nodes]
-----------------------------------

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:

```php
$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:

```php
$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:

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

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

```php
// öğ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 .[#toc-creating-a-document-fragment]
------------------------------------------------------------

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

```php
$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:

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

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


HTML Çıktısı Oluşturma .[#toc-generating-html-output]
=====================================================

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:

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

Önemli bir özellik de [Çapraz Site Komut Dosyalarına (XSS) |nette:glossary#cross-site-scripting-xss] karşı otomatik korumadır. `setText()` veya `addText()` kullanılarak eklenen tüm öznitelik değerleri veya içerik güvenilir bir şekilde önlenir:

```php
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 .[#toc-conversion-html-text]
====================================================

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

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


HtmlStringable .[#toc-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.