Dokumentace - základní postupy

Obsah

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

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. Registrovat nemusíte domény typu
    file://
    a
    http://localhost
    - tam funguje Smartform vždy.
  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://secure.smartform.cz/api/v1/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 initialize() {
              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-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)
    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-street" />
      <input type="text" class="smartform-number" />
      <input type="text" class="smartform-city" />
      <input type="text" class="smartform-zip" />
    

    Je možné použít libovolnou kombinaci zadávacích polí.

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

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-street-and-number" />
        <input id="obec_zakaznik" type="text" class="smartform-instance-zakaznik smartform-city" />
        <input id="psc_zakaznik" type="text" class="smartform-instance-zakaznik smartform-zip" />
    </div>

    <div >
        <input id="ulice_dodaci" type="text" class="smartform-instance-dodaci smartform-street" />
        <input id="ulice_dodaci" type="text" class="smartform-instance-dodaci smartform-number" />
        <input id="obec_dodaci" type="text" class="smartform-instance-dodaci smartform-city" />
        <input id="psc_dodaci" type="text" class="smartform-instance-dodaci smartform-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.

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

  2. 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().addAnnounceCallback(announceCallback);
        }
        
        function announceCallback(validationType, addressArray) {
            if (validationType == smartform.ValidationResultType.HIT) {
                // podle vstupních dat byla nalezena jedna validní adresa            
                var address = addressArray[0].ADDRESS_WHOLE;
                alert('Celá adresa: ' + address);            
            }
        }        
      

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

    Podrobnější informace jsou v dokumentaci API.

Asynchronní načítání javascriptu

Od dubna 2018 je možné načítat skript smartform.js do stránek asynchronně. Díky asynchronnímu načítání javascriptu

  • se HTML stránka vykreslí rychleji, protože její zpracování prohlížečem není blokováno načítáním javascriptu.
  • nehrozí problémy s vykreslením stránky při případném výpadku serveru smartform.cz.
Pokud jste Smartform do svých stránek implementovali před dubnem 2018, patrně skript smartform.js vkládáte synchronním způsobem. Jak své stránky upravit najdete v návodu na asynchronní vkládání skriptu smartform.js.

Problém s překrýváním dvou našeptávačů v Google Chrome

V novějších verzích prohlížeče Chrome (únor 2018) se může přes našeptávač Smartformu zobrazovat ještě našeptávač prohlížeče, ve kterém se našeptávají v prohlížeči uložené adresy. Jak tomu zabránit se dočtete na stránce Překrývání našeptávačů v Google Chrome.


Hlavní navigace: