Dotazový datový zdroj JDO (dříve: JDO dotazový datový zdroj)

Datová třída

com.etnetera.jnp.data.QueryDataSourceData

Rozšiřuje

AbstractAssetDataSourceData

Obsahové varianty

  • default (default)

Atributy

(Kromě atributů dále uvedených také může dědit od typu AbstractAssetDataSourceData. Viz úvodní poznámky k tomuto přehledu.)

Systémový názevTyp hodnotyVícejazyčnýMultihodnota
baseType
baseTypeTyp assetunene
folder
folderFolderDatanene
restrictBaseClass
restrictBaseClassBooleannene
restrictFolder
restrictFolderBooleannene
query
queryStringnene
imports
importsStringnene
parameterDeclaration
parameterDeclarationStringnene
variableDeclaration
variableDeclarationStringnene
queryOptions
queryOptionsStringnene

Použití v příkazu while

Zdroj se používá v příkazu while. (Dřívější použití v příkazu datasource se nyní nedoporučuje.) Hodnota, kterou zpřístupňuje v cyklu při každém průchodu, je assetová obálka.

Při volání v šabloně lze zdroji předat libovolné parametry. Speciální význam mají:

limit
Maximální počet assetů, který bude vrácen ve výsledku.
offset
Daný počet assetů na začátku seznamu bude přeskočen. Pomocí offset a limit lze tedy seznam stránkovat.
forceCount
Pokud je hodnota větší než nula, uvnitř cyklu bude dostupná proměnná _count udávající celkový počet záznamů ve zdroji.
folder
Počáteční složka. Pokud je parametr definovaný, dostane přednost před hodnotou atributu folder nastavenou ve zdroji.
restrictFolder
Omezení na danou složku. Hodnota parametru se konvertuje na řetězec; pokud hodnotou není null ani prázdný řetězec, dostane přednost před hodnotou atributu restrictFolder zdroje. Hodnota "1" se bere jako true, jakákoli jiná hodnota jako false.
ordering
Řazení. Dostane přednost před hodnotou atributu ordering nastavenou ve zdroji.
query
Vlastní dotaz, který nahradí hodnotu atributu query.

Ostatní parametry se předají zdroji jako hodnoty parametrů JDO dotazu.

Poznámky k forceCount

Zjištění počtu assetů je pro většinu datových zdrojů poměrně drahá operace, která by se měla používat uváženě. Často je nutné projít iterací celým datovým zdrojem včetně nezobrazených prvků.

K zamezení nekontrolovatelného poklesu výkonu je zavedena následující konvence:

  • Hodnota parametru není boolean, ale celé číslo. Pokud je větší než 1, pak udává maximální počet prvků, které jsou ve zdroji povoleny.
  • Jestliže je hodnota parametru přesně 1, není počet omezen. Tato funkce by se měla používat velmi uvážlivě – viz dále.

Proměnná _count je dostupná v celém cyklu, i v blocích whilefirst a whilelast. Zde typicky bude použitá pro vypsání počtu položek nebo prvku umožňujícího stránkování.

Hodnotou proměnné _count, která je v takovém případě k dispozici, je celkový počet výsledků dotazu, a to jako by se nepoužil offset a limit, tzn. velikost celé stránkované množiny assetů. Pokud je forceCount číslo větší než 1, pak _count nikdy nebude větší než toto číslo.

Hodnota forceCount větší než 1 ale omezuje i počet vrácených výsledků. To znamená, že pokud by zdroj obsahoval více assetů, jsou všechny ostatní ignorovány nejen pro účely zjištění počtu, ale i při samotné iteraci.

Použití forceCount=1 by mělo být omezené na případy, kdy je skutečně nutné znát celkový počet záznamů. Je třeba uvážit, zda funkčnost vyžadující tuto volbu (viditelný výpis celého počtu, odkaz na poslední stránku seznamu) je z pohledu uživatele toho kterého webu skutečně nutná:

  • Je možné zobrazit počet až na vyžádání?
  • Používá alespoň některý uživatel skutečně odkaz na poslední stránku seznamu?
  • Je možné stránkování omezit na prvních n výsledků?

JDOQL dotaz

Dotaz může dále omezit množinu vrácených assetů. Při formulaci dotazu se používá standardní dotazovací jazyk JDOQL. Zde najdete rychlý přehled tohoto jazyka a popis konkrétních implementovaných funkcí v použitém TJDO.

Inspirací pro sestavení dotazu může být i jazyk NGQL.

V dotazu je možné použít následující identifikátory:

  • Systémové názvy atributů, které jsou definované pro datovou třídu baseClass nebo její nadtřídy. Také lze použít identifikátory name (systémový název assetu) a contentVersion (obsahová varianta assetu).
  • Deklarované parametry.
  • Deklarované proměnné.
Příklad: Vyhledání assetů, které se nejmenují "index"
JDOQL dotaz
name != "index"

Pozor: Pokud je datový slovník systému jNetPublish dvojjazyčný, je nutné názvy atributů uvádět včetně jazykového sufixu, tedy například title_cz pro titulek.

Příklad: Vyhledání assetů s neprázdným řetězcem
JDOQL dotaz
not title = ""

Pro některé atributy může být reprezentace z pohledu JDOQL odlišná od té, kterou je autor šablon zvyklý používat v TFS. Týká se to zejména referencí na assety (v JDOQL jsou dostupné jako celá čísla – identifikátory assetů) a atributu controlWordsSet (hodnota controlWords v JDOQL není dostupná).

Příklad: Vyhledání assetů s určitým řídícím slovem
JDOQL dotaz
controlWordsSet.contains("news")

Seznam vrácených assetů se omezuje na ty, které mezi řídícími slovy obsahují slovo "news".

Povšimněte si, že testovaný atribut je controlWordsSet, jehož hodnotou je z pohledu JDOQL dotazu množina řetězců. (V editačním rozhraní je tento atribut reprezentovaný jedním řetězcem, který obsahuje jednotlivá řídící slova oddělená mezerou.)

Nad touto množinou je možné v implementaci JDO, kterou používá jNetPublish, volat metodu contains a (nestandardní) notContains pro její negaci.

Všimněte si, že není možné filtrovat seznam assetů podle jiných dat, než jsou atributy, zejména ne podle jejich vlastností. Tuto skutečnost je důležité zohlednit už v okamžiku návrhu reprezentace dat v prezentaci.

Parametry dotazu

Při volání datového zdroje je možné mu z šablony předat parametry. Předávají se všechny parametry příkazu while kromě parametrů speciálním významem.

Parametry je třeba deklarovat; v assetu zdroje k tomu slouží atribut Parametry dotazu. Deklarace parametru má tvar “název typu (mezera) název parametru“. Pokud je parametrů více než jeden, oddělují se čárkou (a mezerou).

Příklad: Test na výskyt podřetězce v řetězci
Šablona
{let query := iif(_request.params.query, _request.params.query, "")}
{while _template.source q=query}
   ...
{/while}
Parametry dotazu
String q
JDOQL dotaz
title.indexOf(q) >= 0

Tímto způsobem je možné implementovat triviální vyhledávání assetů podle podřetězce v titulku. Pozor: toto není náhrada za skutečný fulltext.

Parametr požadavku q je předaný zdroji pod stejným jménem. Všimněte si, že když už je parametr zdroje jednou deklarovaný, je nutné předat nějakou hodnotu, která není null – alespoň prázdný řetězec..

Předávané parametry musí přesně odpovídat těm, které jsou deklarované v assetu zdroje; žádný nesmí chybět ani přebývat. Problém nastane i v případě, že je předávaná hodnota null.

Příklad: Funkce iif pro výběr datového zdroje
Vstup
{let c := value(_request.params.category, null)}
{while iif(c, _template.categoryItems, _template.allItems) category=c}
  ...
{/while}

Při iteraci přes JDO dotazový datový zdroj je nutné zajistit, aby byly zdroji vždy předané správné parametry.

Předpokládejme, že k šabloně jsou připojené dva dotazové zdroje: categoryItems s parametrem category a allItems bez parametrů.

Hodnota parametru se přebírá z requestu, samozřejmě jen pokud je nastavena.

Pomocí funkce iif se zajistí volání vždy toho správného zdroje. Tímto způsobem je možné eliminovat zbytečné duplikování kódu.

Příklad: Vyhledání assetů ve vícero složkách
JDOQL dotaz
parent childrenof :section or parent childrenof :folder

Porovnáním se kontroluje shoda předaného assetu (v tomto případě sekce a složky) s referencí v atributu parent.

Příklad: Vyhledání assetů ve vícero složkách s ošetřením
JDOQL dotaz
parent childrenof :folder or (defined :alternativeFolder and parent childrenof :alternativeFolder)

Obdoba předchozího příkladu s ošetřením nepovinného parametru.

Příklad: Test presence jedné hodnoty v kolekci
JDOQL dotaz
tags contains :tag
JDOQL dotaz
:tag in tags

Kritérium spočívá v testu, zda atribut tags typu kolekce obsahuje hodnotu předanou parametrem :tag.

Obě alternativy jsou ekvivalentní.

Příklad: Test neprázdnosti průniku dvou množin
JDOQL dotaz
tags contains any :tags
JDOQL dotaz
defined :tags and tags contains any :tags

Kritérium spočívá v testu, zda alespoň jedna hodnota v atributu tags obsahuje alespoň jednu hodnotu z kolekce předané parametrem :tags. Jinými slovy zda průnik těchto dvou množin je neprázdný.

Ve druhém případě je parametr (a tedy celá podmínka) nepovinný.

Příklad: Test podmnožiny
JDOQL dotaz
tags contains all :tags
JDOQL dotaz
defined :tags and tags contains all :tags

Kritérium spočívá v testu, zda všechny hodnoty předané v kolekci :tags jsou obsaženy v atributu tags typu kolekce. 

Import typů

Kromě atomických typů javy je otestované předávání parametrů typů String a Date. Pro parametry jiných typů než atomických a String je třeba importovat příslušné typy. V assetu zdroje k tomu slouží atribut Import typů. Import se zapisuje ve tvaru “import název importované třídy“. Více importů se odděluje středníkem (a mezerou); slovo import se opakuje v každém importu.

Je třeba dávat pozor na detaily zápisu: například řádkový zlom mezi jednotlivými importy může vést k chybě.

Dále je třeba zohlednit skutečnost, že dotaz, který systém skutečně provede, je zkonstruován s přidáním vlastních importů, deklarací a částí dotazu. Tyto dodatečné součásti už mohly některé typy naimportovat (například java.util.Date pro validaci); pak by duplicitní použití importu vedlo k chybě.

Proměnné dotazu

Deklarované proměnné se mohou vyskytnout v dotazu. Tyto proměnné jsou implicitně existenčně kvantifikované: zdroj vrací ty položky, pro které existuje nějaká hodnota každé proměnné taková, že je podmínka dotazu splněná.

Pro vložení příspěvku do diskuse se přihlašte.