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

widget/listonic-button.js

Podstawowa implementacja

<!-- Produkty do dodania – linki HTML obsługiwane -->
<div class="listonic-button"
     data-items="produkt <a href='http://example.com'>jeden</a>, produkt dwa"
     data-name="Moja lista zakupów">
</div>
<script src="widget/listonic-button.js" defer></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

widget/listonic-auto.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>
  var listonic_auto = {
    entryClass: "recipe__wrapper__list",
    hideSideBar: true
  };
</script>
<script src="widget/listonic-auto.js" defer></script>

Jak działa automatyczne wyodrębnianie

Widget skanuje element HTML określony przez właściwość 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 wielu elementów <div class="listonic-button">. Skrypt wystarczy dołączyć tylko raz.

<!-- Pierwszy przycisk -->
<div class="listonic-button"
     data-items="Mleko, Jajka"
     data-name="Śniadanie">
</div>

<!-- Drugi przycisk -->
<div class="listonic-button"
     data-items="Kurczak, Ryż, Warzywa"
     data-name="Obiad">
</div>

<!-- Dołącz skrypt raz -->
<script src="widget/listonic-button.js" defer></script>

Parametry przycisku niestandardowego#

Parametry przycisku automatycznego#

Przycisk automatyczny jest konfigurowany za pomocą obiektu listonic_auto. Ustaw jego właściwości przed załadowaniem skryptu.

Stylizacja przycisku#

Dostosuj wygląd przycisku Listonic za pomocą atrybutu data-style. Przekaż obiekt JSON z właściwościami stylizacji, które chcesz nadpisać.

Niestandardowa stylizacja#

Użyj atrybutu data-style na dowolnym elemencie przycisku, aby zastosować niestandardowe style:

<div class="listonic-button"
     data-items="Mleko, Jajka, Chleb"
     data-name="Moja lista"
     data-style='{
       "primaryColor": "#FF6B35",
       "iconColor": "#ffffff",
       "textColor": "#ffffff",
       "borderRadius": "50px",
       "fontFamily": "Roboto, sans-serif",
       "fontSize": "16px",
       "fontWeight": "600",
       "buttonText": "Dodaj do listy zakupów",
       "iconStyle": "shopping-cart"
     }'>
</div>
<script src="widget/listonic-button.js" defer></script>

Dostępne właściwości stylizacji

Treść dynamiczna (AJAX/SPA)#

Jeśli wstawiasz treść dynamicznie (na przykład przez AJAX lub framework frontendowy), możesz tworzyć i inicjalizować przyciski Listonic programowo za pomocą API ListonicButton.initButton.

// Po załadowaniu treści przez AJAX
function addListonicButton(items, listName, containerId, style) {
  const container = document.getElementById(containerId);

  // Utwórz element przycisku z atrybutami data
  const el = document.createElement('div');
  el.className = 'listonic-button';
  el.dataset.items = items.join(', ');
  el.dataset.name = listName;
  if (style) {
    el.dataset.style = JSON.stringify(style);
  }
  container.appendChild(el);

  // Zainicjalizuj przycisk przez publiczne API
  if (window.ListonicButton) {
    window.ListonicButton.initButton(el);
  }
}

Integracja z frameworkami#

Poniższe przykłady pokazują, jak zintegrować przyciski Listonic z popularnymi frameworkami JavaScript. Te komponenty używają atrybutów v2 data-* i API ListonicButton.initButton.

React

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

const ListonicButton = ({ items, name, style }) => {
  const ref = useRef(null);

  useEffect(() => {
    if (ref.current && window.ListonicButton) {
      window.ListonicButton.initButton(ref.current);
    }
  }, [items, name]);

  return (
    <div
      ref={ref}
      className="listonic-button"
      data-items={items}
      data-name={name}
      data-style={style ? JSON.stringify(style) : undefined}
    />
  );
};

export default ListonicButton;

Vue.js

<template>
  <div ref="buttonEl"
       class="listonic-button"
       :data-items="items"
       :data-name="name"
       :data-style="styleJson"></div>
</template>

<script>
export default {
  props: {
    items: { type: String, required: true },
    name: { type: String, default: 'Lista zakupów' },
    style: { type: Object, default: null }
  },
  computed: {
    styleJson() {
      return this.style ? JSON.stringify(this.style) : undefined;
    }
  },
  mounted() {
    if (window.ListonicButton) {
      window.ListonicButton.initButton(this.$refs.buttonEl);
    }
  }
}
</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 kontenera ma klasę listonic-button
• Zweryfikuj, że nie ma błędów JavaScript w konsoli
• Upewnij się, że data-items jest ustawiony na elemencie przed załadowaniem skryptu

Produkty nie są dodawane

• Sprawdź, czy produkty są oddzielone przecinkami w atrybucie data-items
• Upewnij się, że treść nie zawiera nieprawidłowego HTML
• Dla przycisku automatycznego zweryfikuj, że entryClass w listonic_auto pasuje do Twojego HTML

Wiele przycisków powoduje konflikty

• Użyj oddzielnych elementów <div class="listonic-button"> dla każdego przycisku
• Dołącz skrypt tylko raz na stronie

Kompatybilność przeglądarek

Widget Listonic obsługuje wszystkie nowoczesne przeglądarki:

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

Widget używa standardowej funkcjonalności JavaScript 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ź element przycisku, aby upewnić się, że ma poprawne atrybuty data-*
3. Zweryfikuj, czy publiczne API jest dostępne: wpisz window.ListonicButton 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 tag skryptu z atrybutem defer, aby nie blokował początkowego renderowania strony
• Dla stron z wieloma przyciskami używaj oddzielnych elementów <div class="listonic-button"> — skrypt obsłuży je wszystkie
• Ł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ść

• Przycisk jest renderowany jako natywny element HTML, dostępny 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), użyj ListonicButton.initButton(el), aby zainicjalizować nowe elementy przycisków po dodaniu ich do DOM
• Używając wielu przycisków, każdy element <div class="listonic-button"> jest niezależny — nie wymaga specjalnej konfiguracji
• 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żyj oddzielnych elementów <div class="listonic-button"> — skrypt automatycznie zainicjalizuje je wszystkie.

Pytania dotyczące dostosowania

Czy mogę dostosować wygląd przycisku?

Tak, możesz dostosować kolory i inne style za pomocą atrybutu data-style. Zobacz sekcję Stylizacja dla wszystkich dostępnych właściwości. Możesz także użyć Generatora widgetu jako edytora wizualnego.

Czy mogę zmienić tekst przycisku?

Tak, użyj właściwości buttonText w atrybucie data-style, aby ustawić dowolną etykietę, na przykład: data-style='{"buttonText":"Dodaj do listy zakupów"}'.

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. Skrypt używa atrybutu defer, więc ładuje się bez blokowania 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#