Aller au contenu

#Le panier

Sur une boutique, le panier appartient au thème, comme chez Shopify. La plateforme fournit les données du panier, son API et la page de paiement ; le thème décide s’il y a un tiroir, une page /cart, les deux ou rien, comment ils se présentent, et quels réglages le marchand voit dans l’éditeur. Aucun réglage de panier n’est ajouté par la plateforme : ceux qui existent sont déclarés par le thème, dans le {% schema %} de ses sections.

La page de paiement (/checkout) reste un document de la plateforme : aucun gabarit, aucune feuille, aucun script du thème n’y entre.

#Ce que fournit la plateforme

cartobjet

Le panier, aux noms de Shopify : cart.items, cart.item_count, cart.total_price, cart.items_subtotal_price, cart.original_total_price, cart.total_discount, cart.cart_level_discount_applications, cart.note, cart.attributes, cart.currency.iso_code, cart.empty, cart.token. Les montants sont en centimes, à passer dans | money. Présent sur toute page d’une boutique. Ce que la visiteuse a écrit — cart.note, les valeurs de cart.attributes et des properties d’une ligne — arrive déjà échappé : à poser tel quel, sans | escape.

routesobjet

Les adresses, préfixées comme le site : routes.cart_url, routes.cart_add_url, routes.cart_change_url, routes.cart_update_url, routes.cart_clear_url, routes.root_url, routes.search_url, routes.collections_url, routes.all_products_collection_url, routes.account_url (vide sans comptes clients).

moneyfiltre

Des centimes en prix lisible, dans la devise du panier : {{ cart.total_price | money }} → 24,90 €.

boutique.en_pausebooléen

Vrai quand le site est en pause : les produits restent visibles, mais la boutique ne prend plus de commande. Absent sinon, donc {% if boutique.en_pause %} suffit. Le thème met alors « Boutique en pause » à la place de son bouton d’ajout au panier (et retire une barre d’achat collée, s’il en a une). Le reste est tenu par la plateforme : l’ajout (/cart/add) répond 422 avec la phrase à afficher (description), le composant du panier remplace son bouton de commande par « Boutique en pause », et le paiement est refusé.

liquid
{%- if boutique.en_pause -%}
  <button type="button" class="ajouter" disabled>Boutique en pause</button>
{%- else -%}
  <button type="submit" class="ajouter">Ajouter au panier</button>
{%- endif -%}

Une ligne de cart.items porte key, id (la variante, ou le produit quand il n’en a pas), quantity, title, product_title, variant_title, url, image, properties (la personnalisation : { "Prénom": "Léa" }), options_with_values, price, final_price, final_line_price, original_line_price, total_discount, et deux champs de plus que Shopify : offerte (un article ajouté par une offre de la boutique, qui ne se change pas) et stock_insuffisant.

Attention

Sur une page servie à toutes, cart est le panier vide. Les pages d’un site sont gardées en cache et servies telles quelles à chaque visiteuse : leur HTML ne peut pas dépendre de la sienne. cart est celui de la visiteuse sur /cart quand elle a un panier (la page est alors rendue pour elle), et dans les sections que l’API rend à la demande. Ailleurs, un compteur se remplit dans la page : [data-wc-panier-compte], l’évènement wcp:maj, ou /cart.js.

#Trois façons d’avoir un panier

#1. Le composant de la plateforme, réglé par le thème

C’est ce que font les thèmes de Webcosa. Une section de la coquille déclare les réglages du panier dans son schéma et en pose les valeurs dans la page ; le composant du panier de la plateforme les lit et dessine le tiroir et la page /cart aux couleurs du thème. Le nom de la section est libre ; celui des thèmes de Webcosa est cart-drawer.

sections/cart-drawer.liquidliquid
<script type="application/json" data-wc-panier>{{ section.settings | json }}</script>

{% schema %}
{
  "name": "Panier",
  "settings": [
    { "type": "select", "id": "forme", "label": "Forme du panier", "default": "tiroir",
      "options": [{ "value": "tiroir", "label": "Tiroir" }, { "value": "page", "label": "Page /cart" }] },
    { "type": "checkbox", "id": "ouvrir_a_l_ajout", "label": "Ouvrir le panier à chaque ajout", "default": true },
    { "type": "text", "id": "titre", "label": "Titre du panier", "default": "Votre panier" },
    { "type": "text", "id": "bouton", "label": "Bouton du panier", "default": "Paiement sécurisé" }
  ]
}
{% endschema %}
layout/theme.liquid (extrait)liquid
    {% section 'pied' %}
    {% section 'cart-drawer' %}
  </body>

Le composant comprend ces identifiants de réglage ; un thème n’en déclare que ceux qu’il veut, les autres gardent la valeur de la plateforme. Une valeur illisible (un choix inconnu, un texte trop long ou qui contient <) est ignorée.

IdentifiantTypeCe qu’il règle
formetiroir ou pageun tiroir sur le côté, ou la page /cart
ouvrir_a_l_ajoutbooléenle panier s’ouvre à chaque ajout
vignettesbooléenles photos des lignes
code_reductionbooléenla ligne « Ajouter un code de réduction »
livraison_estimeebooléenle port du mode le moins cher dans le total
livraison_offertebooléenla carte « Plus que 21 € pour la livraison offerte », lue dans les modes de livraison
cadenasbooléenun cadenas dans le bouton
logos_paiementbooléenles logos des moyens que la caisse propose vraiment
icone_sous_boutonaucune, retour, cadenas, camion, bouclierl’icône de la ligne sous le bouton
recommandationsbooléendes produits associés à ceux du panier
recommandations_sourceassocies, collection, les_deuxd’où ils viennent
recommandations_nombre1 à 6combien
titretexte (60)le titre du panier
texte_videtexte (160)le panier vide
boutontexte (40)le bouton qui mène au paiement
sous_boutontexte (160), facultatifune ligne sous le bouton
texte_livraison_restanttexte (120) avec {montant}la carte de livraison offerte, en chemin
texte_livraison_atteintetexte (120)la carte, seuil atteint
titre_recommandationstexte (60)le titre des recommandations

Le composant se règle aussi par CSS : il pose ses éléments sous .wcp, le bouton principal est .wcp-commander, les boutons secondaires .wcp-second. Le contenu d’un <template data-wc-panier-note> posé dans la page est recopié sous la carte de livraison offerte à chaque rendu (une ligne de saison).

La page /cart du thème pose l’emplacement que le composant remplit :

templates/cart.jsonjson
{
  "sections": { "panier": { "type": "main-cart", "settings": {} } },
  "order": ["panier"]
}
sections/main-cart.liquidliquid
<h1 class="masque">{{ page.titre | escape }}</h1>
<div id="wc-panier-page"></div>
{% schema %}{ "name": "Page du panier", "settings": [] }{% endschema %}

#2. Votre propre panier, sur l’API

Un thème importé de Shopify garde son tiroir et sa page : templates/cart.json et ses sections lisent cart, ses formulaires postent vers routes.cart_add_url, son script appelle l’API ci-dessous. Il ne pose pas data-wc-panier, et le composant de la plateforme ne dessine rien.

Les scripts en ligne d’une section sont admis ; assets/ n’accepte ni .js ni autre chose que du CSS et du SVG.

#3. Pas de panier

Un thème sans section qui pose data-wc-panier n’a pas de tiroir : les liens vers /cart y mènent, et l’ajout depuis une fiche aussi (la forme « page » de Shopify). Sans templates/cart.json, /cart montre le panier minimal de la plateforme dans la coquille du thème, et le paiement reste à un clic. L’éditeur d’une boutique le dit : « Ce thème n’a pas de panier ».

#L’API

Sur l’adresse de la boutique, aux chemins et aux formes de Shopify. Les réponses sont du JSON, jamais en cache.

DemandeCorpsRéponse
GET /cart.js (ou .json)—le panier
POST /cart/add.js{ "items": [{ "id", "quantity", "properties" }] }, ou un article à platles lignes ajoutées ({ items }), ou la ligne seule pour un article à plat
POST /cart/change.js{ "line": 1, "quantity": 0 } ou { "id": "<key>", "quantity": 2, "properties": {…} }le panier
POST /cart/update.js{ "updates": { "<key>": 2 }, "note": "…", "attributes": { "cadeau": "oui" }, "discount": "NOEL10" }le panier
POST /cart/clear.js—le panier, vide (la note et les attributs restent)
POST /cart/add, /cart/change, /cart/update, /cart/clearun formulaire303 vers /cart (/checkout si le formulaire porte checkout)
GET /cart/change?line=1&quantity=0—303 vers /cart (une quantité seulement : des properties dans l’adresse sont refusées, 405)

id est l’identifiant d’une variante, ou d’un produit sans variante. Les properties sont rapprochées des champs de personnalisation du produit, par leur identifiant ou leur libellé (« Prénom ») ; une clé qui commence par _ est un champ discret. Une propriété qui ne correspond à aucun champ n’est pas gardée.

Ajouter, puis redessiner sa sectionjs
const r = await fetch("{{ routes.cart_add_url }}.js", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ items: [{ id, quantity: 1, properties: { Prénom: "Léa" } }], sections: "mon-tiroir" }),
});
const reponse = await r.json();
if (!r.ok) return afficher(reponse.description);
tiroir.innerHTML = reponse.sections["mon-tiroir"];
window.dispatchEvent(new CustomEvent("wcp:relire"));

sections (une liste, ou une chaîne séparée par des virgules, cinq au plus) renvoie, dans sections, le HTML de ces sections du thème publié rendues avec le nouveau panier — la « Section Rendering API » de Shopify. Une section de la coquille prend ses réglages enregistrés ; une section du gabarit cart, les siens. Une section absente ou en erreur vaut null.

Les erreurs ont la forme de Shopify : { "status": 422, "message": "Cart Error", "description": "…" }. 422 : article inconnu, hors vente, stock insuffisant, personnalisation incomplète, panier plein ; 400 : ligne introuvable ; 403 : demande venue d’un autre site ; 429 : trop de demandes.

#Les évènements

ÉvènementSurSens
wcp:majwindowle panier a changé ; detail.item_count
wcp:renduwindowle composant vient de se redessiner
wcp:ouvrirwindowà envoyer : ouvrez le tiroir du composant
wcp:relirewindowà envoyer après vos appels à l’API : le composant relit le panier
cart:updatedocumentcelui des thèmes Horizon, compris comme wcp:relire

Les compteurs [data-wc-panier-compte] et les liens a[href="/cart"] (ou [data-wc-panier-ouvrir]) sont tenus par le composant sur toute page.

#Ce qui est garanti

  • Aucun prix n’est cru. Le panier ne retient que des identifiants, des quantités, des saisies et un code. Prix, stock, remises et port sont relus dans le catalogue à chaque réponse, par la même fonction que le paiement ; un price envoyé est ignoré. La caisse recalcule tout encore une fois.
  • Le panier vit dans un cookie de l’hôte de la boutique, __Host-cart_<boutique> (cart_<boutique> en http, sur un poste de développement) : aucun autre hôte ne peut le poser, SameSite=Lax, Secure, trente jours. Il ne contient rien de secret ; il tient une quarantaine de lignes simples, au-delà l’ajout est refusé.
  • Le recalcul est limité à 300 demandes par dix minutes, par connexion et par boutique.
  • Une écriture venue d’un autre site est refusée (Origin d’un autre hôte).
  • Le paiement est un document de la plateforme. Le bouton du panier mène à /checkout ; rien du thème n’y entre.