Smartform pro web – Dokumentace API verze 1

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

Property ssl byla zrušena. Dříve nastavovala, zdali komunikace se serverem smartform.cz probíhá šifrovaně. Nyní se se serverem smartform.cz vždy komunikuje pomocí SSL.

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.

void setNewSlovakRegister(boolean enable)

Povolí/zakáže použití nového slovenského registru.

V roce 2021 jsme pro slovenské adresy začali používat nový slovenský registr adres, spravovaný slovenskou státní správou. Jeho hlavní výhodou je, že je denně aktualizován. Kvůli zpětné kompatibilitě této verze API jsme ale ponechali jako defaultní původní registr slovenských adres. Touto metodou lze tedy přepnout na nový slovenský registr adres.

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ým identifikátorem – viz SmartFormInstance).

Pokud instance Smartformu s tímto ID neexistuje, funkce vrací null.

String[] getInstanceIds()

Vrátí pole identifikátorů všech formulářových instancí na stránce. Podrobnosti k identifikátorům viz smartform.getInstance(instanceId).

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 unbindForm(instanceId)

Ve formuláři se zadaným instanceId zruší napojení na Smartform. U tohoto formuláře přestanou fungovat našeptávače a validace adres.

Identifikátorem instanceId se rozumí název CSS třídy uvedené u všech políček formuláře tvořící instanci Smartformu. Identifikátor vždy začíná řetězcem "smartform-instance".

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 enableSetAutocomplete(boolean enable)

Povolí/zakáže Smartformu nastavit hodnotu atributu "autocomplete" u textových políček.

Defaultní chování je takové, že Smartform nastavuje atribut "autocomplete" na hodnotu "off". Metodu můžete použít v situaci, kdy chcete nastavit hodnotu atributu "autocomplete" jinou než je "off". Zavolejte ji v callbacku smartform.beforeInit.

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í.

void setCountry(String countryCode)

Pro daný formulář nastavuje zemi (její kód), z jaké se má našeptávat.

V současnosti je možné zadat tyto kódy:

• CZ (Česká republika)
• SK (Slovenská republika)

Defaultně je v každém formuláři nastaveno, že se našeptávájí adresy z České republiky.

Příklad použití metody setCountry() najdete na Demo – slovenské adresy.

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Č)
• smartform-whole-address (celá adresa)

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 – výsledek validace – viz ValidationResultType.
• addressArray je pole zvalidovaných adres (typicky pole obsahuje žádnou nebo jednu adresu), každá adresa obsahuje atributy z AddressFieldType.

boolean isAddressValid()

Vrátí výsledek poslední validace – true, pokud byla nalezena právě jedna adresa (HIT).

void 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 setZIndex( int zIndex )

Nastavuje z-index (CSS vlastnost určující prioritu při překrývání) našeptávacím oknům. Smartform se snaží určit hodnotu z-indexu automaticky, tato metoda slouží v případech, kdy hodnota nastavená Smartformem nevyhovuje.

void setSuggestionFormatter( function )

Nastaví callback, který umožňuje měnit text zobrazený v našeptáváči. Pokud je callback nastaven, je volán při zobrazení každého řádku v našeptávači.

Návratová hodnota callbacku bude použita jako text v našeptávači. Pokud callback vrátí null, použije se defaultní text našeptávače.

Při volání callbacku mu budou předány tyto parametry

• suggestion – instance AddressSuggestion, reprezentuje jeden řádek v našeptávacím okně
• fieldType – textový identifikátor typu políčka – viz SmartFormInstance.getBox(id) ("smartform-street-and-number", "smartform-city", …)

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 – DOM element textového pole
• text – řetězec, který by měl být vyplněn do textového pole
• fieldType – textový identifikátor typu políčka – viz SmartFormInstance.getBox(id)
• suggestion – instance AddressSuggestion, reprezentuje jeden řádek v našeptávacím okně

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 true.

void setSuggestContext( contextType, contextAreaItems )

Nastavení oblasti, ze které se adresy našeptávají.

Parametry:

• contextType – řetězec s typem omezení oblasti našeptávání. Možné jsou dvě hodnoty:
  • FILTER – adresy se našeptávají pouze ze zadané oblasti.
  • PREFERENCE – adresy se našeptávají přednostně ze zadané oblasti. Adresy mimo zadanou oblast se našeptávají také, za adresami z nastavené oblasti.
• contextAreaItems – vymezení našeptávací oblasti. Jde o pole ve tvaru [ [contextAreaCodeType, contextAreaCode], … ]. Položky seznamu se skládají z
  • contextAreaCodeType – řetězec s typem adresní entity. Může nabývat těchto hodnot
    • MUNICIPALITY_CODE – obec
    • DISTRICT_CODE – okres
    • REGION_CODE – kraj
  • contextAreaCode – kód entity – obce, okresu nebo kraje.

Pokud budeme chtít, aby našeptávač našeptával jen adresy z obce Ubušínek (kód 549959), okresu Pelhřimov (kód 3304) nebo Zlínského kraje (kód 141), dosáhneme toho následujícím voláním:

smartform.getInstance().setSuggestContext( 'FILTER', [['MUNICIPALITY_CODE', 549959], ['DISTRICT_CODE', 3304], ['REGION_CODE', 141]] )

Při nastavování našeptávací oblasti se mohou hodit kódy českých krajů a okresů. Kódy obcí získáte v demu web-service s validací názvu obcí (v odpovědi hledejte řádek s MUNICIPALITY_CODE).

void clearSuggestContext()

Odstraní nastavený našeptávací kontext. Viz metoda setSuggestContext(contextType, contextAreaItems).

void setOracleEnabled(value)

Podle hodnoty boolean parametru zapne/vypne našeptávač u tohoto políčka.

void 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.

void setPopupContainerId(String id)

Nastaví id prvku, do kterého má být našeptávací popup vložen. Našeptávací popup okno se standardně vkládá na konec prvku body, touto metodou lze toto chování změnit. Při volání této metody nejspíš budete potřebovat zavolat i metodu SmartFormInstance.setPopupAttributePosition(String position).

void setPopupAttributePosition(String position)

Nastaví hodnotu CSS atributu position našeptávacího popupu.

Našeptávácí popup okno má standardně nastaven atribut position na hodnotu absolute.

Pokud se zavolá tato metoda, nenastavuje Smartform u popupu atributy top a left.

boolean isWholeAddress()

Zdali se jedná o celou (konkrétní) adresu.

String getValue( String fieldType )

Vrací text, který bude vyplněn do input boxu daného typu. Parametr fieldType může nabývat následujících hodnot

• "smartform-street" – ulice
• "smartform-number" – číslo domu
• "smartform-street-and-number" – ulice a číslo domu
• "smartform-city" – zformátovaný název obce (může obsahovat poštu – např. „Hořice v Podkrkonoší“ – nebo název městské části – např. „Praha 4 - Podolí“)
• "smartform-municipality" – čistý název obce (např. „Hořice“, „Praha“)
• "smartform-zip" – PSČ
• "smartform-whole-address" – celá adresa

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ů)

Atributy:

• CODE (ID v databázi RÚIAN – dříve UIR-ADR)
• UIRADR_CODE (nepoužívejte, místo toho použijte CODE)
• BUILDING_CODE (kód stavebního objektu)
• 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)
• STREET_CODE (kód ulice)
• CITY (obec)
• CITY_CODE (kód obce)
• PART (část obce)
• PART_CODE (kód části obce)
• ZIP (PSČ)
• POST (pošta)
• DISTRICT (okres)
• DISTRICT_CODE (kód okresu)
• REGION (kraj)
• REGION_CODE (kód kraje)
• CITY_AREA_1 (dělení obcí – v ČR odpovídá městským částím)
• CITY_AREA_1_CODE (dělení obcí – kód)
• CITY_AREA_2 (dělení obcí – v ČR odpovídá městským obvodům – v Praze je to "Praha 1" – "Praha 10")
• CITY_AREA_2_CODE (dělení obcí – kód)
• CITY_AREA_3 (dělení obcí – v ČR odpovídá správním obvodům – v Praze je to "Praha 1" – "Praha 22")
• CITY_AREA_3_CODE (dělení obcí – kód)
• FIRST_LINE (první řádka adresy)
• SECOND_LINE (druhá řádka adresy)
• ADDRESS_WHOLE (celá adresa na jedné řádce)
• COORD_X (JTSK souřadnice x)
• COORD_Y (JTSK souřadnice y)
• GPS_LAT (GPS souřadnice – šířka)
• GPS_LONG (GPS souřadnice – délka)
• COUNTRY (název státu)
• COUNTRY_CODE (zkratka státu – "CZE" nebo "SVK")
• LAND_LOT_NUMBER_1 (Kmenové číslo parcely)
• LAND_LOT_NUMBER_2 (Poddělení (pořadové číslo nové parcely v rámci původní parcely))
• CADASTRAL_DISTRICT_NAME (Název katastrálního území)
• CADASTRAL_DISTRICT_CODE (Číslo katastrálního území)
• BUILDING_WITH_LIFT (Informace o výtahu (hodnoty "true", "false", null))
• NUMBER_OF_STOREYS (Počet podlaží v budově)
• NUMBER_OF_FLATS (Počet bytů v budově)
• FLOOR_AREA (Podlahová plocha budovy [m2])

Ukázky použití skrytých polí:

• Příklad práce se skrytými poli
• Příklad práce s identifikátory instancí