Actions ExperSHOP


Page Principale Table

Pour tout rapport de bug ou suggestion, envoyez un mèl au Support ExperLog


Les Actions, c'est quoi ?

Les Actions sont des classes Java, invoquées à la demande par ExperSHOP pour exécuter certaines tâches.

ExperSHOP est livré avec un certain nombre d'actions prédéfinies: par exemple, l'action com.expershop.actions.ESAddToCart sert à ajouter un article dans le panier d'achats.

Les actions peuvent être invoquées :

  • Directement depuis un modèle de page DynHtml, en utilisant l'instruction $Action.
    Les actions "Server-side" ne peuvent être appelées que par ce moyen.
  • Par ExperSHOP lors du chargement des pages, avant d'afficher le contenu:
    L' Action est alors passées en paramètre aux servlets ExperSHOP via le paramètre HTTP "Action": invoquer un servlet ExperSHOP avec Action=com.expershop.actions.ESAddToCart dans sa liste de paramètres ajoutera l'article spécifié au panier d'achats avant d'afficher quoi que ce soit.
    Les actions "Server-side" ne peuvent pas être appelées par ce moyen, pour des raisons de sécurité.

Les Actions peuvent recevoir des paramètres (également passés au servlet comme paramètres HTTP), et peuvent aussi retourner des paramètres comme résultat (ces nouveaux paramètres seront visibles du servlet comme des paramètres HTTP).
Par exemple, l'action ESAddToCart reçoit un paramètre "ProdId", avec pour valeur la référence de l'article à ajouter au panier d'achats.

Une action peut s'exécuter avec succès, ou échouer; il est possible de récupérer l'erreur et de l'afficher grace à un template: le paramètre HTTP "ActionFailed" définit quelle page afficher si l'action échoue.

Actions ExperSHOP prédéfinies

Les actions suivantes sont prédéfinies:

Actions à usage général:

Actions d'administration :

  • Les actions d'administration sont accessibles uniquement à l'administrateur de la boutique; voir la documentation des actions d'administration pour plus de détails.

Actions réservées au paiement sécurisé:

  • Paiement Sécurisé; ExperShop s'interface avec plusieurs systèmes de paiement sécurisé : les Actions sont largement utilisées dans ce cadre, voir la documentation concernant le paiement sécurisé pour plus de détails.
Nous allons maintenant détailler chaque action, ainsi que ses paramètres en entrée et en sortie.

com.expershop.actions.ESAddToCart

Ajouter un article au panier d'achats.

Paramètres d'entrée:

  • ProdId (OBLIGATOIRE) - La référence de l'article à ajouter au panier d'achats
  • Qty (FACULTATIF) - La quantité, 1 par défaut.
  • Options (FACULTATIF) - Chaine de caractères pour décrire des options.
  • Superior (FACULTATIF) - Un identifiant d'article dans le panier (ItemId), dont le nouvel article sera un sous-article.
  • OptionNames (FACULTATIF) - Pour les produits comportant plusieurs options: ce paramètre contient les noms des options, qui sont eux-mêmes des noms de paramètres. Les noms doivent être séparés par des virgules: par exemple, "Couleur,Pointure".
  • UINFO_[nom] (FACULTATIF) - Pour stocker des informations dans le panier. Chaque information a un nom et une valeur, et reste en mémoire aussi longtemps que le panier n'est pas vide. Pour accéder à l'information, utiliser $ShoppingCart:UInfo.[nom], [nom] étant le nom associé à l'information.
  • AllowDups (FACULTATIF) - Si présent (par exemple, égal à 1), autorise l'ajout de doublons dans le panier d'achats.

Paramètres en sortie:

  • ItemId: identifiant unique de l'article ajouté dans le panier.

com.expershop.actions.ESUpdateCart

Mettre à jour le contenu du panier d'achats.

Paramètres d'entrée:

  • TaxZone (FACULTATIF) - Le nom de zone pour le calcul de la Taxe sur la Valeur Ajoutée.
  • ShippingZone (FACULTATIF) - Le nom de zone pour le calcul des frais de livraison.
  • DiscountCode (FACULTATIF) - Le code remise pour le calcul de la remise.
  • AddItems (FACULTATIF) - Si présent (par exemple, égal à "O"), les articles spécifiés qui ne seraient pas présents seront ajoutés au panier.
  • Superior (FACULTATIF) - A combiner avec AddItems; Un identifiant d'article dans le panier (ItemId), dont les nouveaux articles seront des sous-articles. Si le supérieur n'est pas présent, il sera également ajouté
  • UINFO_[nom] (FACULTATIF) - Pour stocker des informations dans le panier. Chaque information a un nom et une valeur, et reste en mémoire aussi longtemps que le panier n'est pas vide. Pour accéder à l'information, utiliser $ShoppingCart:UInfo.[nom], [nom] étant le nom associé à l'information.
  • AllowDups (FACULTATIF) - Si présent (par exemple, égal à 1), autorise l'ajout de doublons dans le panier d'achats.
Et POUR CHAQUE ARTICLE concerné:
  • QTY_[ItemId] - la quantité (nombre d'occurrences de cet article), [ItemId] est la référence de l'article dans le panier d'achats (exemple: QTY_$ItemId$ dans une boucle). Une valeur nulle supprime l'article et ses sous-articles.
    Si AddItems est présent, ItemId sera considéré comme une référence article à ajouter.
  • Options_[ItemId] (FACULTATIF) - Chaine de caractères pour décrire des options.
  • OptionNames_[ItemId] (FACULTATIF) - Pour les articles comportant plusieurs options: ce paramètre contient les noms des options, qui sont eux-mêmes des noms de paramètres. Les noms doivent être séparés par des virgules: par exemple, "Couleur,Pointure".
  • DEL_[ItemId] (FACULTATIF) - Supprimer un article du panier d'achats: si ce paramètre est égal à "y" ou "Y" (pour "yes"), l'article spécifié est supprimé, ainsi que ses éventuels sous-articles.

com.expershop.actions.ESEmptyCart

Vider le panier d'achats.
Cette action peut être utilisée lors de l'interfaçage d'ExperSHOP avec un système de paiement sécurisé incluant des fonctions de back-office: dans ce cas, le marchand peut ne pas souhaiter utiliser le back-office d'ExperSHOP, et simplement vider le panier d'achats lorsqu'une commande client est confirmée.

com.expershop.actions.ESConfigureCart

Configurer le panier d'achats - en particulier, pour changer la table utilisée pour les produits.
Cette action est réservée à des utilisations avancées du panier d'achats.
Action "Server-side".

Paramètres en entrée :

Tout paramètre qui commence par CONFIG_ .
Si l'action ne reçoit aucun paramètre, elle restaure les valeurs par défaut de la configuration.
Pour changer la table utilisée pour les produits :

  • CONFIG_Table: le nom de la nouvelle table produits (défaut: EProduct)
  • CONFIG_ProdId: le nom de la nouvelle colonne ProdId (référence produit; défaut: ProdId)
  • CONFIG_Name: le nom de la nouvelle colonne Name (nom du produit; défaut: Name)
  • CONFIG_Price: le nom de la nouvelle colonne Price (prix du produit; défaut: Price)

Paramètres en sortie : aucun.

com.expershop.actions.ESSaveCart

Sauvegarder le contenu du panier d'achats.

Paramètres en entrée :

  • CartId (FACULTATIF) : un identifiant de panier sauvegardé. Si cet identifiant a déjà été utilisé, l'enregistrement correspondant dans la base de données sera écrasé.

Paramètres en sortie:

  • CartId : un identifiant unique de panier sauvegardé, généré par ExperSHOP, ou speécifié lors de l'appel.

com.expershop.actions.ESRestoreCart

Restaurer un panier d'achats précédemment sauvegardé: le contenu du panier sera remplacé.

Paramètres d'entrée:

  • CartId: L'identifiant unique de panier sauvegardé généré par ExperSHOP lors d'une sauvegarde précédente.

com.expershop.actions.ESCustomerLogin

Connecter un client existant (log-in).

Paramètres d'entrée:

  • Login (OBLIGATOIRE) - Le code client
  • Password (OBLIGATOIRE si les mots de passe sont activés) - Le mot de passe client
Paramètres en sortie:
  • En cas de succès, le client est connecté (le code client sera implicitement passé à tous les servlets ExperSHOP)
  • Le code client sera alors accessible via le cookie ($Cookie:CustId$). On pourra par exemple s'assurer du succès de l'action comme suit : $IfPresent Cookie:CustId.

com.expershop.actions.ESNewCustomer

Créer un nouveau client dans la base de données.

Paramètres d'entrée:

  • Mandatory (FACULTATIF) - La liste, séparée par des virgules, de tous les champs obligatoires.
    Exemple: Mandatory=FirstName,LastName,Address pour dire que les prénom, nom et adresse client sont obligatoires.
    Valeur par défaut: FirstName,LastName,Address,City,ZipCode,Country (prénom, nom, adresse, ville, code postal et pays obligatoires).
  • Login (FACULTATIF) - "true" (vrai) ou "false" (faux), défaut "true": spécifie si le client nouvellement créé doit être connecté immédiatement, ou pas.
  • CustId (FACULTATIF) - Si présent, permet au client de choisir son propre identifiant client (par exemple, son nom); Dans le cas où cet identifiant existe déjà dans la base, un chiffre y sera ajouté (en commençant à 1, puis 2, etc...) afin de le rendre unique.
  • Autres paramètres: ceux qui sont spécifiés dans la valeur du paramètre "Mandatory" sont obligatoires, d'autres champs éventuels étant facultatifs.
Paramètres en sortie:
  • MissingField - Présent seulement si un champ obligatoire n'est pas renseigné, égal au nom du champ manquant.
  • Si le paramètre Login est égal à "true", le nouveau client est connecté (le code client sera implicitement passé à tous les servlets ExperSHOP)

com.expershop.actions.ESUpdateCustomer

Mettre à jour un client existant dans la base de données.

Paramètres d'entrée:

  • CustId (OBLIGATOIRE, sauf si le client est déjà connecté) - Le code client.
  • Mandatory (FACULTATIF) - La liste, séparée par des virgules, de tous les champs obligatoires.
    Exemple: Mandatory=FirstName,LastName,Address pour dire que les prénom, nom et adresse client sont obligatoires.
    Valeur par défaut: aucun champ obligatoire.
  • Login (FACULTATIF) - "true" (vrai) ou "false" (faux), défaut "true": spécifie si le client nouvellement modifié doit être connecté immédiatement, ou pas.
  • Autres paramètres: ceux qui sont spécifiés dans la valeur du paramètre "Mandatory" sont obligatoires, d'autres champs éventuels étant facultatifs.
Paramètres en sortie:
  • MissingField - Présent seulement si un champ obligatoire n'est pas renseigné, égal au nom du champ manquant.
  • Si le paramètre Login est égal à "true", le nouveau client est connecté (le code client sera implicitement passé à tous les servlets ExperSHOP)

com.expershop.actions.ESOrderAct

Passer commande du contenu du panier d'achat (le panier d'achats est ensuite vidé).
L'état de la nouvelle commande sera égal à "WAITING" (en attente de paiement), car cette action est destinée au paiement par chèque ou fax.

ESOrderAct crée une nouvelle entrée dans la table ECustOrder de la base de données: vous pouvez mettre à jour les colonnes de votre choix dans votre commande, en spécifiant dans votre FORM HTML des paramètres HTTP portant le même nom que les colonnes à mettre à jour dans la table ECustOrder.
Par exemple, pour collecter le numéro de carte de crédit et la date d'expiration, utilisez des tags HTML de type INPUT nommés CcNum et CcExpDate (correspondant aux champs CcNum et CcExpDate dans la table ECustOrder).
Vous pouvez aussi ajouter des colonnes de votre choix à la table ECustOrder, puis les mettre à jour par le même moyen.

Paramètres d'entrée:

  • Aucun si un client est connecté (voir le paramètre "Login" des actions ESNewCustomer et ESUpdateCustomer, ainsi que l'action ESCustomerLogin).
    Sinon, les paramètres "ShipName" et "ShipAddress" (nom et adresse de livraison) doivent être présents.
Paramètres en sortie:
  • OrdId : Le code commande, automatiquement généré par ExperSHOP.

com.expershop.actions.ESNewDiscount

Créer un nouveau code remise dans la base de données.

Paramètres d'entrée :

  • Dcode : Code remise
  • Rate : Taux de remise
  • Dtype (FACULTATIF) : Type de remise (défaut : FLAT; autres valeurs possibles : PRICE, FREESHIPPING, GIFT)
  • Maxuse (FACULTATIF) : Nombre maximal d'utilisations de ce code (défaut : 1)
  • Datemin (FACULTATIF) : Date de début (défaut : aucune)
  • Datemax (FACULTATIF) : Date de fin (défaut : 30 jours de validité)
  • Minamount (FACULTATIF) : Montant minimal pour rendre ce code applicable (défaut : Rate pour type FLAT, 0 sinon)
  • Minqty (FACULTATIF) : Nombre minimal d'articles commandés pour rendre ce code applicable (défaut : 0)
  • Descrip (FACULTATIF) : Description texte de ce code lorsqu'il est applicable (défaut : "Discount")
  • Notapplicable (FACULTATIF) : Description texte de ce code lorsqu'il n'est pas applicable (défaut : "Not applicable")
  • Dcond (FACULTATIF) : Condition SQL pour rendre ce code applicable - appliquée à la table EProduct avec un "and" SQL (défaut : pas de condition; non applicable aux types GIFT et FREESHIPPING)
Paramètres en sortie EN CAS DE SUCCES :
  • Dcode2 : Le code remise généré (égal au paramètre d'entrée "Dcode").
Paramètres en sortie EN CAS D'ERREUR :
  • MissingField : Présent seulement si un champ obligatoire n'est pas renseigné, égal au nom du champ manquant.

com.expershop.actions.ESCheckParams

Contrôle des paramètres obligatoires: par exemple, lors de la soumission d'une forme de saisie, peut servir à vérifier que le nom du client est bien présent.

Paramètres d'entrée:

  • Mandatory - Liste des paramètres obligatoires (séparés par des virgules).
  • ErrorTemplate - (FACULTATIF) Un message d'erreur à afficher en cas d'absence d'un paramètre obligatoire.
    ErrorTemplate peut contenir des informations dynamiques, complétées au moment de l'élaboration du message: par exemple, "Le paramètre $MissingField$ est absent" affichera le nom du paramètre absent dans le message (MissingField est un paramètre en sortie de l'action ESCheckParams, voir ci-dessous).
  • All - (FACULTATIF) Si égal à "true" (vrai), l'action retournera la liste de tous les paramètres absents (séparés par des virgules), sinon seul le nom du premier paramètre absent sera retourné.
Paramètres en sortie EN CAS D'ERREUR:
  • MissingField - Nom du premier paramètre manquant, ou liste de tous les paramètres absents (séparés par des virgules) si le paramètre "All" est égal à "true" (vrai).
  • Message - Message d'erreur correspondant, selon la valeur du paramètre d'entrée ErrorTemplate (valeur par défaut du message d'erreur, en anglais: "Parameter [nom-du-paramètre-absent] should have a value.")
Paramètres en sortie EN CAS DE SUCCES: Aucun.

com.expershop.actions.ESSendMail

Envoi d'e-mail.

Paramètres de configuration:

  • email.MailHost - Nom ou adresse IP du serveur de mail (FACULTATIF, valeur par défaut = localhost - machine locale).
Paramètres d'entrée:
  • From - Adresse e-mail de l'émetteur (FACULTATIF si email.From est défini dans le fichier de configuration de la boutique)
  • To - Adresse e-mail du destinataire (FACULTATIF si email.ManagerEmail est défini dans le fichier de configuration de la boutique), pour indiquer plusieurs destinataires, les séparer par des virgules.
  • Subject - Sujet du mail (FACULTATIF, valeur par défaut (en anglais): "(No Subject)")
  • Content_type - Le type de contenu: directives Content-type & charset (FACULTATIF)
    Exemple, valeur pour un mail en français: "text/plain\; charset=fr-ascii\n";
  • Template - (OBLIGATOIRE) Chemin d'accès à un fichier modèle pour construire le contenu du mail (syntaxe du fichier: DynHtml). Le chemin est relatif au répertoire rachine de la boutique.
Paramètres en sortie: Aucun.

com.expershop.actions.ESSendMailMP

Envoi d'e-mail avec fichiers attachés.

Paramètres d'entrée:

  • From - Adresse e-mail de l'émetteur (FACULTATIF si email.From est défini dans le fichier de configuration de la boutique)
  • To - Adresse e-mail du destinataire (FACULTATIF si email.ManagerEmail est défini dans le fichier de configuration de la boutique). Pour indiquer plusieurs destinataires, les séparer par des virgules.
  • Cc - Adresse e-mail pour copie (FACULTATIF). Pour indiquer plusieurs destinataires, les séparer par des virgules.
  • Bcc - Adresse e-mail pour copie cachée (FACULTATIF). Pour indiquer plusieurs destinataires, les séparer par des virgules.
  • ReturnReceiptTo - Adresse email pour accusé de réception par le serveur de mail (FACULTATIF)
  • ConfirmReadingTo - Adresse email pour confirmation de lecture par le destinataire (FACULTATIF)
  • Subject - Sujet du mail (FACULTATIF, valeur par défaut (en anglais): "(No Subject)")
  • Content_type - Le type de contenu: directives Content-type & charset (FACULTATIF)
    Exemple, valeur pour un mail en français: "text/plain\; charset=fr-ascii\n";
  • Template - (OBLIGATOIRE) Chemin d'accès à un fichier modèle pour construire le contenu du mail (syntaxe du fichier: DynHtml). Le chemin est relatif au répertoire rachine de la boutique.
  • Attachment - un ou plusieurs fichiers à mettre en attachement au présent mail (FACULTATIF). Chemin relatif au répertoire défini par app.UploadDir (absolu ou relatif à la webapp) dans le fichier de configuration.
  • remove - tous les fichiers attachés seront supprimés du serveur une fois que le mail sera envoyé. Cette option est utile lorsque l'action ESSendMailMP est utilisée avec la servlet ESUploaderServlet.
    Valeurs autorisées: 1, les fichiers sont ensuite supprimés, 0 (valeur par défaut) les fichiers sont conservés sur le serveur (FACULTATIF).
Paramètres en sortie: Aucun.
Attention: les packages mail.jar et activation.jar sont requis pour cette action (Ils sont livrés en standard dans Tomcat).

Exemple pour envoyer en attachement une liste de fichiers qui proviennent de la servlet ESUploaderServlet. Les noms des fichiers sont stockés dans des paramètres 'uploadfile[n]' avec n commençant à 1. remove=1, les fichiers seront ensuite supprimés du serveur.

$Assign Template ESTemplates/Mail/custom.tmpl
$Assign To his_name@his_company.com
$Assign From my_name@my_company.com
$Assign Subject a new version
$Assign remove 1
$Assign Attachment ""
$DefVar nf 1->$nbfiles$
$LoopOnEnum nf bf
 $Append Attachment " "
 $Defvar pname uploadfile$bf:value$
 $Append Attachment $(Eval)pname$
$EndLoop
$Action com.expershop.actions.ESSendMailMP 
      

com.expershop.actions.ESWriteFile

Ecrire un fichier sur le disque, par expansion d'un modèle de page DynHtml.
Action "server-side" pour des raisons de sécurité: ne peut être invoquée que via $Action.
Exemple (Unix):
$Assign Template ESTemplates/xml/toxml.tmpl
$Assign File /usr/tmp/resultat.xml
$Action com.expershop.actions.ESWriteFile

Paramètres d'entrée:

  • Template (OBLIGATOIRE) - Le nom du modèle de page DynHtml; Relatif au répertoire racine de l'application (RootDir).
  • File (OBLIGATOIRE) - Le nom du fichier à écrire; Relatif au racine de l'application (RootDir), ou chemin absolu.
    Notez que ce fichier sera créé par l'application, donc par l'utilisateur du serveur web au sens de la sécurité.
Paramètres en sortie: Aucun.