URL hivatkozások létrehozása

A kétirányú útválasztásnak köszönhetően soha nem kell a sablonokban vagy a kódban keményen beprogramoznia az alkalmazás URL-címeit, amelyek később megváltozhatnak, vagy bonyolult lehet az összeállításuk. Csak adja meg a bemutatót és az akciót a linkben, adjon át bármilyen paramétert, és a keretrendszer maga generálja az URL-t. Valójában ez nagyon hasonlít egy függvény meghívásához. Tetszeni fog.

A bemutató sablonban

Leggyakrabban a sablonokban hozunk létre linkeket, és ebben nagy segítségünkre van a n:href attribútum:

<a n:href="Product:show">detail</a>

Figyeljük meg, hogy a href HTML attribútum helyett az n:attribútumot n:href használjuk. Ennek értéke nem egy URL, ahogyan azt a href attribútummal megszoktuk, hanem a bemutató és a művelet neve.

A linkre kattintás, egyszerűen szólva, olyasmi, mint egy módszer meghívása ProductPresenter::renderShow(). És ha a szignatúrájában vannak paraméterek, akkor argumentumokkal is meg tudjuk hívni:

<a n:href="Product:show $product->id, $product->slug">detail</a>

Lehetőség van nevesített paraméterek átadására is. A következő hivatkozás a lang paramétert adja át a en értékkel:

<a n:href="Product:show $product->id, lang: en">detail</a>

Ha a ProductPresenter::renderShow() metódus aláírásában nem szerepel a $lang, akkor a paraméter értékét a $lang = $this->getParameter('lang') segítségével vagy a tulajdonságból tudja lekérdezni.

Ha a paraméterek egy tömbben vannak tárolva, akkor a ... operátorral (vagy a Latte 2.x-ben a (expand) operátorral) bővíthetők:

{var $args = [$product->id, lang => en]}
<a n:href="Product:show ...$args">detail</a>

Az úgynevezett tartós paraméterek is automatikusan átadásra kerülnek a hivatkozásokban.

A n:href attribútum nagyon hasznos a HTML címkékhez. <a>. Ha a linket máshol, például a szövegben akarjuk kiírni, akkor a {link} attribútumot használjuk:

URL is: {link Home:default}

A kódban

A link() metódus a bemutatóban egy link létrehozására szolgál:

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

A paraméterek tömbként is átadhatók, ahol megnevezett paraméterek is megadhatók:

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

A linkek prezenter nélkül is létrehozhatók a LinkGenerator és annak link() metódusa segítségével.

Linkek a bemutatóhoz

Ha a link célpontja az előadó és a művelet, akkor a következő szintaxissal rendelkezik:

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

A formátumot az összes Latte tag és az összes olyan presenter módszer támogatja, amely linkekkel dolgozik, azaz n:href, {link}, {plink}, link(), lazyLink(), isLinkCurrent(), redirect(), redirectPermanent(), forward(), canonicalize() és a LinkGenerator. Tehát még ha a példákban a n:href is szerepel, bármelyik függvény lehet.

Az alapforma tehát Presenter:action:

<a n:href="Home:default">home</a>

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

<a n:href="default">home</a>

Ha a művelet a default, elhagyhatjuk, de a kettőspontnak meg kell maradnia:

<a n:href="Home:">home</a>

A hivatkozások más modulokra is mutathatnak. Itt a linkek az almodulokhoz viszonyítva, illetve abszolút módon különböztethetők meg. Az elv analóg a lemezes elérési utakkal, csak a kötőjelek helyett kettőspontok vannak. Tegyük fel, hogy a tényleges bemutató a Front modul része, akkor azt írjuk:

<a n:href="Shop:Product:show">link to Front:Shop:Product:show</a>
<a n:href=":Admin:Product:show">link to Admin:Product:show</a>

Speciális eset a saját magára való hivatkozás. Itt azt írjuk, hogy this a cél.

<a n:href="this">refresh</a>

A HTML oldal egy bizonyos részére a # hash szimbólum után egy úgynevezett fragmentummal tudunk hivatkozni:

<a n:href="Home:#main">link to Home:default and fragment #main</a>

Abszolút elérési utak

A link() vagy n:href által generált linkek mindig abszolút elérési utak (azaz /-vel kezdődnek), de nem abszolút URL-ek protokollal és domainnel, mint például https://domain.

Abszolút URL létrehozásához adjon hozzá két kötőjelet az elejéhez (pl. n:href="//Home:"). Vagy a $this->absoluteUrls = true beállítással úgy is beállíthatja a prezentert, hogy csak abszolút linkeket generáljon.

Link az aktuális oldalra

A cél this létrehoz egy linket az aktuális oldalra:

<a n:href="this">refresh</a>

Ugyanakkor az összes paraméter, amelyet a action<Action>() vagy a render<View>() metódusban megadott paraméterek, ha a action<Action>() nincs definiálva, átadásra kerül. Tehát ha a Product:show és a id:123 oldalakon vagyunk, akkor a this linkje is átadja ezt a paramétert.

Természetesen lehetőség van a paraméterek közvetlen megadására is:

<a n:href="this refresh: 1">refresh</a>

A isLinkCurrent() függvény meghatározza, hogy a link célpontja megegyezik-e az aktuális oldallal. Ez például egy sablonban használható a linkek megkülönböztetésére stb.

A paraméterek ugyanazok, mint a link() metódus esetében, de lehetőség van a * joker karakter használatára is egy konkrét művelet helyett, ami a bemutató bármely műveletét jelenti.

{if !isLinkCurrent('Admin:login')}
	<a n:href="Admin:login">Přihlaste se</a>
{/if}

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

A rövidített formát a n:href kapcsolattal együtt lehet használni egyetlen elemben:

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

A * joker karakter csak a prezentáló műveletét helyettesíti, magát a prezentálót nem.

Annak megállapítására, hogy egy adott modulban vagy annak almoduljában vagyunk-e, a isModuleCurrent(moduleName) függvényt használhatjuk.

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

Linkek a Signalhoz

A link célpontja nem csak a bemutató és az akció lehet, hanem a jel is (ők hívják a metódust handle<Signal>()). A szintaxis a következő:

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

A jelzést tehát felkiáltójel különbözteti meg:

<a n:href="click!">signal</a>

Az alkomponens (vagy al-alkomponens) jelére mutató linket is létrehozhat:

<a n:href="componentName:click!">signal</a>

Linkek a komponensben

Mivel a komponensek különálló, újrafelhasználható egységek, amelyeknek nem lehet kapcsolatuk a környező bemutatókkal, a hivatkozások egy kicsit másképp működnek. A n:href Latte attribútum és a {link} címke, valamint az olyan komponensmódszerek, mint a link() és mások, mindig a célt tekintik jelzőnévnek. Ezért nem szükséges felkiáltójelet használni:

<a n:href="click">signal, not an action</a>

Ha a komponenssablonban előadókra akarunk hivatkozni, akkor a {plink} címkét használjuk:

<a href={plink Home:default}>home</a>

vagy a kódban

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

Álnevek

Néha hasznos, ha egy könnyen megjegyezhető álnevet rendelünk egy Presenter:action pároshoz. Például a Front:Home:default honlapot egyszerűen elnevezheti home -nek, vagy a Admin:Dashboard:default -t admin-nak.

Az aliasok a konfigurációban a application › aliases kulcs alatt kerülnek meghatározásra:

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

A hivatkozásokban az at szimbólummal íródnak, például:

<a n:href="@admin">administration</a>

A linkekkel dolgozó összes módszer támogatja őket, például a redirect() és hasonlók.

Érvénytelen hivatkozások

Előfordulhat, hogy érvénytelen linket hozunk létre – vagy azért, mert nem létező bemutatóra hivatkozik, vagy azért, mert több paramétert ad át, mint amennyit a célmódszer az aláírásában kap, vagy amikor nem lehet generált URL a célzott művelethez. Azt, hogy mit tegyünk az érvénytelen linkekkel, a Presenter::$invalidLinkMode statikus változó határozza meg. Ez a következő értékek (konstansok) egyikét veheti fel:

• Presenter::InvalidLinkSilent – néma üzemmód, URL-ként a # szimbólumot adja vissza.
• Presenter::InvalidLinkWarning – E_USER_WARNING kerül előállításra.
• Presenter::InvalidLinkTextual – vizuális figyelmeztetés, a hiba szövege megjelenik a hivatkozásban.
• Presenter::InvalidLinkException – az InvalidLinkException hibaüzenetet kap.

Az alapértelmezett beállítás termelési üzemmódban a InvalidLinkWarning, fejlesztési üzemmódban pedig a InvalidLinkWarning | InvalidLinkTextual. A InvalidLinkWarning nem öli meg a szkriptet a termelési környezetben, de a figyelmeztetés naplózásra kerül. A fejlesztői környezetben a Tracy elfogja a figyelmeztetést és megjeleníti a hiba bluescreen-t. Ha a InvalidLinkTextual van beállítva, a prezenter és a komponensek URL-ként adják vissza a hibaüzenetet, amely a #error: csillaggal kezdődik. Ahhoz, hogy az ilyen linkeket láthatóvá tegyük, hozzáadhatunk egy CSS szabályt a stíluslapunkhoz:

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

Ha nem akarjuk, hogy a fejlesztői környezetben figyelmeztetések jelenjenek meg, akkor a konfigurációban bekapcsolhatjuk a silent invalid link mode-ot.

application:
	silentLinks: true

LinkGenerator

Hogyan hozhatunk létre linkeket a link() comfort módszerrel, de prezenter jelenléte nélkül? Ezért itt van a Nette\Application\LinkGenerator.

LinkGenerator egy olyan szolgáltatás, amelyet átadhat a konstruktoron keresztül, majd linkeket hozhat létre a link() módszerével.

Az előadókhoz képest van különbség. A LinkGenerator minden linket közvetlenül abszolút URL-ként hoz létre. Emellett nincs “tényleges prezenter”, így nem lehet csak a link('default') műveletnevet célként felsorolni, vagy relatív elérési utakat felsorolni a modulokhoz.

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