JavaScript biblioteka

Biblioteka skirta el. parduotuvėms ir svetainėms, kuriose klientas įveda pristatymo adresą. Ji naudoja PostAPI.lt pašto kodų API ir veikia su Lietuvos, Latvijos ir Estijos adresais.

• • Paieška rašant arba paieška mygtuku („Rasti pašto kodą“).
• • Užpildo pašto kodo, miesto, gatvės, namo numerio, korpuso, buto ir savivaldybės laukus.
• • Atpažįsta adresus be lietuviškų raidžių, su rašybos klaidomis, su butu (Laisvės pr. 44-78).
• • Veikia su klaviatūra ir ekrano skaitytuvais.

Įkelkite biblioteką puslapyje, kuriame yra adreso forma (pvz. prieš uždarantį </body>):

<script src="https://api.postapi.lt/js/postapi.min.js"></script>

Failą galima atsisiųsti ir laikyti savo svetainės statinių failų kataloge – tada pakeiskite src kelią.

Prie adreso lauko prijunkite biblioteką ir nurodykite, kuriuos laukus užpildyti pasirinkus adresą:

<input id="address" placeholder="Adresas">
<input id="postcode" placeholder="Pašto kodas">
<input id="city" placeholder="Miestas">

<script src="https://api.postapi.lt/js/postapi.min.js"></script>
<script>
  PostAPI.attach("#address", {
    key: "JŪSŲ_API_RAKTAS",
    fields: { postcode: "#postcode", city: "#city" }
  });
</script>

Pasiūlymai rodomi rašant, pasirinkti galima pele arba klaviatūra (↑ ↓ ir Enter). Pasirinkus adresą užpildomi nurodyti laukai ir kviečiama onSelect funkcija.

PostAPI.attach("#address", {
  key: "JŪSŲ_API_RAKTAS",
  fields: {
    postcode: "#postcode",
    city: "#city",
    apartment: "#flat"
  },
  onSelect: function (item) {
    console.log(item.postcode_full, item.city);
  }
});

Kai pasiūlymų rašant nereikia: vartotojas įveda visą adresą ir paspaudžia mygtuką. Jei randamas vienas adresas – laukai užpildomi iškart, jei keli – rodomas sąrašas, jei nė vieno – pranešimas.

<input id="address" placeholder="Adresas">
<button id="find" type="button">Rasti pašto kodą</button>
<input id="postcode">

<script>
  PostAPI.lookup("#address", {
    key: "JŪSŲ_API_RAKTAS",
    trigger: "#find",
    fields: { postcode: "#postcode" }
  });
</script>

Jei formoje yra keli adreso blokai (pvz. pristatymo ir sąskaitos), prijunkite biblioteką prie kiekvieno adreso lauko atskirai. Kiekvienas veikia savarankiškai ir užpildo tik savo bloko laukus.

PostAPI.attach("#shipping_address", {
  key: "JŪSŲ_API_RAKTAS",
  fields: { postcode: "#shipping_postcode", city: "#shipping_city" }
});

PostAPI.attach("#invoice_address", {
  key: "JŪSŲ_API_RAKTAS",
  fields: { postcode: "#invoice_postcode", city: "#invoice_city" }
});

Parinktyje fields nurodykite lauko selektorių kiekvienai reikšmei. Užpildžius siunčiami input ir change įvykiai, todėl pakeitimą pastebi ir PrestaShop, WooCommerce, React ar Vue formos.

PostAPI.attach("#street", {
  key: "JŪSŲ_API_RAKTAS",
  sources: ["#house", "#city"],
  fields: { postcode: "#postcode" }
});

fields: {
  postcode: {
    target: "#zip",
    transform: function (value) { return value.replace("LT-", ""); }
  },
  city: function (value, item) { myCart.city = value; }
}

API raktas, įrašytas puslapyje, matomas jo kode. Saugiau naudoti laikiną token'ą: jūsų serveris jį sukuria ir perduoda bibliotekai, o pats raktas lieka serveryje. Token'as galioja 180 min., biblioteka jį atnaujina automatiškai.

PostAPI.attach("#address", {
  tokenUrl: "/postapi-token.php",
  fields: { postcode: "#postcode" }
});

openssl_public_encrypt(POSTAPI_KEY . ";" . time(), $encrypted, POSTAPI_PUBLIC_KEY, OPENSSL_PKCS1_OAEP_PADDING);

header("Content-Type: application/json");
echo json_encode(["token" => base64_encode($encrypted)]);

Naudojant nemokamą API raktą, svetainėje privaloma nuoroda į PostAPI.lt. Biblioteka ją rodo automatiškai – po adreso lauku, todėl papildomai nieko daryti nereikia:

Nuorodos tekstas – tos šalies kalba, kurios adresų ieškoma (parinktis country): Latvijoje „Pasta indeksu integrācija“, Estijoje „Postiindeksite integratsioon“. Pakeitus šalį (setCountry), tekstas atnaujinamas iškart.

Mokamame plane nuoroda nerodoma. Jei laukas formoje yra vienoje eilutėje su kitais, nuorodos vietą galima pakeisti parinktimi attributionTarget.

Pasiūlymų sąrašo spalvas ir šriftą pritaikykite savo svetainei CSS kintamaisiais:

.postapi-ac {
  --postapi-active: #fff3e0;     /* pažymėtas pasiūlymas */
  --postapi-border: #e0e0e0;
  --postapi-radius: 4px;
  --postapi-font: 15px/1.4 Arial, sans-serif;
}

• • Naršyklės: visos šiuolaikinės, taip pat Internet Explorer 11, iOS Safari 9+, Android 4.4+ – be papildomų bibliotekų.
• • Be priklausomybių: nereikia jQuery ar kitų bibliotekų, dydis – 9 KB (gzip).
• • Be konfliktų: vienas globalus vardas PostAPI, visi stiliai su priešdėliu postapi-ac – jūsų svetainės išvaizdos biblioteka nekeičia, o svetainės stiliai nesugadina pasiūlymų sąrašo.
• • Prieinamumas: valdymas klaviatūra, ARIA atributai, rezultatų skaičius pranešamas ekrano skaitytuvams.