Picker

1. Základní informace

• Picker je dialogové okno, které zobrazuje nahlížecí tabulku s databázovými záznamy, jejichž hodnoty je možné převzít či zkopírovat do právě otevřeného editačního formuláře. Picker se typicky používá pro kopírování celých databázových záznamů nebo pro převzetí hodnoty cizího klíče (ForeignKey).
• Odkaz na dialogové okno pickeru s nahlížecí tabulkou a databázovými záznamy má podobu ikony lupy, a zobrazuje se v editačním formuláři napravo vedle ovládacího prvku, ke kterému je picker přidružen.
• Picker je dostupný pro tyto typy ovládacích prvků:
  • TextBox
  • TextArea
  • RichTextBox
  • ComboBox
  • ListBox
  • MultiListBox
  • Radio
  • CheckBox
  • ForeignKey
  • File
  • Image
  • DatePicker
• Picker má i podobu ajaxového našeptávače, který začne nabízet databázové záznamy už při zadávání hodnoty do textového pole v editačním formuláři. Našeptávač je dostupný u ovládacích prvků TextBox, ComboBox s možností zadat vlastní hodnotu a ForeignKey, a jen tehdy, když je zaškrtnuto „Vyhledat hodnotu zadanou v editačním formuláři“ a není zaškrtnuto „Optimalizované hledání“.
• Nastavení pickeru se provádí v samostatném dialogu. Odkaz na tento dialog má podobu ikony lupy, a nachází se v levém dolním rohu dialogu nastavení ovládacího prvku, ke kterému je picker přidružen. Odkaz se zobrazí až u uloženého ovládacího prvku.
• Aby se ikona pickeru v editačním formuláři zobrazila, musí mít picker vyplněnou přiřazovací tabulku, tj. alespoň jeden řádek se zvoleným zdrojem i cílem. Samotné nastavení zdroje dat ikonu nezobrazí.
• Ikona pickeru se nezobrazí v editačním formuláři, který uživatel nesmí měnit (typicky záznam bez práva editace nebo záznam uzamčený jiným uživatelem), ani v dialogu hromadných změn. U ovládacího prvku „Jen ke čtení“ se ikona zobrazuje a picker do něj hodnotu zapíše — takto se obvykle plní pole, která uživatel nemá vyplňovat ručně. Výjimkou jsou ovládací prvky „Jen ke čtení“, jejichž hodnotu drží server — převzetí z pickeru je nezmění. Jde o ovládací prvky se zaškrtnutým „Zakázat změnu hodnoty pomocí JavaScriptu“ a dále o ovládací prvky „Jen ke čtení“ s tímto způsobem výpočtu výchozí hodnoty:
  • TextBox a TextArea – „Aktuální uživatel“, „Aktuální datum“, „Aktuální čas“, „Aktuální datum a čas“ nebo „Aktuální hodnota v databázi“
  • RichTextBox, CheckBox a ForeignKey – „Aktuální hodnota v databázi“
  • ComboBox, ListBox a Radio – „Aktuální uživatel“ nebo „Aktuální hodnota v databázi“
• Nahlížecí tabulka pickeru musí obsahovat alespoň jeden sloupec jiný než sloupec „(ID)“, jinak se dialogové okno pickeru po otevření okamžitě zavře. Nejčastěji na to narazí picker cizího klíče, jehož přiřazovací tabulka obsahuje jediný řádek s cílem v cizím klíči a se zdrojem ve sloupci „(ID)“. V takovém případě je potřeba přiřadit další sloupec, nebo doplnit alespoň jeden sloupec na záložce „Nápověda“. Sloupce ze záložky „Aktivovat hledání“ k zobrazení nahlížecí tabulky nestačí.

2. Záložka „Obecné“

2.1. Tooltip

• Tooltip určuje text nápovědy, který se zobrazí po najetí myši nad ikonu pickeru v editačním formuláři.
• Tentýž text se použije i jako titulek dialogového okna pickeru; tři tečky na jeho konci se v titulku vynechají. Není-li tooltip vyplněný, má dialogové okno titulek „Picker“.

2.2. Zdroj dat

• Zdroj dat definuje data zobrazovaná v nahlížecí tabulce pickeru. Tato data jsou výsledkem databázového dotazu, který je vyhodnocen při otevření okna pickeru, nebo při zahájení našeptávání hodnot přímo do editačního formuláře.
• Nastavení zdroje dat se provádí v grafickém návrháři databázových dotazů.
• Při změně zdroje dat se sloupce přiřazovací tabulky předvyplní automaticky podle shody názvů ovládacích prvků.
• Podmínky dotazu mohou obsahovat hodnoty ovládacích prvků editačního formuláře (#ng_...#). Do podmínek se dosazují aktuální hodnoty z otevřeného formuláře, včetně dosud neuložených změn. Prázdná hodnota ovládacího prvku vede na podmínku „je prázdné“ — podmínka se tedy nevynechá.

2.3. Počet záznamů na stránce

• Pro přehlednost používá nahlížecí tabulka stránkování zobrazovaných záznamů. To je užitečné v situacích, kdy nahlížecí tabulka načítá velké množství dat.
• Počet záznamů na stránce určuje maximální počet záznamů, které se zobrazí na jedné stránce. Mezi jednotlivými stránkami lze snadno přecházet pomocí nástrojů, které obsahuje každá nahlížecí tabulka ve svém zápatí.
• Tentýž počet omezuje i ajaxový našeptávač, který nabídne nejvýše tolik záznamů a za ně připojí „...“. Není-li počet vyplněný, použije se 20 záznamů.

2.4. Možnosti

• Vyhledat hodnotu zadanou v editačním formuláři
  • Pro ovládací prvky TextBox, ComboBox s možností zadat vlastní hodnotu a ForeignKey
  • Zaškrtnutí tohoto pole určuje, zda má být hodnota zadaná v editačním formuláři vyhledána v nahlížecí tabulce pickeru, a zda má editační formulář nabízet ajaxový picker.
  • U ovládacího prvku TextBox s datumovým, časovým nebo číselným pickerem či výběrem barvy se hodnota nevyhledává.
• Optimalizované hledání
  • Pro všechny ovládací prvky editačního formuláře s možností pickeru
  • Optimalizované hledání znamená, že každý sloupec nahlížecí tabulky pickeru používá svoje textové pole určené pro zadání hledaného výrazu nebo slovního spojení.
  • Běžné (neoptimalizované) hledání znamená, že se pro zadání hledaného výrazu používá jedno společné textové pole, do kterého je možné vypsat všechny hledané výrazy, a ty jsou následně vyhledávány ve všech sloupcích nahlížecí tabulky najednou.
  • Optimalizované hledání vypíná ajaxový našeptávač i předání hodnoty z editačního formuláře do hledání v pickeru.
• Zobrazit pouze výsledky hledání
  • Pro všechny ovládací prvky editačního formuláře s možností pickeru
  • Zaškrtnutí tohoto pole určuje, zda má nahlížecí tabulka pickeru zobrazovat záznamy, pouze když je zadán hledaný výraz nebo slovní spojení. Bez hledaného výrazu zobrazí nahlížecí tabulka výzvu „Zadejte prosím hledaný výraz“.
  • Hledání se v tomto režimu provádí přímo v databázi a načte se nejvýše tolik záznamů, kolik je nastaveno v poli „Počet záznamů na stránce“. Bez tohoto režimu se načte celý výsledek dotazu a hledá se v něm až po načtení.
• Přepsat hodnotu zadanou v editačním formuláři
  • Pro ovládací prvky TextBox, TextArea, RichTextBox a MultiListBox
  • Zaškrtnutí tohoto pole určuje, zda má převzetí hodnoty pole z nahlížecí tabulky pickeru do editačního formuláře hodnotu přepsat, nebo jí přidat na konec. Přidávané hodnoty se oddělují čárkou a mezerou (TextBox), novým řádkem (TextArea a RichTextBox), resp. jako další vybraná položka (MultiListBox).
  • Volba se vyhodnocuje u ovládacího prvku, do kterého se hodnota převádí — tedy u cíle přiřazení, a to u každého pickeru, který do tohoto ovládacího prvku zapisuje. Nastavit ji lze jen v pickeru daného ovládacího prvku, takže do ovládacího prvku bez vlastního pickeru se hodnota vždy zapíše přepsáním.
  • Při přidávání hodnoty se aktuální obsah ovládacího prvku TextBox do hledání v pickeru nepředává. Ajaxový našeptávač vyhledává jen text za poslední čárkou.
• Povolit vytváření nových záznamů
  • Pro všechny ovládací prvky editačního formuláře s možností pickeru
  • Zaškrtnutí tohoto pole určuje, zda se pod nahlížecí tabulkou pickeru bude zobrazovat tlačítko pro zadání nového záznamu stejné agendy, která je použitá jako zdroj dat v nahlížecí tabulce. Detailní popis je uveden v kapitole Vytváření a otevírání záznamů.
• Povolit otevírání záznamů
  • Pro všechny ovládací prvky editačního formuláře s možností pickeru
  • Zaškrtnutí tohoto pole určuje, zda má být možné otevírat jednotlivé záznamy z nahlížecí tabulky pickeru, a v dialogovém okně pickeru zobrazit detail konkrétního databázového záznamu přímo v jeho editačním formuláři. Záznam se otevírá odkazem v prvním sloupci nahlížecí tabulky.
• Povolit výběr více záznamů najednou
  • Pro všechny ovládací prvky editačního formuláře s možností pickeru
  • Zaškrtnutí tohoto pole umožňuje výběr více záznamů v pickeru najednou. Jednotlivé záznamy se v pickeru vybírají zaškrtnutím checkboxu umístěného na každé řádce nahlížecí tabulky pickeru v prvním sloupci. Tímto způsobem je však možné pickovat pouze sloupec „(ID)“ tj. primární klíč. Do editačního formuláře se vybrané záznamy převezmou jako jednotlivé hodnoty primárního klíče oddělené středníkem. Detailní popis je uveden v kapitole Výběr více záznamů najednou.

2.5. Přiřazovací tabulka

• Sloupce
  • Nastavení sloupců určuje, jaký sloupec nahlížecí tabulky v pickeru bude zkopírován do jakého ovládacího prvku v editačním formuláři.
  • Cílem může být kterýkoli databázový ovládací prvek editačního formuláře kromě AutoSum.
  • Pickované sloupce – ty co mají nastavený zdroj a cíl – se automaticky zobrazují v nahlížecí tabulce pickeru v pořadí, v jakém jsou uvedeny v přiřazovací tabulce.
  • Sloupce v nahlížecí tabulce pickeru je možné skrýt výběrem příkazu „Skrýt“ z rozbalovacího seznamu umístěného napravo vedle rozbalovacího seznamu „Cíl“. Skrytý sloupec se v nahlížecí tabulce nezobrazí a nevyhledává se v něm, jeho hodnota se ale do editačního formuláře převezme.
  • Sloupec se skryje automaticky i tehdy, když je jeho cílem ovládací prvek TextBox, TextArea, CheckBox nebo ForeignKey se zaškrtnutým „Skryté pole“.
  • U sloupců v nahlížecí tabulce pickeru je možné aktivovat hledání výběrem příkazu „Aktivovat hledání“ z rozbalovacího seznamu umístěného napravo vedle rozbalovacího seznamu „Cíl“.
  • Není-li zvolen žádný sloupec pro hledání, automaticky se aktivuje hledání u všech sloupců nahlížecí tabulky pickeru, kde je to povolené z pohledu obecného nastavení vyhledávání v nahlížecích tabulkách, které se definuje ve vlastnostech ovládacího prvku.
  • Je-li záložka „Nápověda“ prázdná, uložení nastavení skončí chybou tehdy, když jsou všechny řádky přiřazovací tabulky skryté, nebo když je v přiřazovací tabulce vybraný pouze primární klíč — nahlížecí tabulka pickeru by neměla co zobrazit.
  • Přiřazení, jehož zdrojový nebo cílový ovládací prvek se smaže, se z přiřazovací tabulky odstraní — a to i u pickerů jiných ovládacích prvků, které smazaný sloupec používaly.

3. Záložka „Nápověda“

• Na záložce „Nápověda“ je možné nastavit seznam všech dalších sloupců, které mají být zobrazeny v nahlížecí tabulce pickeru, přestože se žádný z těchto sloupců nepickuje.

4. Záložka „Aktivovat hledání“

• Na záložce „Aktivovat hledání“ je možné nastavit seznam všech dalších sloupců, ve kterých má být aktivováno hledání.

5. Záložka „Ostatní“

• Název šablony
  • Nastavení pickeru je možné uložit do šablony, aby se dalo snadno zkopírovat při nastavování pickeru dalšího ovládacího prvku, který načítá data ze stejného zdroje dat.
  • Výběr šablony se nabízí, až je vybraný zdroj dat, a obsahuje pickery ovládacích prvků stejného typu, jejichž zdroj dat čte ze stejného editačního formuláře a které mají vyplněný název šablony. Výběr šablony zkopíruje tooltip, počet záznamů na stránce, možnosti pickeru a sloupce na záložkách „Nápověda“ a „Aktivovat hledání“; zdroj dat ani přiřazovací tabulku nekopíruje.

6. Tlačítka „Uložit“, „Vynulovat přiřazovací tabulku“ a „Skrýt – pro vše“

• Tlačítko „Uložit“ – Uložení změn v nastavení pickeru.
• Tlačítko „Vynulovat přiřazovací tabulku“ – Odstranění aktuálních přiřazení mezi zdrojem a cílem na všech řádkách přiřazovací tabulky. Hodnoty ve sloupci Cíl a Možnosti jsou tímto tlačítkem vráceny do nepřiřazeného stavu. Uložením prázdné přiřazovací tabulky se picker zruší; zdroj dat a ostatní nastavení zůstanou uložené a znovu se nabídnou při dalším nastavení pickeru.
• Tlačítko „Skrýt – pro vše“ – Nastavení příznaku „Skrýt“ na všech řádkách přiřazovací tabulky.

7. Otevření pickeru

• Picker se otevírá kliknutím na ikonu lupy vedle ovládacího prvku, na mobilním zařízení v novém okně. Z JavaScriptu editačního formuláře ho otevře funkce picker_Open().
• Je-li u pickeru zaškrtnuto „Vyhledat hodnotu zadanou v editačním formuláři“, předá se aktuální hodnota ovládacího prvku do hledání v pickeru a nahlížecí tabulka se rovnou otevře vyfiltrovaná.
• Dialogové okno pickeru načítá data až po svém otevření, protože nejdříve přebírá aktuální hodnoty z editačního formuláře (viz kapitola Zdroj dat).
• Nahlížecí tabulka pickeru nenabízí export, přizpůsobení ani ikonu „Skrýt“ pro skrytí obsahu tabulky a uživatelské úpravy řazení se u ní neukládají. Tlačítko „Výchozí třídění“ vrátí řazení podle zdroje dat a stránkování podle nastaveného počtu záznamů na stránce.
• Má-li zdroj dat nastavený „Časový úsek podle“, zobrazí se nad nahlížecí tabulkou pickeru výběr časového úseku, ve výchozím stavu od měsíce zpět do konce aktuálního roku.
• Sloupce se zaškrtnutým „Zobrazit filtr v nahlížecí tabulce“ nabízejí filtr stejně jako v běžné nahlížecí tabulce.
• Hodnoty v nahlížecí tabulce pickeru se zobrazují bez odkazů a bez jednotek.
• Nastane-li při načítání dat chyba databázového dotazu, zobrazí se chybové hlášení přímo v nahlížecí tabulce pickeru.

7.1. Rozsah načítaných dat

• Bez zaškrtnutého „Zobrazit pouze výsledky hledání“ načítá picker celý výsledek databázového dotazu a stránkování i hledání probíhá až nad načtenými daty. U rozsáhlých tabulek je proto potřeba omezit zdroj dat podmínkami, nastavením „Načíst pouze prvních“ v návrháři databázových dotazů, nebo zaškrtnout „Zobrazit pouze výsledky hledání“.
• Nastavení „Načíst pouze prvních“ má přednost před počtem záznamů na stránce.
• Ajaxový našeptávač načítá nejvýše o jeden záznam víc, než je nastavený počet záznamů na stránce. Je-li ve zdroji dat nastavené „Odstranit záznamy s duplicitním“, načítá se až do limitu „Načíst pouze prvních“, a není-li nastavený, celý výsledek dotazu.

8. Ajaxový našeptávač

• Našeptávač se spustí po zadání prvního znaku do ovládacího prvku, s krátkou prodlevou po posledním stisku klávesy. Klávesy Enter, Esc a klávesy pro pohyb kurzorem hledání nespouštějí.
• Nabízené záznamy se zobrazují jako hodnoty viditelných sloupců oddělené svislou čárou, bez formátování. Ze sloupců TextArea a RichTextBox se zobrazí jen první z nich.
• Klávesa Enter převezme zvýrazněný záznam, a není-li žádný zvýrazněný, první nabízený.
• Našeptávač prohledává stejné sloupce jako nahlížecí tabulka pickeru, kromě skrytých.
• Našeptávač vždy převezme jediný záznam, a to i u pickeru s povoleným výběrem více záznamů najednou.
• Tlačítko „Vybrat první“ v nahlížecí tabulce pickeru převezme první nalezený záznam; zobrazuje se, je-li zadaný hledaný výraz a existuje-li alespoň jeden záznam.

9. Převzetí hodnot do editačního formuláře

• Kliknutím na řádek nahlížecí tabulky pickeru (resp. výběrem záznamu v našeptávači) se hodnoty zdrojových sloupců zapíšou do cílových ovládacích prvků podle přiřazovací tabulky. Sloupce ze záložky „Nápověda“ se nepřebírají.
• Po zápisu se u každého cílového ovládacího prvku vyvolá událost změny hodnoty, takže proběhne JavaScript navázaný na změnu i aktualizace formuláře.
• Převzatá hodnota se uloží do databáze až uložením editačního formuláře.
• Způsob zápisu závisí na typu cílového ovládacího prvku:
  • TextBox, TextArea, RichTextBox, DatePicker – hodnota se zapíše do pole, případně přidá na konec (viz „Přepsat hodnotu zadanou v editačním formuláři“). U ovládacího prvku TextBox s datem a časem se hodnota rozdělí do obou polí.
  • ComboBox s možností zadat vlastní hodnotu – hodnota se vždy přepíše.
  • ComboBox, ListBox, Radio – vybere se položka podle hodnoty, případně podle zobrazovaného textu. Není-li převzatá hodnota mezi položkami ovládacího prvku, zapíše se do záznamu i tak a formulář se aktualizuje.
  • MultiListBox – převezmou se všechny hodnoty zdrojového sloupce, případně se přidají k již vybraným.
  • CheckBox – pole se zaškrtne, shoduje-li se převzatá hodnota s hodnotou, kterou zaškrtnuté pole ukládá do databáze, jinak se zaškrtnutí zruší.
  • ForeignKey – převezme se ID záznamu a zobrazovaný text se dopočítá podle dotazu hodnot cizího klíče.
  • File, Image – převzatá příloha se zkopíruje jako nová příloha editovaného záznamu. Kopie vzniká už při převzetí, tedy i tehdy, když se editační formulář nakonec neuloží.
• Hodnota zdrojového sloupce TextArea se zaškrtnutým šifrováním se převezme jako maska hesla, ne jako skutečná hodnota.

10. Výběr více záznamů najednou

• Kliknutím na řádek se záznam jen označí; převzetí provede až tlačítko „Převzít“ pod nahlížecí tabulkou. Bez označeného záznamu zobrazí tlačítko hlášení „Nejsou označeny žádné záznamy.“.
• Převezmou se hodnoty primárního klíče označených záznamů oddělené středníkem, a to do cíle prvního řádku přiřazovací tabulky.
• Dialog nastavení pickeru v tomto režimu povolí jen přiřazovací tabulku s primárním klíčem jako zdrojem; jinak zobrazí hlášení „Režim výběru více záznamů najednou umožňuje převzít pouze primární klíč.“.

11. Vytváření a otevírání záznamů

• Tlačítko „Nový záznam“ i odkaz v prvním sloupci nahlížecí tabulky otevírají editační formulář zdroje dat přímo v dialogovém okně pickeru. Oprávnění k založení i úpravě záznamu se vyhodnocují stejně jako při běžném otevření editačního formuláře — volby pickeru jen zobrazují tlačítko a odkaz.
• Nový záznam se zakládá jako samostatný záznam bez vazby na rodičovský záznam.
• Editační formulář otevřený z pickeru se vždy zobrazuje v uživatelském režimu, nenabízí tlačítko „Uložit a nový“ a neprovádí přesměrování, která skript formuláře po uložení, smazání nebo spuštění skriptu naplánuje.
• Po uložení se picker vrátí do nahlížecí tabulky s tímto jediným záznamem a zároveň aktualizuje editační formulář, ze kterého byl otevřen. Záznam se v ní zobrazí jen tehdy, když splňuje podmínky zdroje dat. Po smazání se picker vrátí na úplný seznam.
• Tlačítko „Zpět“ v editačním formuláři vrací picker se zachovaným hledaným výrazem a označenými záznamy; odkaz „Zrušit filtry“ je nezachovává.

12. Oprávnění

• Picker smí otevřít jen uživatel s právem k ovládacímu prvku, ke kterému je picker přidružen; jinak se dialogové okno zavře a našeptávač nic nenabídne.
• Přiřazení, k jehož zdrojovému nebo cílovému sloupci uživatel nemá právo, se vynechá. Ze sloupců na záložkách „Nápověda“ a „Aktivovat hledání“ se použijí jen ty, ke kterým má uživatel právo.
• Práva k editačnímu formuláři, nahlížecí stránce nebo záznamům, ze kterých zdroj dat čte, se nekontrolují — picker zobrazí všechny záznamy, které splní podmínky databázového dotazu. Omezit okruh zobrazených záznamů lze jen podmínkami zdroje dat.
• Podmínky, které obsahují hodnoty ovládacích prvků editačního formuláře (#ng_...#), nejsou bezpečnostním filtrem, protože hodnoty dodává prohlížeč uživatele. Bezpečnostní omezení se proto zapisuje systémovými proměnnými, které dosazuje server (např. #loginname#, #userid#).
• Dialog nastavení pickeru může otevřít jen administrátor, který smí měnit editační formulář ovládacího prvku.

13. Ostatní

• Při kopírování ovládacího prvku se zkopíruje i jeho picker. Přiřazení, jehož cílem je kopírovaný ovládací prvek, zapisuje v kopii do nového ovládacího prvku.
• Poznámka editačního formuláře obsahující text „DEBUGPICKER“ vypisuje do konzole prohlížeče průběh převzetí hodnot z pickeru.