WebToDate/Ankety/Reference
Administrační rozhraní
Nabídka modulu
Nabídka modulu vypadá následovně:
Nastavení
- └Seznam předpisů
- └Globální
- └Starší ankety
- └Navigační lišta
- └Předpisy
- └Předpis 1
Administrace
- └Kategorie
- └Předvolby
- └Práva
Data
- └Ankety
K administrační části modulu mají přístup pouze administrátoři WebToDate s výjimkou funkce Data – Ankety, ke které lze nastavit přístup i jiným uživatelům.
Administrace
V prvé řadě je třeba nastavit předvolby modulu. Nastavení Vlastnosti HTML zprávy generované modulem určují, do které kategorie a publikace se budou řadit zprávy vytvořené pomocí tlačítka Generovat ve formuláři pro vytvoření ankety.
Dále je zde volba zapisovat volby jednotlivých uživatelů. Pokud tato volba není zaškrtnuta, uchovává se v databázi identifikace anonymního uživatele (řetězec uložený do jeho cookie) a identifikátor ankety, na kterou odpověděl. Uchovává se tedy standardně na co který uživatel již odpověděl, neuchovává se informace jak hlasoval. Pokud je tato volba zaškrtnuta, uchovává se i informace o tom jak kdo hlasoval. Jedná se o záznamy v databázové tabulce VOTERESULTS. K těmto datům ovšem není přístup přes www rozhraní modulu a v případě potřeby je třeba je vyhodnotit přímým přístupem do databáze.
Funkce Kategorie slouží k definici jednoúrovňového seznamu kategorií, do kterých lze ankety řadit. Zařazení anket do kategorií není povinné, pokud se použije, lze anketu zařadit do maximálně jedné kategorie.
Kategorie lze zakládat a měnit dle potřeby, mazání kategorie je povoleno, jen když neobsahuje žádné ankety.
Pomocí funkce Práva se nastavují týmy, které mají přístup k datům modulu a mohou zadávat a měnit ankety. Seznam oprávněných týmů se spravuje způsobem obvyklým v modulech WebToDate, ankety mohou vytvářet i redaktoři týmů.
Nastavení
Pro ankety se podobně jako pro některé další moduly používají tzv. předpisy. Předpis je sada grafických a případně i funkčních nastavení, který se může týkat více různých typů stránek najednou. V tomto modulu každý definovaný předpis reprezentuje jeden typ zobrazení ankety – pokud budete tedy potřebovat více různých typů grafického zobrazení anket, je třeba definovat více předpisů.
Předpis se zakládá pomocí funkce Seznam předpisů. Ve formuláři se vyplňuje pouze název, který lze volit dle potřeby. Existující předpis lze libovolně přejmenovávat, smazat jen v případě, že není někde (u nějaké ankety) použit.
Po založení předpisu se název předpisu zobrazuje v nabídce Předpisy. V této nabídce klepnutí na název předpisu zobrazuje formulář, ve kterém se definují grafická nastavení v rámci předpisu:
Pro anketu se rozeznávají dva případy pro zobrazení – jeden případ pro uživatele, který ještě na anketu neodpovídal (Před hlasováním) a druhý pro uživatele, který již na anketu hlasoval (Po hlasování). Pro oba případy se volí WebToDate styl, kterým se anketa formátuje. Dále je zde pole Max. délka obrázku. Modul interně počítá odpovědi a zároveň jejich procentuální podíly, v prezentační vrstvě může rovněž generovat grafické procentuální zobrazení. Tomu pak v těle stylu odpovídá klíčové slovo <!--WTD_VOTE(IMGWIDTH)-->. Pokud je v tomto poli zadána např. hodnota 100, znamená to, že pro odpověď s největším počtem hlasů bude za toto klíčové slovo dosazena hodnota 100, pro ostatní odpovědi čísla odpovídající poměru hlasů. Když např. budou na anketu tři hlasující, z toho jedna otázka bude mít dva hlasy, tak šířka obrázku pro otázku se dvěma hlasy bude 100, na otázku s jedním hlasem 50.
V sekci formuláře Po hlasování je navíc volba Zobrazit samostatně. Pokud je toto zvoleno a uživatel hlasuje na danou anketu, zobrazí se mu vždy stránka /scripts/modules/vote/vote.php zobrazující samostatně výsledky hlasování. Tuto volbu je vždy třeba použít, pokud chceme generovat ankety na zvolené stránky webové prezentace, volitelně v případě, že chceme používat ankety svázané se zprávou. Pokud je anketa svázaná se zprávou a tato volba není zaškrtnuta, zobrazí se po hlasování opět stránka se zprávou a hlasovací formulář ve stavu po hlasování, pokud toto je zaškrtnuto, zobrazí se samostatná hlasovací stránka /scripts/modules/vote/vote.php.
Je-li navíc zaškrtnuto Zobrazit samostatně, je třeba zvolit v posledním poli formuláře Předloha odpovídající předlohu – šablonu pro stránku /scripts/modules/vote/vote.php. Šablona musí obsahovat především klíčové slovo <!--WTD_VOTE(VOTEFORM)-->, které zobrazuje hlasovací formulář, a to vždy ve stavu po hlasování.
V nabídce Nastavení dále existuje sekce Globální, která se v tomto modulu vztahuje pouze na funkci výpisu starších anket.
Formulář Starší ankety slouží ke specifikaci způsobu zobrazení starších anket tak, jak je může zobrazovat stránka /scripts/modules/vote/default.php.
Zde se povinně vybírá Předloha (šablona pro stránku /scripts/modules/vote/default.php) a Styl kterým se formátuje seznam anket (všechny ankety se zde vypisují stejným stylem odpovídajícím typu po hlasování). Výpis anket může být rozdělen na více stránek, počet anket na jednu stránku se specifikuje v poli Počet záznamů na str. Význam pole Max. délka obrázku je stejný jako u předpisů.
V předloze pro zobrazení starších anket lze použít tři základní klíčová slova:
- <!--WTD_VOTE(RESULTLABEL)--> - zobrazuje uvozující nadpis.
- <!--WTD_VOTE(VOTELIST)--> - zobrazuje vlastní seznam anket
- <!--WTD_VOTE(NAVIG)--> - zobrazuje stránkovací navigační lištu
Pro uvozující nadpis platí nastavení v sekci formuláře Uvozující nadpis výpisu – rozlišuje se zde případ, kdy se ve výpisu nezobrazuje žádná anketa a kdy se zobrazuje alespoň jedna anketa.
Poslední možnou volbou je zobrazovat i aktivní. Každá anketa nese příznak, zda je aktivní, tj. zda na ní lze ještě hlasovat. Volba v tomto formuláři říká, zde se mají ve výpisu starších anket zobrazovat i tyto aktivní, na které lze ještě hlasovat, nebo jen ty uzavřené, tj. neaktivní.
Ve formuláři Navigační lišta je definován vzhled lišty, která je používána pro stránkování seznamů položek.
Grafický vzhled jednotlivých prvků navigační lišty se definuje pomocí následujících polí:
- Předchozí – HTML kód určující formátování odkazu pro přechod na předcházející stránku
- Následující – HTML kód určující formátování odkazu pro přechod na další stránku
- Hlavička – HTML kód který je umístěn na počátku výsledného kódu navigační lišty
- Patička – HTML kód který je umístěn na konci výsledného kódu navigační lišty
- Číslo stránky – formátování jednotlivých čísel stránky, které umožní odkliknutí na zvolenou stránku
- Aktivní stránka – formátování údaje o čísle aktuální stránky
- Separátor – oddělovač mezi jednotlivými čísly stránek.
- Počet stránek určuje maximální počet čísel stránek v navigační liště a tím nepřímo ovlivňuje i její šířku.
Pro správnou funkci navigační lišty je nutné do výše popsaných polí zadávat i klíčová slova<!--WTD_NAVIG(URL)--> a <!--WTD_NAVIG(NUMBER)-->.
Jejich použití je zřejmé z následujícího jednoduchého příkladu:
Navigační lišta je pak v předloze pro zobrazení seznamu starších anket reprezentována klíčovým slovem <!--WTD_VOTE(NAVIG)-->.
Data
V této sekci nabídky se vytvářejí a spravují vlastní ankety, pouze tuto nabídku lze pomocí funkce Práva zpřístupnit i jiným uživatelům než administrátorům.
Pro existující ankety je k dispozici vyhledávání. Vyhledávací formulář se zobrazí klepnutím na odkaz Vyhledat v pravém horním rohu okna prohlížeče.
Vyhledávat lze např. podle textu v názvu ankety, ID ankety apod. Zadaná kritéria se spojují logickou spojkou "a zároveň".
Nová anketa se přidává odkazem Přidat v pravém horním rohu okna prohlížeče. V pravém spodním rámci se zobrazí formulář pro vkládání a úpravy anket. Formulář je rozdělen na tři záložky:
- Otázka – obsahuje vstupní pole pro vytvoření anketní otázky, svázání ankety se zprávou apod.
- Odpovědi – umožňuje definovat výběr odpovědí
- Výsledky – v režimu pouze pro čtení zobrazuje aktuální výsledky již existující ankety.
V první záložce se definuje anketní otázka a další vlastnosti ankety.
Přístupná pole jsou:
- Název ankety – název tak, jak se zobrazuje návštěvníkům webu
- Popis ankety – kromě názvu může mít anketa ještě další popisek, který lze opět na veřejně přístupné prezentaci zobrazit
- Kategorie – lze vybrat maximálně jednu kategorie; pole se nezobrazuje, pokud nejsou žádné kategorie definovány
- Datum – datum vypsání ankety
- ID zprávy – ID zprávy, ke které se eventuálně anketa vztahuje; nevyplňuje se, pokud se jedná o anketu, která nepatří ke konkrétní zprávě (a má se umístit např. na úvodní stránce)
- Aktivní – na anketu mohou návštěvníci webu hlasovat jen v případě, že tento příznak je zaškrtnut, v opačném případě je možné pouze zobrazovat výsledky ankety, hlasovací formulář žádné další hlasy nepřidá. Pokud je taková anketa umístěná ve zprávě, formátuje se při zobrazení vždy rovnou stylem po hlasování. V nabídce Nastavení – Globální – Starší ankety lze zvolit, zda seznam starších anket (/scripts/modules/vote/default.php) zobrazuje i aktivní ankety nebo jen ty, které již jsou uzavřeny.
- Zobrazovat výsledky bez hlasování – toto nastavení ovlivňuje, zda je možné výsledky ankety zobrazovat bez toho, že by uživatel hlasoval. Pokud zobrazíme stránku /scripts/modules/vote/vote.php?id=xxx, kde xxx je ID ankety a tato volba je zaškrtnuta, zobrazí se aktuální výsledky této ankety. V opačném případě se anketa vůbec nezobrazí a vyvolá se událost NOCURRENTRESULTS (viz kapitola Klíčová slova modulu).
- Tým – tým, kterému patří daná anketa a který tuto anketu může měnit
- Předpis – volí se jeden z připravených předpisů – způsobů formátování ankety
- Komentář – další textové pole, které lze u ankety zobrazovat na veřejné části prezentace. Lze využít např. tak, že při uzavírání ankety se zde dopíše nějaký názor redakce na výsledky, který se pak zobrazuje v seznamu starších anket.
Druhou záložkou jsou Odpovědi, kde se definuje seznam možných odpovědí na danou anketu.
Ve výchozím stavu se v této záložce nacházejí tři řádky pro tři odpovědi. Tlačítkem Přidat odpověď se přidává další řádek pro další možnou odpověď, naopak tlačítkem Odstranit se odstraňuje vybraný řádek. Použití těchto tlačítek se realizuje na klientské straně, to znamená, že v databázi anket se tyto změny promítnou až ve chvíli, kdy se tlačítkem Uložit celá anketa uloží.
Poslední záložka Výsledky zobrazuje v režimu pouze pro čtení aktuální výsledky dané ankety, tj. počet hlasů pro jednotlivé odpovědi a procentuální poměr odpovědí.
Po uložení formuláře s novou anketou je anketa okamžitě funkční v případě, že je svázána s nějakou zprávou (tj. je vyplněno pole ID zprávy). Chceme-li anketu použít na jiné stránce, např. na úvodní stránce serveru, je třeba postupovat dále. Ve formuláři je tlačítko Generovat. Toto tlačítko vygeneruje novou zprávu, v jejímž těle je HTML kód hlasovacího formuláře formátovaný dle zvoleného předpisu stylem před hlasováním. Zpráva je ve stavu Vloženo, je zařazena ve stromu kategorií do kategorie nastavené v předvolbách modulu a patří stejnému týmu jako samotná anketa. Tuto zprávu je třeba umístit na danou stránku stejným způsobem, jako se umísťují jiné zprávy, WebToDate styl pro vložení této zprávy na stránku musí obsahovat klíčové slovo pro tělo zprávy.
Jednou vygenerovaná anketa si pamatuje tento stav a zobrazuje tlačítko Zobrazit, kterým se přechází na formulář pro úpravy této vygenerované zprávy. Pokud již zpráva byla vygenerována a novu se použije tlačítko Generovat, dojde k přepisu vygenerované zprávy, nikoliv k založení nové zprávy.
Anketa, která má takto vygenerovanou zprávu, nepovoluje smazání. Je-li potřebné takovou anketu odstranit, správný postup je následující:
- Odstranit vygenerovanou zprávu ze všech stránek
- Smazat vygenerovanou zprávu
- Smazat anketu
Veřejné skripty
Prezentační skripty
V adresáři /scripts/modules/vote/ se nacházejí veřejně přístupné prezentační skripty modulu. Jedná se o následující skripty:
| Skript | Funkce |
| vote.php | Skript se používá pro hlasování v jedné anketě nebo zobrazení výsledků jedné ankety |
| default.php | Skript se používá pro zobrazení stránkovaného výpisu výsledků starších anket |
Kromě dvou výše uvedených skriptů je možné díky extenzi zmíněné v kapitole [#_Umístění_extenzí Umístění extenzí] zobrazovat dynamicky ankety ve zobrazení zpráv pomocí skriptu /scripts/detail.php. Zde je možné zobrazovat jak anketu nabízející možnost hlasovat tak výsledky hlasování.
Klíčová slova modulu
Následující klíčová slova lze použít v hlavičce nebo patičce stylu pro formátování anketního formuláře.
| Klíčová slova použitelná v hlavičce nebo patičce stylu ankety | ||
| Klíčové slovo | Význam | Poznámka |
| <!--WTD_VOTE(TARGETURL)--> | Cílové URL pro hlasovací formulář | Ve stylu se použije kód typu
<form action="<!--WTD_VOTE(TARGETURL)-->" method="post"> |
| <!--WTD_VOTE(ID)--> | ID ankety | |
| <!--WTD_VOTE(NAME)--> | Název ankety | |
| <!--WTD_VOTE(DESCRIPTION)--> | Popis ankety | |
| <!--WTD_VOTE(TOTAL)--> | Aktuální počet hlasů v dané anketě | |
| <!--WTD_VOTE(COMMENT)--> | Komentář | |
| <!--WTD_VOTE(RESULTSURL)--> | URL které zobrazuje stránku s průběžnými výsledky bez nutnosti hlasovat | Stránka /scripts/modules/vote/vote.php?results=1&id=xxx |
Následující klíčová slova se používají v těle stylu anket.
| Klíčová slova použitelná v těle stylu ankety | ||
| Klíčové slovo | Význam | Poznámka |
| <!--WTD_VOTE(BUTTONNAME)--> | Hodnota atributu name pro radiopřepínač | Používá se kód
<input type="radio" name="<!--WTD_VOTE(BUTTONNAME)-->" value="<!--WTD_VOTE(IDX)-->"> |
| <!--WTD_VOTE(IDX)--> | ID odpovědi | |
| <!--WTD_VOTE(ANSWER)--> | Text odpovědi | |
| <!--WTD_VOTE(VOTECOUNT)--> | Počet hlasů již hlasujících pro danou odpověď | |
| <!--WTD_VOTE(PERCENTAGE)--> | Procentuální zastoupení odpovědi v odevzdaných hlasech | Zaokrouhluje se na celé číslo |
| <!--WTD_VOTE(IMGWIDTH)--> | Vypočtená šířka obrázku pro grafické znázornění počtu odpovědí | Používá se HTML kód typu
<img src="/images/vote/voteblue.gif" height="12" width="<!--WTD_VOTE(IMGWIDTH)-->" /> |
| <!--WTD_VOTE(VOTEIDXURL)--> | URL pro hlasování klepnutím na odkaz | Používá se kód typu
<a href="<!--WTD_VOTE(VOTEIDXURL)-->"><!--WTD_VOTE(ANSWER)--></a> |
Následující klíčová slova se používají v HTML kódu předlohy pro zobrazení hlasovací stránky (tj. /scripts/modules/vote/vote.php?id=xxx).
Následující klíčová slova se používají v těle stylu anket.
| Klíčová slova použitelná v předloze pro hlasovací stránku | ||
| Klíčové slovo | Význam | Poznámka |
| <!--WTD_VOTE(VOTEFORM)--> | Hlasovací formulář | |
Kompletní kód pro zobrazování anket v hlasovací stránce vypadá typicky zhruba následovně:
<div class="anketa1">
<!--WTD_VOTE(VOTEFORM)-->
<p>
<!--WTD_IF(ALREADYUSED,"Na tuto anketu jste již odpovídal.")-->
<!--WTD_IF(NOCURRENTRESULTS,"Výsledky nejsou k dispozici.")-->
</p>
</div>
V předloze pro samostatnou hlasovací stránku lze rovněž použít následující konstrukce typu WTD_IF pro zobrazování eventuálních chybových hlášení:
| Možná chybová hlášení (předloha pro hlasovací stránku) | ||
| Klíčové slovo | Význam | Poznámka |
| <!--WTD_IF(ALREADYUSED,"…")--> | Text se zobrazí, pokud již uživatel na danou anketu hlasoval. Lze použít v předloze pro samostatnou hlasovací stránku. | Např. <!--WTD_IF(ALREADYUSED,"Na tuto anketu jste již odpovídal(a).")--> |
| <!--WTD_IF(VOTECLOSED,"…")--> | Text se zobrazí, pokud není anketa aktivní. Lze použít v předloze pro samostatnou hlasovací stránku. | Např. <!--WTD_IF(VOTECLOSED,"Anketa je uzavřena.")--> |
| <!--WTD_IF(NOCURRENTRESULTS,"…")--> | Text se zobrazí v případě, že se uživatel pokusí zobrazit anketu, která nemá povoleno samostatné zobrazení výsledků (nemá nastaveno zobrazovat výsledky bez hlasování). Lze použít v předloze pro samostatnou hlasovací stránku. | Např. <!--WTD_IF(NOCURRENTRESULTS,"Výsledky pro tuto anketu nejsou k dispozici.")--> |
| <!--WTD_IF(NOCOOKIE,"…")--> | Text se zobrazí v případě, že uživatel nemá povoleny cookies a hlasoval ze stránky se zprávou | Např. <!--WTD_IF(NOCOOKIE,"Hlasovat můžete jen se zapnutými cookies.")--> |
Následující klíčová slova se používají v předloze pro stránku zobrazující seznam starších anket.
| Klíčová slova použitelná v předloze pro seznam starších anket | ||
| Klíčové slovo | Význam | Poznámka |
| <!--WTD_VOTE(VOTELIST)--> | Seznam starších anket | |
| <!--WTD_VOTE(NAVIG)--> | Navigační stránkovací lišta | |
| <!--WTD_VOTE(RESULTLABEL)--> | Uvozující nadpis seznamu | Např. "Ankety 1 až 5 z 5" |
| <!--WTD_VOTE(CATEGORY)--> | Název kategorie | Vloží se název v případě, že skript má v URL nastaven parametr categid a daná kategorie existuje |
| <!--WTD_VOTE(CATEGORYID)--> | ID kategorie | Vloží se ID kategorie v případě, že skript má v URL nastaven parametr categid a daná kategorie existuje |
Dále je podporováno podmíněné vložení kódu podle toho, zda se vypisuje z nějaké kategorie: <!--WTD_IF(CATEGNULL,"…")--> resp. <!--WTD_IF(CATEGNOTNULL,"…")--> - dosadí podmíněně obsah v případě, že kategorie není resp. je vypisována. Příkladem použití je následující HTML kód použitelný v předloze pro výpis starších anket.
<h3><!--WTD_IF(CATEGNOTNULL,"Starší ankety z kategorie <!--WTD_VOTE(CATEGORY)-->")--><!--WTD_IF(CATEGNULL,"Starší ankety")--></h3>
Formulářová pole a další možné parametry prezentačních skriptů
Názvy formulářových polí je třeba přesně dodržet, jinak může být hlasovací formulář nefunkční.
Lze vytvářet anketní formuláře, kde jsou jednotlivé odpovědi prezentovány jako radiopřepínače, nebo jako odpovědi, na které je umístěn odkaz, klepnutím na odkaz se rovnou hlasuje.
V prvém případě je třeba, aby se jednalo o HTML formulář, v hlavičce stylu pro anketu je pak kód
<form action="<!--WTD_VOTE(TARGETURL)-->" method="post">
<input type="hidden" name="id" value="<!--WTD_VOTE(ID)-->">
Je zde třeba uvést pole s ID ankety (tj. kód name="id" value="<!--WTD_VOTE(ID)-->"). Názvy polí pro jednotlivé odpovědi se dosazují automaticky pomocí klíčového slova modulu, v těle stylu tedy musí být konstrukce typu
<input type="radio" name="<!--WTD_VOTE(BUTTONNAME)-->" value="<!--WTD_VOTE(IDX)-->">
V druhém případě (hlasování klepnutím na odpověď) se nejedná o HTML formulář. V těle stylu musí být kód typu
<a href="<!--WTD_VOTE(VOTEIDXURL)-->"><!--WTD_VOTE(ANSWER)--></a>
který dosadí potřebná URL automaticky.
Pro skript vote.php zobrazující hlasovací stránku lze v URL použít následující parametry:
- id – ID ankety
- tmplid – ID předlohy (pokud má být vynucena jiná předloha než je v modulu nastaveno)
- patternid - ID předpisu, který se má pro zobrazení ankety použít; pokud je uvedeno tmplid i patternid, použije se předloha dle tmplid ale ostatní nastavení dle patternid
- lid - ID jazyka v případě používání jiné jazykové mutace než výchozí
- locale - locale string jazyka (CS, EN, DE). Výsledek stejný jako v předchozím případě.
Skript default.php pro zobrazení výpisu starších anket používá v URL následující parametry:
- pg – číslo stránky v rámci stránkování seznamu
- categid – ID kategorie anket; pokud není uvedeno, vypisují se všechny ankety
- tmplid – ID předlohy (pokud má být vynucena jiná předloha než je v modulu nastaveno)
- lid - ID jazyka v případě používání jiné jazykové mutace než výchozí
- locale - locale string jazyka (CS, EN, DE). Výsledek stejný jako v předchozím případě.
Plánovaná úloha
Součástí modulu je i úloha pro Plánovač úloh nazvaná Ankety - odstranění starých dat. Tato úloha slouží k promazávání databáze a odstraňování již nepotřebných dat modulu, čímž se šetří využívaný databázový prostor. Konkrétně se jedná o záznamy o tom, zda uživatel již na anketu hlasoval nebo ne (v databázi tabulka VOTERECORD) – zejména v případě, že anketa je již uzavřena (tj. je označena jako neaktivní) jsou již tyto záznamy nepotřebné, protože na uzavřenou anketu již stejně nelze hlasovat.
Úloha má dva parametry:
- Všechny neaktivní – smažou se všechny záznamy o hlasování uživatelů pro všechny ankety, které jsou označeny jako neaktivní
- Počet dnů - smažou se všechny záznamy o hlasování uživatelů starší než zadaný počet dní (to znamená před kolika dny uživatel hlasoval, tento údaj nemá nic společného s vlastním datem vytvoření ankety)
[[Image:|ankety-planovac.jpg|center]]
Spouštění úlohy nemá vliv na zaznamenaný počet hlasů na jednotlivé odpovědi, tyto údaje nejsou spouštěním úlohy nijak měněny.
Úlohu doporučujeme spouštět v případě, že jsou ankety nasazeny ve větším měřítku a existuje na ně velký počet hlasujících uživatelů, doporučujeme využívat zejména nastavení Všechny neaktivní.
