Komponentový model

Důležitým pojmem v Nette je komponenta. Do stránek vkládáme vizuální interaktivní komponenty, komponentami jsou i formuláře nebo všechny jejich prvky. Základní dvě třídy, od kterých všechny tyto komponenty dědí, jsou součástí balíčku nette/component-model a mají za úkol vytvářet stromovou hierarchii komponent.

Component

Nette\ComponentModel\Component je společným předkem všech komponent. Obsahuje metody getName() vracející název komponenty a metodu getParent() vracející jejího rodiče. Obojí lze nastavit metodou setParent() – první parametr je rodič a druhý název komponenty.

lookup (?string $type, bool $throw=true): ?Component

Vyhledá v hierarchii směrem nahoru objekt požadované třídy nebo rozhraní. Například $component->lookup(Nette\Application\UI\Presenter::class) vrací presenter, pokud je k němu, i přes několik úrovní, komponenta připojena. Pokud žádný odpovídající objekt neexistuje, vyhodí výjimku; předáním false jako druhého argumentu místo toho vrátíte null. Když jako $type předáte null, metoda hledá nejvyšší komponentu ve stromu, tj. kořen bez rodiče.

lookupPath (?string $type=null, bool $throw=true): ?string

Vrací tzv. cestu, což je řetězec vzniklý spojením jmen všech komponent na cestě mezi aktuální a hledanou komponentou. Takže např. $component->lookupPath(Nette\Application\UI\Presenter::class) vrací jedinečný identifikátor komponenty vůči presenteru. Když je $type null (nebo vynechán), cesta se měří až ke kořeni stromu.

Container

Nette\ComponentModel\Container je rodičovská komponenta, tj. komponenta obsahující potomky a tvořící tak stromovou strukturu. Disponuje metodami pro snadné přidávání, získávání a odstraňování objektů. Je předkem například formuláře či tříd Control a Presenter. Potomci využívající trait ArrayAccess (například Control a Presenter) navíc umožňují přístup k potomkům zápisem pole, např. $container['child'].

addComponent (Component $component, ?string $name, ?string $insertBefore=null): static

Přidá komponentu do kontejneru jako potomka. Je-li $name roven null, použije se vlastní název komponenty. Volitelným $insertBefore – názvem existujícího potomka – vložíte novou komponentu těsně před něj; jinak se přidá na konec. Metoda vrací kontejner, takže lze volání řetězit.

removeComponent (Component $component): void

Odebere potomka z kontejneru.

getComponent (string $name): ?Component

Vrací komponentu. Při pokusu o získání nedefinovaného potomka je zavolána továrna createComponent($name). Metoda createComponent($name) zavolá v aktuální komponentě metodu createComponent<název komponenty> a jako parametr jí předá název komponenty. Vytvořená komponenta je poté přidána do aktuální komponenty jako její potomek. Těmto metodám říkáme továrny na komponenty a mohou je implementovat potomci třídy Container.

getComponents(): IComponent[]

Vrací přímé potomky jako pole; klíče obsahují názvy těchto komponent. Pro získání celého podstromu rekurzivně použijte getComponentTree(), případně v kombinaci s array_filter() pro filtrování podle typu. (Parametry $deep a $filterType známé ze starších verzí byly ve verzi 4.0 odstraněny.)

getComponentTree(): list<IComponent>

Získá celou hierarchii komponent včetně všech vnořených podřízených komponent jako indexované pole. Prohledávání jde nejprve do hloubky.

Monitorování předků

Komponentový model Nette umožňuje velmi dynamickou práci se stromem (komponenty můžeme vyjímat, přesouvat, přidávat), proto by byla chyba se spoléhat na to, že po vytvoření komponenty je hned (v konstruktoru) znám rodič, rodič rodiče atd. Většinou totiž rodič při vytvoření vůbec známý není.

Jak může komponenta zjistit okamžik, kdy je připojena pod presenter – nebo pod jiného předka daného typu? Sledovat přímého rodiče nestačí, protože spojení může nastat výš ve stromu, například když se připojí rodič rodiče. Přesně k tomu slouží metoda monitor($type, $attached, $detached): komponenta oznámí, že chce být upozorněna, kdykoli se nad ní ve stromu objeví předek třídy nebo rozhraní $type, nebo z něj zmizí. Komponenta může monitorovat libovolný počet typů; callback $attached se spustí při připojení odpovídajícího předka a dostane ho jako argument, callback $detached při jeho odpojení. Monitorování lze opět ukončit metodou unmonitor($type).

Oznámení kopírují strukturu stromu. Při připojování je předek uvědoměn dříve než jeho potomci (odshora dolů), takže rodič může nejprve připravit sdílený stav, případně potomka odebrat ještě předtím, než se spustí jeho vlastní callback. Při odpojování je pořadí opačné – nejdříve jsou uvědoměni potomci. Callbacky jsou navíc deduplikované, takže se stejný callback nikdy nezavolá dvakrát pro tentýž objekt. Důvody tohoto chování popisuje článek na blogu k verzi 4.0.

Pro lepší pochopení příklad: třída UploadControl, reprezentující formulářový prvek pro upload souborů v Nette Forms, musí formuláři nastavit atribut enctype na hodnotu multipart/form-data. V době vytvoření objektu ale k žádnému formuláři připojena být nemusí. Ve kterém okamžiku tedy formulář modifikovat? Řešení je jednoduché – v konstruktoru se požádá o monitoring:

class UploadControl extends Nette\Forms\Controls\BaseControl
{
	public function __construct($label)
	{
		$this->monitor(Nette\Forms\Form::class, function ($form): void {
			$form->setHtmlAttribute('enctype', 'multipart/form-data');
		});
		// ...
	}

	// ...
}

a jakmile je formulář k dispozici, zavolá se callback.