Příručka vývojáře

Dokumentace - API

Obsah

Objekt smartform

Centrální objekt API, stará se o inicializaci, přihlašování uživatele a umožňuje přístup k jednotlivým instancím Smartformu. Tento objekt je singleton a je k dispozici po celou dobu existence stránky.

Atributy:

beforeInit
Sem lze vložit callbackovou funkci, která bude zavolána po načtení stránky - v okamžiku, kdy je možné přistupovat k objektu smartform a procházet instance formulářů a jejich políčka. Využívat služby Smartformu je ale možné až od okamžiku, kdy se spustí callbacková funkce smartform.afterInit
afterInit
Sem lze vložit callbackovou funkci, která bude zavolána po inicializaci a přihlášení k službám Smartformu pomocí ID uživatele nastaveného v smartform.beforeInit. V okamžiku zavolání této funkce je možné využívat všechny služby Smartformu podle typu licence.
ssl
Hodnota typu boolean, která určuje, jestli bude komunikace se Smartform serverem probíhat šifrovaně pomocí protokolu SSL. Výchozí hodnota je false.
Nastavení zabezpečení je nutné nastavit ještě před přihlášením k službám Smartformu (v smartform.beforeInit). Pro zajištění celkového zabezpečení stránky je potřeba také načítat skript Smartformu ze zabezpečené stránky: 
https://secure.smartform.cz/api/v1/smartform.js

Metody:

void setClientId(clientId)
Nastaví klientské ID - identifikátor klienta, který se přihlašuje k využívaní služeb Smartformu. Pro správné fungování Smartformu musí být klientské ID nastaveno během inicializace - nejlépe v metodě vložené do smartform.beforeInit. Nastavujete-li clientID jinde, pak je potřeba po jeho nastavení vyvolat inicializaci metodou smartform.rebindAllForms.
SmartFormInstance getInstance(instanceId)
Vrátí instanci formuláře podle jeho přiděleného identifikátoru - instanceId.
Tento identifikátor musí být uveden jako CSS třída u všech HTML elementů <input>, které mají být součástí tohoto formuláře (musí být v seznamu atributu class). Všechny identifikátory musí povinně začínat řetězcem smartform-instance (výjimkou je implicitní instance s prázdnýn identifikátorem - viz SmartFormInstance).
Pokud instance Smartformu s tímto ID neexistuje, funkce vrací null.
void rebindAllForms(clear, doneCallback)
Vynutí reinicializaci všech objektů Smartformu na stránce. Projde znovu celý HTML dokument, najde všechny INPUT elementy určené pro Smartform a sloučí je do nových instancí Smartformu.
Pokud je clear=false, předchozí objekty SmartFormInstance se nesmažou, pouze se obnoví jejich vstupní a výstupní elementy. To se hodí, pokud se nezměnil seznam instancí ani názvy jejich identifikátorů.
Do parametru doneCallback lze nastavit funkci, která se zavolá po reinicializaci a přihlášení k službám Smartformu. Kód ve smartform.afterInit se automaticky nevykonává, případně ho volejte manuálně.
void setFocusNextFieldEnabledForAll(on)
Nastavení boolean příznaku, jestli má být po úspěšném výběru celé adresy z našeptávače nastaven focus na další pole formuláře, které následuje za adresními políčky. Implictně je tento příznak nastaven na true.
void setBackgroundColor(color)
Nastaví barvu pozadí okna našeptávače u všech instancí.
void setForegroundColor(color)
Nastaví barvu písma v našeptávači u všech instancí.
void setSelectionBackgroundColor(color)
Nastaví barvu pozadí označené položky našeptávače u všech instancí.
void setBorderColor(color)
Nastaví barvu okraje okna našeptávače u všech instancí.

Class SmartFormInstance

Třída slouží k nastavování vlastností jedné konkrétní instance Smartform formuláře a k přístupu k jednotlivým vstupním a výstupním elementům formuláře.

Na HTML stránce je totiž možno umístit více adresních formulářů a v takovém případě je potřeba i více instancí Smartformu. HTML elementy určené pro jednotlivé instance Smartformu se pak slučují pomocí identifikátoru instance, kterým je CSS třída (uvedená v atributu class u všech HTML elementů instance Smartformu). Identifikátor musí povinně začínat řetězcem "smartform-instance". Ke každé instanci Smartformu je možné získat přístup voláním metody smartform.getInstance(id), přičemž parametrem je právě identifikátor instance.

Metody:

SmartFormSuggestBox getBox(id)
Vrátí objekt zadávacího políčka s našeptávačem. id je identifikátor typu políčka, který musí být uveden v atributu class elementu input - možné hodnoty jsou:
  • smartform-street (ulice)
  • smartform-number (číslo domu)
  • smartform-street-and-number (ulice a číslo domu)
  • smartform-city (obec)
  • smartform-zip (PSČ)
Pokud políčko s daným ID neexistuje, funkce vrátí null.
void setStatusBox(boxId)
Nastaví element, do kterého se bude vkládat informace o validnosti zadané adresy. boxId je id <div> elementu, který bude sloužit jako status box.
String getId()
Vrátí identifikátor instance uvedený v atributu class příslušného elementu input.
void setAllOraclesEnabled(value)
Podle hodnoty boolean parametru zapne/vypne našeptávače u všech políček instance.
void addAnnounceCallback(function)
Přidá funkci do seznamu funkcí, které se vykoná po příchodu announce service (výsledek validace zadané adresy). Callback funkce se zavolá s parametry (validationType, addressArray);
  • validationType je typu String - jedna z možností enumerace smartform.ValidationResultType
  • addressArray je pole objektů s položkami typu String; atributy jsou stejné jako v enumeraci smartform.AddressFieldType
boolean isAddressValid()
Vrátí výsledek poslední validace - true, pokud byla nalezena právě jedna adresa (HIT).
boolean isAddressValidating()
Indikuje relevanci výsledku funkce isAddressValid vzhledem k datům zadaným ve formuláři. Pokud isAddressValidating() vrátí true, požadavek na ověření validnosti zadané adresy se ještě neodeslal nebo na něj zatím nepřišla odpověď.
void setBackgroundColor(color)
Nastaví barvu pozadí okna našeptávače u všech zadávacích políček.
void setForegroundColor(color)
Nastaví barvu písma v našeptávači u všech zadávacích políček.
void setSelectionBackgroundColor(color)
Nastaví barvu pozadí označené položky našeptávače u všech zadávacích políček.
void setBorderColor(color)
Nastaví barvu okraje okna našeptávače u všech zadávacích políček.
void setFocusNextFieldEnabled(on)
Nastavení boolean příznaku, jestli se má po výběru celé adresy z našeptávače označit políčko následující za posledním zadávacím políčkem adresy.
void setSelectionCallback(function)
Nastaví callback pro vyplnění políček výběrem z našeptávače. Pro každé políčko bude zavolána nastavená funkce s parametry (element, text, fieldType): element je DOM element textového pole, text je řetězec, který byl vybrán z našeptávače, fieldType je textový identifikátor typu políčka (viz SmartFormInstance.getBox(id)). Výchozí chování Smartformu je vyplnit text do políčka, tj. zavolat 
element.value = text;
Vybraný text se políčku nastaví automaticky v případě, že callback není nastaven, nebo také když je návratová hodnota callbacku false.

Parametr color

Identifikátor barvy pro nastavení vzhledu menu našeptávače. Lze použít jakékoliv identifikátory barev platné v CSS, tedy HTML názvy (green, black, yellow ...) nebo RGB kódy barev (např. #803020), zkrácené RGB kódy (např. #f90), funkci rgb nebo rgba (např. rgb(255,0,0), rgba(100%, 0%, 0%, 0.7)), funkci hsl nebo hsla (např. hsl(240, 100%, 50%)). Některé prohlížeče nemají ještě podporu pro CSS3, takže některé identifikátory nefungují. HTML kódy a názvy a funkce rgb by měly fungovat všude. Více na w3.org.

Class SmartFormSuggestBox

Objekt jednoho zadávacího políčka adresy. Vstupní políčko musí být označeno identifikátorem části adresy (viz SmartFormInstance.getBox(id)) v atributu class elementu <input>.

Metody:

void setOracleEnabled(value)
Podle hodnoty boolean parametru zapne/vypne našeptávač u tohoto políčka.
boolean isOracleEnabled()
Zjistí, jestli je našeptávač zapnutý.
void setLimit(limit)
Nastaví maximální počet položek v menu našeptávače.
int getLimit()
Vrátí limit počtu položek v menu našeptávače.

Enum ValidationResultType

Výčet možných výsledků validace. Každá položka objektu má hodnotu stejnou jako název. Objekt je součástí objektu smartform (smartform.ValidationResultType).

Atributy:

  • HIT (právě jedna odpovídající adresa)
  • MANY (více odpovídajících adres)
  • TOOMANY (jako MANY, ale v seznamu adres jsou jen některé)
  • NOTHING (žádná odpovídající adresa nenalezena)
  • INSUFFICIENT_DATA (bylo zadáno malo vstupních parametrů)

Enum AddressFieldType

Výčet atributů u každé adresy ve výsledku validace. Každá položka objektu má hodnotu stejnou jako název. Objekt je součástí objektu smartform (smartform.AddressFieldType).

Atributy:

  • UIRADR_CODE (ID v databázi uir-adr)
  • COORD_X (souřadnice x)
  • COORD_Y (souřadnice y)
  • NUMBER_ORIENTACNI (orientační číslo)
  • CHAR_ORIENTACNI (písmeno orientačního čísla)
  • NUMBER_POPISNE (popisné číslo)
  • NUMBER_EVIDENCNI (evidenční číslo)
  • NUMBER_WHOLE (celé číslo domu - např. ev.č. 179/or.č. 42)
  • STREET (ulice)
  • CITY (město)
  • PART (část města)
  • ZIP (PSČ)
  • POST (pošta)
  • DISTRICT (okres)
  • REGION (kraj)
  • FIRST_LINE (první řádka adresy)
  • SECOND_LINE (druhá řádka adresy)
  • ADDRESS_WHOLE (celá adresa na jedné řádce)

Skrytá (hidden) vstupní pole formuláře

Skrytá pole jsou vyplněna podle toho, co mají nastaveno v atributu class. Možné hodnoty odpovídají výše uvedenému enumu AddressFieldType.

Například:
  • smartform-field-UIRADR_CODE
  • smartform-field-NUMBER_ORIENTACNI
  • smartform-field-REGION

V případě, že ve formuláři je použito vícero Smartformů, je třeba i pro skrytá pole v atributu class použít identifikátor instance (viz SmartFormInstance).

Hlavní navigace: