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. Nejprve se zaregistrujte v administrační aplikaci, tím získáte své clientId, které později vložíte do zdrojového kódu pro přihlášení k Smartformu.
  2. Přidejte všechny domény, na kterých chcete Smartform provozovat. Zaregistruje si i domény, na kterých budete Smartform testovat.
  3. Poté si v administrační aplikaci aktivujte službu „Poštovní adresy“ a podle pokynů proveďte platbu. 
  4. 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>
  5. 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. Z tohoto důvodu doporučujeme dát při výběru této verzi přednost.

Odkazy na obě verze:

Návod na přechod mezi těmito verzemi najdete na stránce Přechod z API verze 1 na verzi 2.

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 potř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 demonstrací dalších možností Smartformu najdete v ukázce.

Inicializace a obnova Smartformu

Jeden z důležitých kroků při používání Smartformu je inicializace formulářů, která se provádí vždy po načtení stránky. Pokud však dynamicky měníte obsah stránky a například přidáváte nové instance smartformu v průběhu života stránky, budete potřebovat zavolat metodu smartform.rebindAllForms(). Tato metoda zajistí, že všechny nové instance smartformu budou správně reinicializovány.

Je také důležité si uvědomit, že některé JavaScriptové frameworky, jako například AngularJS nebo Vue.js, dynamicky generují HTML prvky až po načtení stránky prohlížečem. Toto může znamenat, že některé instance smartformu mohou být vytvořeny až po inicializaci. V takovém případě je opět nutné zavolat metodu rebindAllForms na objektu smartform, aby byly tyto dynamicky generované instance správně obnoveny. Tím je zajištěno, že bez ohledu na to, kdy nebo jak jsou instance smartformu vytvořeny, budou vždy správně inicializovány a připraveny k použití.

Příklad vytvoření nového formuláře s políčkem pro našeptávání adresy a následnou reinicializaci:

// přidání nového HTML prvku
$('body').append('<form> <input type="text" class="smartform-adress-whole-address"> </form>');

// znovu navázání smartformu
smartform.rebindAllForms();

Následující ukázka ilustruje konkrétní příklad použití.

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 a podrobnější informace jsou v dokumentaci API.

Omezení oblasti našeptávání

Při použití našeptávače je možné omezit oblast, ze které se adresy našeptávají, a to pomocí dvou funkcí:

  1. Filtrování – při našeptávání se nabízí jen adresy ze zadané oblasti

  2. Přednost – při našeptávání se nabízí přednostně adresy ze zadané oblasti. Adresy mimo zadanou oblast se našeptávají také, za adresami z nastavené oblasti. Zadávat lze kódy obcí, okresů a krajů.

Možnost omezení oblasti našeptávání adres si můžete vyzkoušet pomocí jednoduchého dema.