Dokumentacja dla deweloperów

Przegląd i korzyści#

Integracja Dodaj do listy została zaprojektowana tak, aby była lekka i łatwa do osadzenia. Możesz ją używać na dwa główne sposoby, w zależności od Twojego przypadku użycia:

• Przycisk niestandardowy – Idealny dla predefiniowanych list produktów. Masz pełną kontrolę nad tym, które produkty są dodawane.
• Przycisk automatyczny – Automatycznie wyodrębnia produkty ze struktury HTML. Idealny dla blogów kulinarnych i uporządkowanej treści.

Obie metody używają prostego fragmentu kodu JavaScript i hostowanych skryptów dostarczonych przez Listonic. Możesz zacząć od Przycisku niestandardowego dla maksymalnej kontroli lub Przycisku automatycznego, aby automatycznie konwertować istniejące listy składników na przyciski Dodaj do listy.

Przycisk niestandardowy Dodaj do listy#

Przycisk niestandardowy daje Ci pełną kontrolę nad tym, które produkty są dodawane do listy zakupów użytkownika. Definiujesz produkty bezpośrednio w JavaScript, a przycisk uruchamia ich dodanie do Listonic.

Kiedy używać

• Masz predefiniowaną listę produktów (np. zestawy produktów, zestawy posiłków)
• Chcesz mieć pełną kontrolę nad listą produktów
• Twoje produkty są generowane dynamicznie przez JavaScript
• Budujesz integrację e-commerce

URL skryptu

https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js

Podstawowa implementacja

<script type="text/javascript">
  // Produkty do dodania – HTML obsługiwany
  listonic_content = 'produkt <a href="http://example.com">jeden</a><br/>produkt dwa<br/>';

  // Opcjonalnie: alternatywny tekst przycisku ("Dodaj do listy zakupów")
  listonic_alternateText = 'true';

  // Opcjonalnie: domyślna nazwa listy
  listonic_name = 'Moja lista zakupów';

  // Wymagany kontener dla przycisku
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

Przycisk automatyczny#

Przycisk automatyczny został zaprojektowany dla uporządkowanej treści takiej jak przepisy i blogi kulinarne. Automatycznie odczytuje składniki z Twojego HTML i udostępnia funkcjonalność Dodaj do listy bez konieczności ręcznego definiowania produktów w JavaScript.

Kiedy używać

• Masz strony z przepisami ze składnikami w HTML
• Chcesz automatycznego wyodrębniania bez ręcznej konfiguracji
• Twoja treść ma spójną strukturę HTML
• Prowadzisz bloga kulinarnego lub stronę z przepisami

URL skryptu

https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/blogwidget.js

Podstawowa implementacja

<!-- Lista składników na stronie -->
<div class="recipe__wrapper__list">
  <ul>
    <li>1 cebula</li>
    <li>2 pomidory</li>
    <li>Oliwa z oliwek</li>
  </ul>
</div>

<script type="text/javascript">
  // Tryb widgetu
  var listonic_bw_type = "generic";

  // Klasa lub ID elementu HTML zawierającego składniki
  var listonic_bw_generic_entryClass = "recipe__wrapper__list";

  // Opcjonalnie: ukryj pasek boczny i użyj bardziej zwartego trybu
  var listonic_hideSideBar = true;
</script>
<script src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/blogwidget.js"
        charset="UTF-8"></script>

Jak działa automatyczne wyodrębnianie

Widget skanuje element HTML określony przez listonic_bw_generic_entryClass i wyodrębnia zawartość tekstową z elementów listy (<li>) lub innych węzłów tekstowych. Każdy element staje się pozycją na liście zakupów.

Wiele przycisków na jednej stronie#

Jeśli potrzebujesz wielu przycisków Dodaj do listy na tej samej stronie, użyj indeksowanych nazw zmiennych. Każdy przycisk używa własnej treści i nazwy listy.

<script type="text/javascript">
  // Pierwszy przycisk
  listonic_content_0 = 'Mleko<br/>Jajka<br/>';
  listonic_name_0 = 'Śniadanie';
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no' id='listonic_ifrm_0'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

<!-- Drugi przycisk -->
<script type="text/javascript">
  listonic_content_1 = 'Kurczak<br/>Ryż<br/>Warzywa';
  listonic_name_1 = 'Obiad';
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no' id='listonic_ifrm_1'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

Parametry przycisku niestandardowego#

Parametry przycisku automatycznego#

Stylizacja przycisku#

Domyślnie przycisk Listonic używa standardowej stylizacji. Jeśli chcesz lepiej dopasować go do wyglądu swojej strony, możesz nadpisać wybrane kolory wewnątrz osadzonego iframe.

Własne kolory#

Poniższy fragment kodu aktualizuje wszystkie iframe przycisków Listonic na stronie o niestandardowe kolory:

<script type="text/javascript">
  setTimeout(function () {
    var iconColor = '#54AB26';       // Kolor wypełnienia ikony
    var iconBackground = '#eeeeee'; // Tło ikony
    var textBackground = '#eeeeee'; // Tło przycisku
    var textColor = '#747474';       // Kolor tekstu

    var frames = document.getElementsByClassName("listonic_ifrm_used");
    for (var i = 0; i < frames.length; i++) {
      var cssStyle = document.createElement("style");
      var css =
        '.listonic-button { background-color: ' + textBackground + ';}' +
        '.listonic-button-icon svg {fill: ' + iconColor + ';}' +
        '.listonic-button-icon { background-color: ' + iconBackground + ';}' +
        '.listonic-button-text svg {fill: ' + textColor + ';}';
      cssStyle.type = 'text/css';
      cssStyle.appendChild(document.createTextNode(css));
      frames[i].contentDocument.head.appendChild(cssStyle);
    }
  }, 0);
</script>

Dostępne klasy CSS

Treść dynamiczna (AJAX/SPA)#

Jeśli wstawiasz treść dynamicznie (na przykład przez AJAX lub framework frontendowy), upewnij się, że skrypty Listonic uruchamiają się po pojawieniu się treści w DOM.

// Śledź ładowanie skryptu i instancje przycisków
var listonicScriptLoaded = false;
var listonicButtonIndex = 0;

// Po załadowaniu treści przez AJAX
function initListonicButton(items, listName, containerId) {
  var container = document.getElementById(containerId);
  var buttonId = listonicButtonIndex++;

  // Użyj indeksowanych zmiennych, aby obsługiwać wiele przycisków
  window['listonic_content_' + buttonId] = items.join('<br/>');
  window['listonic_name_' + buttonId] = listName;

  // Utwórz iframe z unikalnym ID
  var iframe = document.createElement('iframe');
  iframe.className = 'listonic_ifrm';
  iframe.id = 'listonic_ifrm_' + buttonId;
  iframe.frameBorder = '0';
  iframe.scrolling = 'no';
  container.appendChild(iframe);

  // Załaduj skrypt tylko raz
  if (!listonicScriptLoaded) {
    var script = document.createElement('script');
    script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
    script.onload = function() { listonicScriptLoaded = true; };
    document.body.appendChild(script);
  }
}

Integracja z frameworkami#

Poniższe przykłady pokazują, jak zintegrować przyciski Listonic z popularnymi frameworkami JavaScript. Te komponenty obsługują odpowiednie czyszczenie i unikają typowych pułapek takich jak wycieki pamięci.

React

import React, { useEffect, useRef } from 'react';

// Śledź ładowanie skryptu (współdzielone między wszystkimi instancjami)
let scriptLoaded = false;

const ListonicButton = ({ items, listName }) => {
  const containerRef = useRef(null);
  const iframeRef = useRef(null);
  const idRef = useRef('listonic_' + Date.now());

  useEffect(() => {
    const id = idRef.current;
    const container = containerRef.current;
    if (!container) return;

    // Wyczyść poprzednią zawartość
    container.innerHTML = '';

    // Użyj indeksowanych zmiennych dla unikalnej identyfikacji
    window['listonic_content_' + id] = items.join('<br/>');
    window['listonic_name_' + id] = listName;

    // Utwórz iframe z unikalnym ID
    const iframe = document.createElement('iframe');
    iframe.className = 'listonic_ifrm';
    iframe.id = 'listonic_ifrm_' + id;
    iframe.frameBorder = '0';
    iframe.scrolling = 'no';
    container.appendChild(iframe);
    iframeRef.current = iframe;

    // Załaduj skrypt tylko raz
    if (!scriptLoaded) {
      const script = document.createElement('script');
      script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
      script.onload = () => { scriptLoaded = true; };
      document.body.appendChild(script);
    }

    // Czyszczenie przy odmontowaniu lub zmianie właściwości
    return () => {
      if (iframeRef.current && iframeRef.current.parentNode) {
        iframeRef.current.parentNode.removeChild(iframeRef.current);
      }
      delete window['listonic_content_' + id];
      delete window['listonic_name_' + id];
    };
  }, [items, listName]);

  return <div ref={containerRef} />;
};

export default ListonicButton;

Vue.js

<template>
  <div ref="container"></div>
</template>

<script>
// Śledź ładowanie skryptu (współdzielone między wszystkimi instancjami)
let scriptLoaded = false;

export default {
  props: {
    items: { type: Array, required: true },
    listName: { type: String, default: 'Lista zakupów' }
  },
  data() {
    return {
      instanceId: 'listonic_' + Date.now(),
      iframe: null
    };
  },
  mounted() {
    this.initButton();
  },
  beforeUnmount() {
    this.cleanup();
  },
  methods: {
    initButton() {
      const id = this.instanceId;

      // Użyj indeksowanych zmiennych dla unikalnej identyfikacji
      window['listonic_content_' + id] = this.items.join('<br/>');
      window['listonic_name_' + id] = this.listName;

      // Utwórz iframe z unikalnym ID
      this.iframe = document.createElement('iframe');
      this.iframe.className = 'listonic_ifrm';
      this.iframe.id = 'listonic_ifrm_' + id;
      this.iframe.frameBorder = '0';
      this.iframe.scrolling = 'no';
      this.$refs.container.appendChild(this.iframe);

      // Załaduj skrypt tylko raz
      if (!scriptLoaded) {
        const script = document.createElement('script');
        script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
        script.onload = () => { scriptLoaded = true; };
        document.body.appendChild(script);
      }
    },
    cleanup() {
      if (this.iframe && this.iframe.parentNode) {
        this.iframe.parentNode.removeChild(this.iframe);
      }
      delete window['listonic_content_' + this.instanceId];
      delete window['listonic_name_' + this.instanceId];
    }
  }
}
</script>

Przewodniki platformowe#

WordPress

1. W edytorze Gutenberg dodaj blok "Własny HTML" tam, gdzie chcesz umieścić przycisk
2. Wklej kompletny kod przycisku Listonic do bloku
3. Dla skryptu użyj wtyczki takiej jak "Insert Headers and Footers", aby dodać go na całej stronie, lub dołącz go w bloku Własny HTML

Shopify

1. Przejdź do Sklep online → Motywy → Edytuj kod
2. Dodaj HTML przycisku do szablonu produktu (product-template.liquid)
3. Dodaj skrypt Listonic do theme.liquid przed </body>

Wix

1. Dodaj element "Embed" lub "HTML iframe" do swojej strony
2. Wklej kompletny kod przycisku włącznie ze skryptem
3. Dostosuj rozmiar elementu, aby pasował do przycisku

Squarespace

1. Dodaj blok "Kod" do swojej strony
2. Wklej kompletny kod przycisku Listonic
3. Zapisz i podejrzyj stronę

Rozwiązywanie problemów#

Typowe problemy

Przycisk się nie pojawia

• Upewnij się, że URL skryptu jest poprawny i dostępny
• Sprawdź, czy element iframe ma klasę listonic_ifrm
• Zweryfikuj, że nie ma błędów JavaScript w konsoli
• Upewnij się, że listonic_content jest zdefiniowany przed załadowaniem skryptu

Produkty nie są dodawane

• Sprawdź, czy produkty są rozdzielone tagami <br/>
• Upewnij się, że treść nie zawiera nieprawidłowego HTML
• Dla widgetu bloga zweryfikuj, że listonic_bw_generic_entryClass pasuje do Twojego HTML

Wiele przycisków powoduje konflikty

• Używaj indeksowanych zmiennych (_0, _1 itp.)
• Upewnij się, że każdy iframe ma unikalne ID

Kompatybilność przeglądarek

Widget Listonic obsługuje wszystkie nowoczesne przeglądarki:

• Chrome (desktop i mobile)
• Firefox
• Safari (desktop i iOS)
• Edge

Widget używa standardowego JavaScript i funkcjonalności iframe obsługiwanej przez wszystkie nowoczesne przeglądarki.

Wskazówki debugowania

1. Otwórz narzędzia deweloperskie przeglądarki (F12) i sprawdź konsolę pod kątem błędów
2. Sprawdź iframe, aby upewnić się, że załadował się poprawnie
3. Zweryfikuj zmienne globalne: wpisz listonic_content w konsoli
4. Sprawdź zakładkę Network, aby upewnić się, że skrypt się załadował (status 200)

Dobre praktyki#

Wydajność i umiejscowienie skryptów

• Umieszczaj skrypty blisko końca dokumentu (przed </body>), aby nie blokowały początkowego renderowania strony
• Dla stron z wieloma przyciskami używaj indeksowanych zmiennych, aby uniknąć konfliktów
• Ładuj skrypt Listonic tylko raz na stronę, nawet przy używaniu wielu przycisków

Wytyczne dotyczące struktury HTML

• Utrzymuj listy składników w czystych, semantycznych strukturach HTML (na przykład listy nieuporządkowane z elementami listy), aby widget mógł je niezawodnie parsować
• Używaj spójnych nazw klas na wszystkich stronach z przepisami
• Unikaj zagnieżdżania elementów interaktywnych wewnątrz elementów listy

Dostępność

• Zawartość iframe jest dostępna dla czytników ekranu
• Zapewnij wystarczający kontrast kolorów przy dostosowywaniu kolorów
• Przycisk jest domyślnie nawigowalny za pomocą klawiatury

Treść dynamiczna

• Jeśli wstawiasz treść dynamicznie (przez AJAX lub framework frontendowy), upewnij się, że skrypty Listonic uruchamiają się po pojawieniu się treści w DOM
• Używając wielu widgetów lub przycisków, upewnij się, że każdy kontener treści ma unikalną klasę lub identyfikator, aby uniknąć niejednoznaczności
• Testuj swoją integrację zarówno na urządzeniach desktopowych, jak i mobilnych, aby zapewnić płynne doświadczenie użytkownika

Dokumentacja API#

API przycisku niestandardowego

API przycisku automatycznego

URL skryptów

Najczęściej zadawane pytania#

Pytania dotyczące instalacji

Czy mogę używać widgetu na każdej stronie?

Tak! Widget działa na praktycznie każdej stronie internetowej lub aplikacji webowej, włącznie z WordPress, Shopify, niestandardowymi stronami HTML i nowoczesnymi frameworkami JavaScript. Dopóki możesz wstawić JavaScript na stronę, możesz używać przycisku Dodaj do listy Listonic.

Czy potrzebuję klucza API?

Nie, widget Listonic jest darmowy i nie wymaga żadnego klucza API ani rejestracji.

Czy jest limit liczby przycisków, które mogę dodać?

Nie, możesz dodać tyle przycisków, ile potrzebujesz. Po prostu używaj indeksowanych zmiennych dla wielu przycisków na tej samej stronie.

Pytania dotyczące dostosowania

Czy mogę dostosować wygląd przycisku?

Tak, możesz dostosować kolory używając skryptu stylizacji dostarczonego w sekcji Stylizacja. Dla bardziej zaawansowanego dostosowania rozważ użycie Generatora widgetu.

Czy mogę zmienić tekst przycisku?

Tak, ustaw listonic_alternateText = 'true', aby użyć "Dodaj do listy zakupów" jako tekst przycisku.

Pytania techniczne

Czy widget jest przyjazny dla urządzeń mobilnych?

Tak, widget jest w pełni responsywny i działa bezproblemowo na urządzeniach mobilnych. Łączy się bezpośrednio z aplikacją Listonic, która jest używana przez ponad 20 milionów użytkowników na całym świecie.

Czy widget wpływa na szybkość ładowania strony?

Widget jest lekki. Dla najlepszej wydajności umieść skrypt blisko końca dokumentu (przed </body>), aby nie blokował początkowego renderowania strony.

Co się dzieje, gdy użytkownik kliknie przycisk?

Przycisk otwiera interfejs Listonic, gdzie użytkownicy mogą dodać produkty do swojej listy zakupów. Jeśli mają aplikację Listonic, produkty synchronizują się automatycznie na wszystkich ich urządzeniach.

Przykłady działania#