Attention Le plugin ne s’occupe pas de la gestion des paniers, ni des paiements, ni des factures. Pour l’aspect « boutique », voir le post-scriptum.
Ce plugin a été élaboré grâce aux contributions de Matthieu Marcillaud, Rastapopoulos, Yffic, touti, Cyril, et du rédacteur de cet article.
Principe
Le plugin agit sur 2 fronts :
→ d’une part il permet aux utilisateurs de gérer les commandes depuis l’espace privé.
→ d’autre part, il fournit les outils permettants et aux développeurs et aux autres plugins de créer et manipuler des commandes.
Installation et dépendances
Le plugin est repertorié dans le dépôt proposé par défaut : « SPIP-Zone - Plugins ». Aussi, il est installable depuis la page Gestion des plugins
, onglet Ajouter des plugins
si vous avez activé ce dépôt.
2 dépendances seront installées automatiquement :
D’autres plugins sont plus ou moins optionnels, là c’est à vous de voir :
- Notifications avancées : à installer si on veut bénéficier de l’envoi de notifications par email.
- Facteur : sans lui, les notifications seront au format texte au lieu d’un joli HTML.
- Coordonnées : fortement recommandé afin de pouvoir gérer les adresses liées aux commandes (livraison et facturation).
- Contacts et organisations : peut vous servir à gérer les auteurs/clients des commandes.
Fonctionnement
A l’installation, 2 tables sont créées :
- La table principale
spip_commandes
sert à enregistrer les données de base des commandes : l’auteur/client, le numéro de référence, le statut et les dates. - La table auxiliaire
spip_commandes_details
sert à enregistrer les « détails » correspondants aux commandes, c’est à dire tous les éléments à partir desquels on va pouvoir calculer le prix total d’une commande : objets et services commandés, frais annexes, ristournes etc.
En théorie, à chaque commande enregistrée dans la table spip_commandes
doit correspondre une ou plusieurs lignes de détails dans la table spip_commandes_details
.
La table spip_commandes :
Une commande est un objet éditorial, au même titre que les articles, brèves et cie. Elles ont un auteur (le client), différents statuts et 3 types de dates : date de création, date de paiement & date d’envoi.
La date de création correspond au champ « date », elle est définie à la création de la commande, et n’est pas censée être altérée par la suite.
Le changement d’un statut peut déclencher l’envoi de notifications par email, et la mise à jour de la date s’y rapportant :
→ passer le statut à "payée" met à jour la date de paiement.
→ passer le statut à "envoyée" met à jour la date d’envoi.
id_commande |
Identifiant unique de la commande |
reference |
Numéro de référence (il ne s’agit pas d’une clé unique). |
id_auteur |
Identifiant de l’auteur/client |
statut |
encours , attente , partiel , paye , envoye , retour_partiel , retour , erreur |
date |
Date de création |
date_paiement |
Date de paiement |
date_envoi |
Date d’envoi |
maj |
Date de la dernière mise à jour |
La table spip_commandes_details :
Pour le contenu des commandes, on parle de « détails » : chaque commande est constituée d’une ou plusieurs lignes de détails.
Un détail est tout élément qui participe au prix d’une commande.
On peut distinguer 2 types de détails :
- Les détails correspondants directement aux objets ou aux services commandés.
- Les détails « annexes » : il peut s’agir des frais de port, des frais de dossier, des ristournes etc.
Une ligne de détail comprend à minima les champs descriptif
et prix_unitaire_ht
, le cas échéant complétés par les champs taxe
et quantite
.
Dans le cas où l’objet commandé est un objet éditorial SPIP, des champs objet
et id_objet
permettent de l’identifier.
id_commandes_detail |
Identifiant unique du détail (attention au « s » à commandes) |
id_commande |
Identifiant de la commande concernée |
descriptif |
Texte décrivant le détail. S’il s’agit d’un objet éditorial, il peut s’agir de son titre, descriptif ou autre. |
quantite |
Quantité |
prix_unitaire_ht |
Prix Hors Taxe |
taxe |
Taxe (TVA) |
statut |
Statut |
objet |
Type d’objet s’il s’agit d’un objet éditorial |
id_objet |
Identifiant de l’objet s’il s’agit d’un objet éditorial |
maj |
Date de la dernière mise à jour |
Exemple des enregistrements en base pour une commande et ses détails
Prenons une commande de 2 objets avec TVA à 20%, comportant des frais de port et une ristourne. Dans la base de donnée, ça nous donne ceci :
1 ligne dans la table spip_commandes
id_commande | reference | id_auteur | statut | date | date_paiement | date_envoi | maj |
1 | xxxxxx | 1 | encours | 2014-05-14 09:00:00 | 0000-00-00 00:00:00 | 0000-00-00 00:00:00 | 2014-05-14 09:00:00 |
4 lignes dans la table spip_commandes_details
id_commandes
_detail |
id_commande | descriptif | quantite | prix
_unitaire_ht |
taxe | statut | objet | id_objet | maj |
1 | 1 | Gibolin 2000 | 2 | 8 | 0.2 | produit | 1 | 2014-05-14 09:00:00 | |
2 | 1 | Ripolin 5000 | 1 | 12 | 0.2 | produit | 2 | 2014-05-14 09:00:00 | |
3 | 1 | Frais de port | 0 | 4 | 0 | 2014-05-14 09:00:00 | |||
4 | 1 | Ristourne | 0 | -2 | 0 | 2014-05-14 09:00:00 |
Boucles et balises
Balises #PRIX
et #PRIX_HT
Grâce au plugin API prix, les balises #PRIX
et #PRIX_HT
permettent d’obtenir automagiquement les prix TTC et HT d’une commande ou d’un de ses détails.
Dans une boucle COMMANDES :
-
#PRIX
= somme des prix TTC des détails. -
#PRIX_HT
= somme des prix HT des détails.
Dans une boucle COMMANDES_DETAILS :
-
#PRIX
=#QUANTITE
* (#PRIX_UNITAIRE_HT
+ (#TAXE
*#PRIX_UNITAIRE_HT
)) -
#PRIX_HT
=#QUANTITE
*#PRIX_UNITAIRE_HT
.
Boucles
Exemple minimal de boucle affichant pour chaque commande un résumé de ses détails et son prix total TTC :
<BOUCLE_commandes(COMMANDES)>
<h4>Commande N°#ID_COMMANDE</h4>
<ul><BOUCLE_details(COMMANDES_DETAILS){id_commande}>
<li>[(#QUANTITE) *]#DESCRIPTIF = #PRIX</li>
</BOUCLE_details></ul>
Prix total TTC : #PRIX
</BOUCLE_commandes>
Gestion dans l’espace privé
Configuration
La page de configuration est accessible depuis le menu Configuration
> Commandes
On peut y gérer les 3 points suivants :
- La durée d’expiration des commandes ayant le statut « en cours ». On considère que les commandes restant « en cours » pendant plus d’un certain temps sont des commandes abandonnées : il est inutile de les conserver dans la base.
- l’activation et le fonctionnement des notifications (cf. plus bas).
- L’affichage en page d’accueil de la liste des commandes « actives » (cf. plus bas).
Liste des commandes
Une page Commandes
est accessible depuis le menu Edition
.
L’encart à gauche sert à filtrer les commandes en fonction de leurs états, de leurs dates de création, et des auteurs/clients.
Au niveau de la liste, les commandes ayant le statut « envoyé » sont surlignées en vert, afin de repérer facilement les commandes terminées.
Fiche d’une commande
La fiche d’une commande est composé de 3 parties :
- Le contenu de la commande : il s’agit d’un tableau listant les détails de la commande.
- Les adresses : si le plugin Coordonnées est installé, sont affichées les adresses associées à la commande, ou à défaut celles associées à l’auteur de la commande.
- L’auteur/client de la commande : si le plugin Contacts et Organisations est installé, on affiche les infos du contact, sinon des infos sur le client.
A noter : Pour les adresses, il n’est pas nécessaire d’activer l’ajout de coordonnées aux commandes dans les options du plugin Coordonnées.
Commandes « actives »
Il est possible d’afficher en page d’accueil la liste des commandes « actives ». il s’agit des commandes nécessitant une prise en charge. Pour se faire, il faut activer l’option dans la configuration du plugin, et choisir les statuts correspondants.
Notifications
Mise en place
On peut activer ’envoi d’emails de notification au vendeur et au client lorsque les commandes acquièrent certains statuts.
Le plugin « Notifications avancées » doît être installé. Le plugin Facteur est également fortement recommandé afin d’envoyer les messages au format HTML.
Rendez vous ensuite sur le formulaire de configuration du plugin pour activer et configurer les notifications.
Personnalisation des emails
Par défaut, les messages envoyés sont spartiates :
Leurs squelettes sont présents dans le répertoire /notifications
du plugin.
Pour chaque type de notification (vendeur
& client
), il y a 3 variantes :
-
commande_xxx_html.html
au format HTML. -
commande_xxx.html
au format texte brut. -
commande_xxx_court.html
au format court, type microblog ou SMS.
Par commodité, ces 6 squelettes incluent tous le même squelette mutualisé, avec différents paramètres pour moduler l’affichage : contenu_commande_mail.html
.
Il suffit de surcharger ce squelette pour le personnaliser selon vos besoins.
Si vous avez besoin de 2 squelettes vraiment différents pour les emails vendeur et client, vous pouvez au choix :
- Faire ça au niveau du squelette
contenu_commande_mail.html
en jouant sur le paramètre#ENV{qui}
:[(#ENV{qui}|=={client}|oui)<INCLURE{fond=mon_squelette_mail_client, env}>][(#ENV{qui}|=={vendeur}|oui)<INCLURE{fond=mon_squelette_mail_vendeur, env}>]
- Ou bien surcharger directement les 6 squelettes clients et vendeurs.
Fonctions utiles
Voici une liste non exhaustive de certaines fonctions, celles qui pourront vous être utiles lors de l’intégration du plugin dans votre projet. Pour les détails (paramètres etc.) et la liste complète, voir le site https://code.spip.net/commandes/.
commandes_lister_statuts Cette fonction retourne les différents statuts des commandes. On peut s’en servir comme filtre dans les squelettes pour obtenir la chaîne de langue d’un statut : [(#STATUT|commandes_lister_statut)] |
creer_commande_encours Crée une commande avec le statut « en cours » pour le visiteur actuel. La commande créée est « vide » : la fonction ne se charge pas de créer les détails. C’est le rôle des plugins tiers (Commandes de paniers par ex.). A noter : on considère qu’il ne peut y avoir qu’une commande « en cours » par session et par auteur. Si une telle commande est déjà présente dans la session, elle va être supprimée de la base et de la session avant la création de la nouvelle.
|
commandes_supprimer Permet de supprimer « proprement » une ou plusieurs commandes, en s’occupant également des données associées. Pour chaque commande à supprimer, la fonction effectue les actions suivantes : - suppression de la commande - suppression de ses détails - dissociation de ses adresses liées, et éventuellement suppression si elles se retrouvent orphelines. Exemple :
|
traiter_notifications_commande Envoie les notifications par email d’une commande, si les conditions sont réunies. Cette fonction est appelée lors de la création d’une commande, puis à chaque changement de statut. |
inc_commandes_reference_dist Cette fonction retourne une référence unique utilisée pour remplir le champ éponyme lors de la création d’une commande. Il s’agit du temps écoulé depuis le 1er janvier 1970, en secondes. Elle est destinée à être surchargée pour l’adapter à vos besoins. |
supprimer_commande Supprime « proprement » une commande. Fait appel à la fonction commandes_effacer , avec les mêmes effets donc.Exemple : #URL_ACTION_AUTEUR{supprimer_commande,#ID_COMMANDE,#SELF} |
instituer_commande Change le statut d’une commandes Exemple : #URL_ACTION_AUTEUR{instituer_commande,#ID_COMMANDE-envoye,#SELF} |
Discussions par date d’activité
Une discussion
Sur un site 3.2.19 j’ai fait la mise à jour des plugins commandes (de la version 1.15.13 à 1.19.2) et paniers (de la version : 1.4.0 à 1.7.0),
mais pas de l’API prix toujours en 1.0.0 (vu les ennuis safehtml décrits sur le forum pour les nouvelles versions).
Je n’ai pas de customisation de fonctions de prix.
Mais depuis cette mise à jour (avant les prix sont corrects) la balise #PRIX (tout comme #PRIX_HT) arrondit le prix à l’euro supérieur.
Par exemple, avec une commande avec dans la table commandes_details d’un seul détail d’une quantité 1, sans taxe, de prix HT 19.91 Euros :
le résultat dans une BOUCLE_commande est :
#PRIX* affiche 20 ( tout comme #PRIX_HT*)
Qu’est-ce qui pourrait bien expliquer cet arrondi après mise à jour ?
Merci !
De mémoire il y a eu un bug d’arrondi à un moment dans le plugin, mais ça a été corrigé de longue date. Il faut passer à une version à jour (la v1.0 a 4 ans !).
Pour l’histoire du safehtml il y a une solution temporaire, c’est dans un ticket, faut que je retrouve lequel.
Ah voilà, pour safehtml c’était là : https://git.spip.net/spip-contrib-extensions/intl/pulls/5#issuecomment-34336
Ok, Tcharlss,
Merci pour tout ! Je vais donc voir avec le nouvel API prix.
Cheers!
Répondre à ce message
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |