Základní postupy

Obsah

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

Pro základní funkci Smartformu (obohacení vstupních políček firmy 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 „Firmy“ 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ž jenom stačí označit zadávací pole ve formuláři pro firmu. Pro jednotlivé části firmy jsou definované identifikátory:
    • smartform-company-name (název firmy)
    • smartform-company-registration-number (IČO)
    • smartform-company-vat-number (DIČ)
  6. Součástí formuláře mohou být také výstupní políčka, do kterých Smartform zapisuje adresu firmy při výběru firmy z našeptávače. Použít můžete následující identifikátory:
    • smartform-company-address-street (ulice)
    • smartform-company-address-number (číslo domu)
    • smartform-company-address-street-and-number (ulice a číslo domu)
    • smartform-company-address-city (obec)
    • smartform-company-address-city-extended (obec – zformátovaný název)
    • smartform-company-address-zip (PSČ)
    • smartform-company-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-company-name" />
<input type="text" class="smartform-company-registration-number" />
<input type="text" class="smartform-company-vat-number" />

<input type="text" class="smartform-company-address-whole-address" />

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

Dokumentace API

Aktuální verze API – verze 2 – obsahuje mimo jiné i funkce pro našeptávání a validaci firem. Vše potřebné najdete v dokumentaci. Pro ovládání našeptávání a validace firem použijte objekt SmartformInstance.companyControl.

Propojení našeptávání firem a adres

Našeptávání firem a poštovních adres lze propojit dvěma způsoby. V obou jsou v HTML formuláři políčka pro firemní údaje i poštovní adresy.

První možností je adresní políčka používat jen pro zápis sídla firmy, je-li vybrána firma z našeptávače. Samotná adresa nemá žádný našeptávač. Tuto možnost ilustruje následující HTML formulář:

<form>
  <input class="smartform-company-name" id="smartform_nazev" placeholder="Název firmy" type="text"/>
  <input class="smartform-company-registration-number" id="smartform_ico" placeholder="IČO" type="text"/>
  <input class="smartform-company-vat-number" id="smartform_dic" placeholder="DIČ" type="text"/>

  <input class="smartform-company-address-street-and-number" id="smartform_ulice_a_cislo" placeholder="Ulice a číslo" type="text"/>
  <input class="smartform-company-address-city" id="smartform_obec" placeholder="Obec" type="text"/>
  <input class="smartform-company-address-zip" id="smartform_zip" placeholder="PSČ" type="text"/>
</form>

Druhá možnost vychází z té první – do políček s adresou je zapsána adresa sídla při výběru firmy z našeptávače. Když do atributu class přidáte identifikátory pro zadávání poštovní adresy (např. smartform-address-street-and-number), získají adresní políčka našeptávače pro zadání adresy. Našeptávání poštovní adresy je nezávislé na obsahu firemních políček. Pro tuto možnost musíte mít v administrační aplikaci aktivovanou službu „Poštovní adresy“. 

Tuto možnost ilustruje následující HTML formulář:

<form>
  <input class="smartform-company-name" id="smartform_nazev" placeholder="Název firmy" type="text"/>
  <input class="smartform-company-registration-number" id="smartform_ico" placeholder="IČO" type="text"/>
  <input class="smartform-company-vat-number" id="smartform_dic" placeholder="DIČ" type="text"/>
  
  <input class="smartform-company-address-street-and-number smartform-address-street-and-number" id="smartform_ulice_a_cislo" placeholder="Ulice a číslo" type="text"/>
  <input class="smartform-company-address-city smartform-address-city" id="smartform_obec" placeholder="Obec" type="text"/>
  <input class="smartform-company-address-zip smartform-address-zip" id="smartform_zip" placeholder="PSČ" type="text"/>
</form>

Obě možnosti najdete v následující ukázce.

Více firemních formulářů na jedné stránce

Pokud potřebujete zadat víc než jednu firmu na jedné stránce, je potřeba vstupní políčka jednotlivých firem 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 firmami:

<form>
  <div>
    <input id="nazev_firmy_1" type="text" class="smartform-instance-firma-1 smartform-company-name" />
    <input id="ico_firmy_1" type="text" class="smartform-instance-firma-1 smartform-company-registration-number" />
    <input id="dic_firmy_1" type="text" class="smartform-instance-firma-1 smartform-company-vat-number" />
  </div>

  <div >
     <input id="nazev_firmy_2" type="text" class="smartform-instance-firma-2 smartform-company-name" />
     <input id="ico_firmy_2" type="text" class="smartform-instance-firma-2 smartform-company-registration-number" />
     <input id="dic_firmy_2" type="text" class="smartform-instance-firma-2 smartform-company-vat-number" />
  </div>
</form>

Praktický příklad 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í firmy a následnou reinicializaci:

// přidání nového HTML prvku
$('body').append('<form> <input type="text" class="smartform-company-name"> </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 údajů o firmě

Při zadávání firmy Smartform průběžně zadanou firmu 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 firmy, když průběžnou validací zjistí, že firma skutečně existuje. Část firmy , 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 datum vzníku firmy.

  <input type="hidden" class="smartform-company-field-CREATION_DATE" name="datum_vzniku">

Jména atributu jsou ve tvaru "smartform-company-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 firmou dále pracovat, můžeme k průběžné validaci připojit vlastní callback funkci.

    smartform.afterInit = function () {
        smartform.getInstance().companyControl.addValidationCallback(validationCallback);
    }
    
    function validationCallback(validationResult) {
        if (response.result.type === smartform.CompanyValidationResultType.HIT) {
            // podle vstupních dat byla nalezena jedna validní firma
            alert("HIT: " + response.result.companyArray[0]);
        }
    }

Příklad praktického použití najdete v ukázce a podrobnější informace jsou v dokumentaci API.