Základní postupy

Obsah

Začínáme se Smartformem – použití v jednoduchém HTML formuláři

Máte již registrovanou doménu a aktivovanou službu „Poštovní adresy“? Pokud ano, pokračujte podle následujícího postupu. Pokud ne, registraci domény a aktivaci služby provedete podle postupu uvedeném na stránce Začínáme.

Pro základní funkci Smartformu – obohacení vstupních políček adresy ve formuláři o našeptávač jsou nezbytné následující kroky:

  1. Zaregistrovat se v administrační aplikaci (pokud jste nový uživatel). Tím získáte své clientId, které později vložíte do zdrojového kódu pro přihlášení k Smartformu.
  2. V administrační aplikaci přidat všechny domény, na kterých hodláte Smartform provozovat. Zaregistruje si i domény, na kterých budete Smartform testovat.
  3. A teď už se vrhneme na úpravu HTML stránky s formulářem. Do hlavičky (head) je potřeba přidat pár řádků s Javascriptem
    • odkaz na Javascript kód Smartformu
       <script type="text/javascript" src="https://client.smartform.cz/v2/smartform.js" async>
       </script>
    • a inicializační skript – zde jako parametr funkce smartform.setClientId doplňte clientId, které máte přiděleno v administrační aplikaci
        <script type="text/javascript">
        var smartform = smartform || {};
        
        smartform.beforeInit = function () {
              smartform.setClientId('[zde doplňte klientské ID]');
        }
        </script>
  4. Potom už stačí jenom správně označit zadávací pole ve formuláři pro adresu. Pro jednotlivé části adresy jsou definované identifikátory:
    • smartform-address-street (ulice)
    • smartform-address-number (číslo domu)
    • smartform-address-street-and-number (ulice a číslo domu)
    • smartform-address-city (obec)
    • smartform-address-city-extended (rozšířený název obce, např. Praha 4 – Podolí nebo Liberec 15)
    • smartform-address-zip (PSČ)
    • smartform-address-whole-address (celá adresa)

Vstupní <input> elementy označíte tak, že do atributu class přidáte příslušný identifikátor - tedy např.:

  <input type="text" class="smartform-address-street-and-number" />
  <input type="text" class="smartform-address-city" />
  <input type="text" class="smartform-address-zip" />

Je možné použít libovolnou kombinaci zadávacích polí. Více informací o kombinacích naleznete na stránce Možnosti rozvržení adresního formuláře

V praxi můžete vidět jednoduchý formulář v ukázce.

Verze dokumentace API

Od června 2022 je k dispozici nová verze dokumentace API. Od staré verze se liší hlavně tím, že používá jiný, denně aktualizovaný, státem spravovaný registr slovenských adres a obsahuje všechny ukázky zdrojových kódů. Z tohoto důvodu doporučujeme dát při výběru této verzi přednost.

Odkazy na obě verze:

Více poštovních adres v jednom HTML formuláři

Pokud potřebujete zadat víc než jednu adresu na jedné stránce, je pořeba vstupní políčka jednotlivých adres odlišit, aby je mohl Smartform seskupit. K tomu slouží další identifikátor, který se přidá do atributu class elementů <input>. Tento identifikátor musí začínat řetězcem "smartform-instance" a jeho uvedením se políčko začlení do tzv. instance Smartformu, která je z API dostupná právě přes svůj identifikátor.

Pokud je na stránce jen jeden formulář, není vůbec potřeba identifikátor zadávat. Použije se totiž implicitní identifikátor instance (což je prázdný řetězec).

Následuje příklad formuláře se dvěma vstupními adresami:

  <form>
    <div>
        <input id="ulice_zakaznik" type="text" class="smartform-instance-zakaznik smartform-address-street-and-number" />
        <input id="obec_zakaznik" type="text" class="smartform-instance-zakaznik smartform-address-city" />
        <input id="psc_zakaznik" type="text" class="smartform-instance-zakaznik smartform-address-zip" />
    </div>

    <div >
        <input id="ulice_dodaci" type="text" class="smartform-instance-dodaci smartform-address-street" />
        <input id="ulice_dodaci" type="text" class="smartform-instance-dodaci smartform-address-number" />
        <input id="obec_dodaci" type="text" class="smartform-instance-dodaci smartform-address-city" />
        <input id="psc_dodaci" type="text" class="smartform-instance-dodaci smartform-address-zip" />
    </div>
  </form>  

Praktický příklad s demostrací dalších možností Smartformu najdete v ukázce.

Získání dalších informací o zadané adrese

Při zadávání adresy Smartform průběžně zadanou adresu validuje (kontroluje zdali skutečně existuje). Máme dvě možnosti, jak se k výsledku validace dostat. Buď můžeme použít skryté (hidden) vstupní prvky formuláře, které smartform automaticky vyplní, nebo univerzálnější řešení pomocí callbacku.

Pomocí skrytých (hidden) prvků

Do formuláře můžeme přidat skrytá (hidden) vstupní políčka, do kterých Smartform vyplňuje části adresy, když průběžnou validací zjistí, že adresa skutečně existuje. Část adresy, která se vloží do daného hidden políčka, je určena atributem class. Hodnota atributu musí specifický formát. Následující příklad vloží do vstupního políčka cela_adresa celou adresu.

  <input type="hidden" class="smartform-field-FORMATTED_ADDRESS_WHOLE" name="cela_adresa">

Jména atributu jsou ve tvaru "smartform-field-JMENO_ATRIBUTU". Všechny možné hodnoty, které smartform umí vrátit, najdeme v dokumentaci API.

Celá ukázka je v příkladech použití.

Použití callbacku

Pokud potřebujeme obecnější řešení nebo chceme s adresou dále pracovat, můžeme k průběžné validaci připojit vlastní callback funkci.

    smartform.afterInit = function () {
        smartform.getInstance().addressControl.addValidationCallback(validationCallback);
    }
    
    function validationCallback(validationResult) {
        if (validationResult.result.type == smartform.AddressValidationResultType.HIT) {
            // podle vstupních dat byla nalezena jedna validní adresa            
            var address = validationResult.result.addressArray[0].FORMATTED_ADDRESS_WHOLE;
            alert('Celá adresa: ' + address);            
        }
    }  

Příklad praktického použití najdete v ukázce.

Podrobnější informace jsou v dokumentaci API.