Poštové adresy

Účelom rozšírenia je rýchle vkladanie adries bez nutnosti vyplňovania všetkých adresných polí formulára na webovej stránke alebo v mobilnej aplikácii.

Vyhľadávacia stratégia

Výsledky vyhľadávania prispôsobujeme podľa zadanej adresy vo formulári. Keď začnete vypĺňaním krajiny alebo obce, zobrazíme adresy týkajúce sa tohto miesta.

Podporované prehliadače

IE / EdgeFirefoxChromeSafariiOS SafariSamsungOperaOpera MiniElectron

Inštalácia

Ponúkame viacero spôsobov ako môžete integrovať službu Swiftyper Places WebAPI do Vašej aplikácie.

CDN <script>

JavaScriptová knižnica je dostupná na platforme jsDelivr CDN.

<script src="https://cdn.jsdelivr.net/npm/swiftyper.js@1.0.6"></script>

<form>
    <div>
        <input type="text" id="ulica" placeholder="Ulica, číslo" />
    </div>
    <div>
        <input type="text" id="psc" placeholder="PSČ" />
    </div>
    <div>
        <input type="text" id="mesto" placeholder="Mesto" />
    </div>
    <div>
        <input type="text" id="krajina" placeholder="Krajina" />
    <div>
</form>

<script>
  var placesAutocomplete = new swiftyper.places({
      selectors: {
          street: document.querySelector('#ulica'),
          municipality: document.querySelector('#mesto'),
          postalCode: document.querySelector('#psc'),
          country: document.querySelector('#krajina'),
      },
      apiKey: '2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y',
  });
</script>

npm

Nájdete nás aj na npm.

Na inštaláciu stačí zadať príkaz:

npm install swiftyper.js --save

Príklad použitia v HTML:

<form>
    <div>
        <input type="text" id="ulica" placeholder="Ulica, číslo" />
    </div>
    <div>
        <input type="text" id="psc" placeholder="PSČ" />
    </div>
    <div>
        <input type="text" id="mesto" placeholder="Mesto" />
    </div>
    <div>
        <input type="text" id="country" placeholder="Krajina" />
    <div>
</form>

Príklad použitia v JavaScripte:

const { places } = require('swiftyper.js')

const placesAutocomplete = new places({
  selectors: {
    street: document.querySelector('#ulica'),
    municipality: document.querySelector('#mesto'),
    postalCode: document.querySelector('#psc'),
    country: document.querySelector('#krajina'),
  },
  apiKey: '2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y',
})

Nastavenia

Popis nastavení ktoré môžete použiť v metóde places({ nastavenia }).

Popis nastavení

  • Name
    apiKey
    Type
    string
    Description

    Prístupový API kľúč.

  • Name
    selectors.address
    Type
    DOM Element
    Description

    Element obsahujúci adresu.

  • Name
    selectors.street
    Type
    DOM Element
    Description

    Element obsahujúci ulicu a číslo.

  • Name
    selectors.streetName
    Type
    DOM Element
    Description

    Element obsahujúci iba názov ulice.

  • Name
    selectors.streetNumber
    Type
    DOM Element
    Description

    Element obsahujúci iba číslo ulice.

  • Name
    selectors.municipality
    Type
    DOM Element
    Description

    Element obsahujúci obec.

  • Name
    selectors.postalCode
    Type
    DOM Element
    Description

    Element obsahujúci PSČ.

  • Name
    selectors.country
    Type
    DOM Element
    Description

    Element obsahujúci krajinu.

  • Name
    suggestions
    Type
    string[]
    Description

    Zoznam polí pre ktoré sa budú zobrazovať návrhy vyhľadávania, hodnoty môžu byť address, street, streetName, municipality a postalCode.

  • Name
    endpoint
    Type
    string
    Description

    Adresa na ktorú je požiadavka smerovaná.

  • Name
    nextFocus
    Type
    bool, DOM Element
    Description

    Nastavenie focus na ďalšie pole formulára po výbere adresy.

  • Name
    highlight
    Type
    bool
    Description

    Nastavenie zobrazenia zvýraznenia zhodnej časti s dopytom vyhľadávania.

  • Name
    showNoResults
    Type
    bool
    Description

    Zobrazenie upozornenia v prípade nenájdených výsledkov.

  • Name
    events
    Type
    string[]
    Description

    Typy udalostí na ktoré bude reagovať vyhľadávanie.

  • Name
    limit
    Type
    integer
    Description

    Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

  • Name
    minlength
    Type
    integer
    Description

    Minimálna dĺžka výrazu na začatie vyhľadávania.

  • Name
    debounce
    Type
    integer
    Description

    Minimálna pauza pred začatím vyhľadávania cez API, počas zadávania výrazu sa časovač vynuluje. Predvolená hodnota je 250 (ms).

  • Name
    theme
    Type
    string
    Description

    Téma rozšírenia, môže byť modern-light (predvolené), modern-dark alebo classic.

  • Name
    htmlAutocomplete
    Type
    bool
    Description

    Nastavenie HTML atribútu autocomplete, predvolene pole nastavujeme na autocomplete=off

  • Name
    context
    Type
    string[]
    Description

    Nastavenie oblastí pre vyhľadávanie (kľúč place_id). Výsledky vyhľadávania môžete odfiltrovať pre konkrétny kraj, okres alebo obec.

  • Name
    contextType
    Type
    string
    Description

    Nastavenie typu vyhľadávacieho kontextu. Použite strict ak chcete vyhľadávať adresu s ďalšími zadanými poliami (napr. mesto, psč) alebo preference pokiaľ chete adresy zo zadaného miesta uprednostniť.

  • Name
    aroundLatLng
    Type
    string
    Description

    Prispôsobenie výsledkov vyhľadávania zadanej lokalite vo formáte latitude,longitude napr. 49.1992988,18.8211994.

  • Name
    aroundLatLngViaIP
    Type
    string
    Description

    Prispôsobenie výsledkov vyhľadávania aktuálnej lokalite používateľa, predvolená hodnota je "true".

  • Name
    itemTemplate
    Type
    function
    Description

    Funkcia na formátovanie položky vyhľadávania.

Udalosti

Rozšírenie používa určité udalosti, ktoré si môžete prispôsobiť.

Popis udalostí

  • Name
    change
    Type
    Description

    Zavolá sa, keď sa zvolí adresa zo zoznamu vyhľadaných adries.

  • Name
    suggestions
    Type
    string
    Description

    Zavolá sa, keď sa načíta zoznam vyhľadaných adries. Táto udalosť sa zavolá aj v prípade, že sa nenájdu žiadne výsledky.

  • Name
    limit
    Type
    Description

    Zavolá sa, keď bude presiahnutý mesačný limit.

  • Name
    error
    Type
    Description

    Zavolá sa, keď sa vyskytne problém s vyhľadaním adresy alebo ak bude presiahnutý mesačný limit.

Metódy

Popis metód ktoré môžete použiť po inicializácii metódy places().

Popis metód

  • Name
    configure
    Type
    Description
    Zmena nastavení rozšírenia.
  • Name
    on
    Type
    Description
    Nastavenie udalostí.
  • Name
    destroy
    Type
    Description
    Zrušenie funkcií rozšírenia.

Štýlovanie

Rozšírenie používa niekoľko základných CSS tried a tágov ktoré si môžete pre vašu aplikáciu prispôsobiť.

CSS triedy a tágy

  • Name
    swiftyper_wrapper
    Type
    Description

    .swiftyper_wrapper je rodičovskou triedou vyhľadávacieho poľa

  • Name
    swiftyper_list
    Type
    Description

    Trieda .swiftyper_list obsahuje zoznam návrhov vyhľadávania

  • Name
    swiftyper_result
    Type
    Description

    Trieda .swiftyper_result obsahuje každý jeden návrh vyhľadávania

  • Name
    <em>
    Type
    Description

    Tág <em> v zozname výsledkov sa používa na zvýraznenie zhodných častí s dopytom vyhľadávania

Príklady použitia

Poštovú adresu je možné zadať niekoľkými spôsobmi, v týchto príkladoch použitia uvádzame tie najpoužívanejšie.

Formulár hľadajúci iba slovenské adresy

<form>
    <div>
        <input type="text" class="ulica" placeholder="Ulica, číslo"/>
    </div>
    <div>
        <input type="text" class="psc" placeholder="PSČ"/>
    </div>
    <div>
        <input type="text" class="mesto" placeholder="Mesto"/>
    </div>
    <div>
        <input type="text" class="krajina" placeholder="Krajina"/>
    </div>
</form>

Formulár s možnosťou výberu krajiny

<form>
    <select class="krajina">
        <option value="SK">Slovenská republika</option>
        <option value="CZ">Česká republika</option>
        <option value="PL">Poľská republika</option>
        <option value="AT">Rakúsko</option>
        <option value="CH">Švajčiarsko</option>
    </select>
    <div>
        <input type="text" class="ulica" placeholder="Ulica, číslo"/>
    </div>
    <div>
        <input type="text" class="psc" placeholder="PSČ"/>
    </div>
    <div>
        <input type="text" class="mesto" placeholder="Mesto"/>
    </div>
</form>

Formulár s oddelenou ulicou a číslom

<form>
    <div>
        <input type="text" class="ulica" placeholder="Ulica">
    </div>
    <div>
        <input type="text" class="cislo" placeholder="Číslo">
    </div>
    <div>
        <input type="text" class="psc" placeholder="PSČ">
    </div>
    <div>
        <input type="text" class="mesto" placeholder="Mesto">
    </div>
    <div>
        <input type="text" class="krajina" placeholder="Krajina">
    </div>
</form>

Formulár s adresou v jednom poli

<form>
    <div>
        <input type="text" class="adresa" placeholder="Adresa"/>
    </div>
</form>

Vyhľadávanie adries iba z konkrétnej obce

Výsledky vyhľadávania sú obmedzené na mesto Žilina. Skúste vyhľadať napríklad ulice: Národná, Lichardova alebo Jedlíková.

<form>
    <div>
        <input type="text" class="ulica" placeholder="Ulica, číslo"/>
    </div>
    <div>
        <input type="text" class="psc" placeholder="PSČ"/>
    </div>
    <div>
        <input type="text" class="mesto" placeholder="Mesto"/>
    </div>
    <div>
        <input type="text" class="krajina" placeholder="Krajina"/>
    </div>
</form>