1. Dokumentace
  2. Reference
  3. Datový model

<Reference>

Pole typu <Reference> slouží k vytvoření vazby na prvek kolekce. Používá se zpravidla tehdy, když potřebujeme vybrat jednu hodnotu z předem určeného seznamu možností. Například článek na blogu chceme přiřadit do jedné z definovaných rubrik. Odkazovaná kolekce v takovém případě obsahuje seznam rubrik.

<Reference name="someRef" sourceCol="someCol" />

Pole typu Reference je v administračním rozhraní zobrazeno jako formulářový prvek select – uživatel tedy může vybrat maximálně jednu možnost (pro výběr více možností slouží pole typu <ReferenceCollection>). V .aspx se pole typu <Reference> chová jako prvek kolekce, na který odkazuje.

Pomocí pole typu <Reference> lze také filtrovat prvky kolekce při jejich výpisu do stránky pomocí controlu <je:repeater>, viz atribut restrictField controlu <je:repeater>.

Atributy

  • allowEditFor nepovinný [seznam skupin uživatelů]

    Skupiny uživatelů, kterým je pole přístupné k editaci. Pokud není atribut zadán, je pole přístupné k editace všem, kteří mají přístup do administrace. Více v článku Zabezpečení před neoprávněným přístupem do administrace.

  • denyEditFor nepovinný [seznam skupin uživatelů]

    Skupiny uživatelů, kterým je pole znepřístupněné k editaci. Pokud není atribut zadán, je pole přístupné k editace všem, kteří mají přístup do administrace. Více v článku Zabezpečení před neoprávněným přístupem do administrace.

  • desc nepovinný [string]

    Uživatelský popis pole, který se zobrazí v administračním rozhraní. Slouží k zapsání doplňujících údajů, jako například pokyny pro editora apod.

  • itemFormat nepovinný

    Určuje, jakým způsobem jsou jednotlivé položky zdrojové kolekce zobrazeny v administračním rozhraní. Více o itemFormat viz Zobrazení prvků kolekcí v administračním rozhraní.

  • name povinný [string]

    Jméno pole. V rámci jednoho typu musí být jedinečné. Smí obsahovat pouze číslice a písmena bez diakritiky. Doporučuje se jména polí uvádět s počátečním malým písmenem (viz Konvence pojmenování).

  • required nepovinný [false, true]

    Při nastavení na true se pole stane povinným a při editaci v administraci je nutné zvolit hodnotu. V opačném případě lze referenci ponechat prázdnou.

  • sourceCol povinný [kolekce]

    Absolutní nebo relativní cesta ke kolekci, z jejíchž prvků bude vybírán odkazovaný prvek. Způsoby zadávání absolutních i relativních cest ilustrují příklady uvedené níže.

  • title nepovinný [string]

    Uživatelský název pole, který se zobrazí v administračním rozhraní. Není-li title uvedeno, zobrazí se name.

Referenční integrita

JellyPot u polí typu <Reference> nezajišťuje referenční integritu. Libovolný prvek z odkazované kolekce lze smazat, i když je odkazován některým polem typu Reference. V takovém případě se pole typu Reference chová, jako by neobsahovalo odkaz na žádný prvek, a to i v případě, že je deklarováno jako povinné (required="true"). V .aspx souborech není zpravidla nutné toto chování nijak ošetřovat: pokud odkazovaný prvek není určen nebo neexistuje, nic se zkrátka nevypíše. V případě potřeby můžeme k rozlišení neexistence odkazu na prvek použít control <je:if>.

Příklady

Máme jednoduchý blog. Chceme, aby každý článek měl přiřazenu právě jednu rubriku. V Site.config tedy deklarujeme potřebné typy a proměnné:

<Vars>
    <Collection name="blogPostCol"
                itemType="BlogPostItem" />
    <Collection name="blogPostCategoryCol"
                itemType="BlogPostCategoryItem" />
</Vars>
<Types>
    <Type name="BlogPostItem">
        <SimpleText name="title" />
        <Text name="text" />
        <Reference name="category"
                   sourceCol="blogPostCategoryCol" />
    </Type>
    <Type name="BlogPostCategoryItem" />
        <SimpleText name="title" />
    </Type>
</Types>

Typ BlogPostItem představuje článek blogu, typ BlogPostCategoryItem pak jednotlivou rubriku.

Odkaz na zdrojovou kolekci rubrik blogPostCategoryCol jsme v poli typu Reference uvedli absolutně (tj. „bez tečky na začátku“) – jinak to ani nešlo, protože kolekce je samostatná proměnná deklarovaná v sekci <Vars>. Odkazy je ale možné uvádět i relativně (tj. „s tečkou na začátku“). Kdy by se to mohlo hodit? Třeba bychom chtěli zavést obalující typ Blog, který by obsahoval kolekci článků a kolekci rubrik. Site.config by pak vypadal třeba takto:

...
<Vars>
    <Var name="blog" type="Blog" />
</Vars>
<Types>
    <Type name="Blog">
        <Collection name="blogPostCol"
                    itemType="BlogPostItem" />
        <Collection name="blogPostCategoryCol"
                    itemType="BlogPostCategoryItem" />
    </Type>
    <Type name="BlogPostItem">
        <SimpleText name="title" />
        <Text name="text" />
        <Reference name="category"
                   sourceCol=".parent.blogPostCategoryCol" />
    </Type>
    <Type name="BlogPostCategoryItem" />
        <SimpleText name="title" />
    </Type>
</Types>
...

Tento přístup se nám může hodit u rozsáhlejších webů, kde nám pomůže udržet spolu související věci pěkně pohromadě.

Výpis jednoho článku v .aspx by pak v obou případech vypadal nějak takto:

...
<je:item runat="server"
         field=".title"
         tag="h1" />
<je:item runat="server"
         field=".category.title" />
<je:item runat="server"
         field=".text" />
...

Připomínky a postřehy

Máte-li nějakou připomínku, dobrý nápad nebo jste našli v dokumentaci chybu, rádi od vás uslyšíme.