URL linkek létrehozása

Az kétirányú routingnak köszönhetően soha nem kell majd keményen beírnia az alkalmazás URL-címeit a sablonokba vagy a kódba, amelyek később megváltozhatnak, vagy bonyolultan összeállítani őket. A linkben elegendő megadni a presentert és az akciót, átadni az esetleges paramétereket, és a keretrendszer maga generálja az URL-t. Valójában nagyon hasonlít egy függvényhívásra. Ez tetszeni fog Önnek.

A presenter sablonjában

Leggyakrabban sablonokban hozunk létre linkeket, és nagyszerű segítő az n:href attribútum:

<a n:href="Product:show">részletek</a>

Figyelje meg, hogy a HTML href attribútum helyett az n:attribútumot n:href használtuk. Ennek értéke nem URL, ahogy az href attribútum esetében lenne, hanem a presenter és az akció neve.

Egy linkre kattintás, leegyszerűsítve, olyan, mintha a ProductPresenter::renderShow() metódust hívnánk meg. És ha annak szignatúrájában paraméterek vannak, argumentumokkal hívhatjuk meg:

<a n:href="Product:show $product->id, $product->slug">termék részletei</a>

Lehetőség van elnevezett paraméterek átadására is. A következő link a lang paramétert adja át cs értékkel:

<a n:href="Product:show $product->id, lang: cs">termék részletei</a>

Ha a ProductPresenter::renderShow() metódusnak nincs $lang a szignatúrájában, a paraméter értékét a $lang = $this->getParameter('lang') segítségével vagy a property-ből tudhatja meg.

Ha a paraméterek tömbben vannak tárolva, kibonthatók a ... operátorral (Latte 2.x-ben az (expand) operátorral):

{var $args = [$product->id, lang => cs]}
<a n:href="Product:show ...$args">termék részletei</a>

A linkekben automatikusan átadódnak az ún. perzisztens paraméterek is.

Az n:href attribútum nagyon praktikus a HTML <a> tag-ekhez. Ha máshol szeretnénk kiírni a linket, például szövegben, használjuk a {link}-et:

A cím: {link Home:default}

A kódban

Link létrehozásához a presenterben a link() metódus szolgál:

$url = $this->link('Product:show', $product->id);

A paramétereket tömb segítségével is át lehet adni, ahol elnevezett paramétereket is meg lehet adni:

$url = $this->link('Product:show', [$product->id, 'lang' => 'cs']);

Linkeket presenter nélkül is lehet létrehozni, erre való a LinkGenerator és annak link() metódusa.

Linkek presenterhez

Ha a link célja egy presenter és egy akció, akkor a szintaxisa a következő:

[//] [[[[:]module:]presenter:]action | this] [#fragment]

A formátumot minden Latte tag és minden presenter metódus támogatja, amely linkekkel dolgozik, tehát n:href, {link}, {plink}, link(), lazyLink(), isLinkCurrent(), redirect(), redirectPermanent(), forward(), canonicalize() és a LinkGenerator is. Tehát még ha a példákban n:href szerepel is, bármelyik függvény lehetne ott.

Az alapforma tehát Presenter:action:

<a n:href="Home:default">kezdőlap</a>

Ha az aktuális presenter akciójára hivatkozunk, kihagyhatjuk a nevét:

<a n:href="default">kezdőlap</a>

Ha a cél a default akció, kihagyhatjuk, de a kettőspontnak maradnia kell:

<a n:href="Home:">kezdőlap</a>

A linkek más modulokba is mutathatnak. Itt a linkeket megkülönböztetjük relatívakra egy beágyazott almodulba, vagy abszolútakra. Az elv analóg a lemezen lévő elérési utakkal, csak perjelek helyett kettőspontok vannak. Tegyük fel, hogy az aktuális presenter a Front modul része, akkor így írjuk:

<a n:href="Shop:Product:show">link a Front:Shop:Product:show-ra</a>
<a n:href=":Admin:Product:show">link az Admin:Product:show-ra</a>

Speciális eset a saját magára mutató link, amikor célként a this-t adjuk meg.

<a n:href="this">frissítés</a>

Hivatkozhatunk az oldal egy bizonyos részére az ún. fragment segítségével a kettőskereszt # jel után:

<a n:href="Home:#main">link a Home:default-ra és a #main fragmentre</a>

Abszolút utak

A link() vagy n:href segítségével generált linkek mindig abszolút utak (azaz / jellel kezdődnek), de nem abszolút URL-ek protokollal és domainnel, mint https://domain.

Abszolút URL generálásához adjon hozzá két perjelet az elejére (pl. n:href="//Home:"). Vagy átkapcsolhatja a presentert, hogy csak abszolút linkeket generáljon a $this->absoluteUrls = true beállításával.

Link az aktuális oldalra

A this cél linket hoz létre az aktuális oldalra:

<a n:href="this">frissítés</a>

Ugyanakkor átadódnak az összes paraméter, amelyek a action<Action>() vagy render<View>() metódus szignatúrájában szerepelnek, ha az action<Action>() nincs definiálva. Tehát ha a Product:show oldalon vagyunk és id: 123, a this-re mutató link ezt a paramétert is átadja.

Természetesen a paramétereket közvetlenül is meg lehet adni:

<a n:href="this refresh: 1">frissítés</a>

Az isLinkCurrent() függvény ellenőrzi, hogy a link célja megegyezik-e az aktuális oldallal. Ezt például a sablonban lehet használni a linkek megkülönböztetésére stb.

A paraméterek ugyanazok, mint a link() metódusnál, de ezen felül lehetőség van egy konkrét akció helyett a * helyettesítő karakter megadására, amely az adott presenter bármely akcióját jelenti.

{if !isLinkCurrent('Admin:login')}
	<a n:href="Admin:login">Jelentkezzen be</a>
{/if}

<li n:class="isLinkCurrent('Product:*') ? active">
	<a n:href="Product:">...</a>
</li>

Az n:href-fel kombinálva egy elemen belül használható a rövidített forma:

<a n:class="isLinkCurrent() ? active" n:href="Home:">...</a>

A * helyettesítő karakter csak az akció helyett használható, a presenter helyett nem.

Annak megállapítására, hogy egy adott modulban vagy annak almoduljában vagyunk-e, használjuk az isModuleCurrent(moduleName) metódust.

<li n:class="isModuleCurrent('Forum:Users') ? active">
	<a n:href="Product:">...</a>
</li>

Linkek signálhoz

A link célja nemcsak presenter és akció lehet, hanem signál is (ezek a handle<Signal>() metódust hívják). Ekkor a szintaxis a következő:

[//] [sub-component:]signal! [#fragment]

A signált tehát a felkiáltójel különbözteti meg:

<a n:href="click!">signál</a>

Lehet linket létrehozni egy alkomponens (vagy al-alkomponens) signáljára is:

<a n:href="componentName:click!">signál</a>

Linkek a komponensben

Mivel a komponensek önálló, újrafelhasználható egységek, amelyeknek nem kellene semmilyen kapcsolatban állniuk a környező presenterekkel, a linkek itt egy kicsit másképp működnek. A Latte n:href attribútuma és a {link} tag, valamint a komponens metódusai, mint a link() és mások, a link célját mindig signál névként kezelik. Ezért még a felkiáltójelet sem kell megadni:

<a n:href="click">signál, nem akció</a>

Ha a komponens sablonjában presenterekre szeretnénk hivatkozni, használjuk a {plink} taget:

<a href={plink Home:default}>kezdőlap</a>

vagy a kódban

$this->getPresenter()->link('Home:default')

Aliasok

Néha hasznos lehet egy könnyen megjegyezhető aliast rendelni egy Presenter:akció párhoz. Például a Front:Home:default kezdőlapot egyszerűen home-nak nevezni, vagy az Admin:Dashboard:default-ot admin-nak.

Az aliasokat a konfigurációban definiáljuk az application › aliases kulcs alatt:

application:
    aliases:
        home: Front:Home:default
        admin: Admin:Dashboard:default
        sign: Front:Sign:in

A linkekben ezután a kukac jellel írjuk őket, például:

<a n:href="@admin">adminisztráció</a>

Támogatottak minden olyan metódusban is, amely linkekkel dolgozik, mint a redirect() és hasonlók.

Érvénytelen linkek

Előfordulhat, hogy érvénytelen linket hozunk létre – vagy azért, mert nem létező presenterhez vezet, vagy azért, mert több paramétert ad át, mint amennyit a célmetódus a szignatúrájában elfogad, vagy ha a célakcióhoz nem lehet URL-t generálni. Az érvénytelen linkek kezelését a Presenter::$invalidLinkMode statikus változó határozza meg. Ez a következő értékek kombinációját veheti fel (konstansok):

• Presenter::InvalidLinkSilent – csendes mód, URL-ként a # karaktert adja vissza
• Presenter::InvalidLinkWarning – E_USER_WARNING figyelmeztetést dob, amely éles módban logolásra kerül, de nem szakítja meg a szkript futását
• Presenter::InvalidLinkTextual – vizuális figyelmeztetés, a hibát közvetlenül a linkbe írja
• Presenter::InvalidLinkException – InvalidLinkException kivételt dob

Az alapértelmezett beállítás InvalidLinkWarning éles módban és InvalidLinkWarning | InvalidLinkTextual fejlesztői módban. Az InvalidLinkWarning éles környezetben nem szakítja meg a szkript futását, de a figyelmeztetés logolásra kerül. Fejlesztői környezetben a Tracy elfogja és bluescreen-t jelenít meg. Az InvalidLinkTextual úgy működik, hogy URL-ként egy hibaüzenetet ad vissza, amely #error: karakterekkel kezdődik. Hogy az ilyen linkek első pillantásra észrevehetők legyenek, adjunk hozzá a CSS-hez:

a[href^="#error:"] {
	background: red;
	color: white;
}

Ha nem szeretnénk, hogy fejlesztői környezetben figyelmeztetések keletkezzenek, beállíthatjuk a csendes módot közvetlenül a konfigurációban.

application:
	silentLinks: true

LinkGenerator

Hogyan hozzunk létre linkeket hasonló kényelemmel, mint a link() metódus, de presenter jelenléte nélkül? Erre való a Nette\Application\LinkGenerator.

A LinkGenerator egy szolgáltatás, amelyet a konstruktoron keresztül kérhetünk, majd a link() metódusával hozhatunk létre linkeket.

A presenterekkel szemben itt van egy különbség. A LinkGenerator minden linket rögtön abszolút URL-ként hoz létre. Továbbá nincs “aktuális presenter”, így nem lehet célként csak az akció nevét megadni (link('default')) vagy relatív utakat megadni a modulokhoz.

Az érvénytelen linkek mindig Nette\Application\UI\InvalidLinkException-t dobnak.