Documentation de l'extension Advanced Shipping 2.6.2 pour Magento 1.x par Owebia

Exemple simple : port offert

Frais relatifs à la destination

Utiliser le caractère jocker * ou les expressions régulières

Frais relatifs au groupe client

On peut utiliser le nom ou l'ID des groupes client.

Utiliser les formules

Les formules peuvent être utilisées dans les propriétés conditions et fees.

Copier la propriété d'un autre élément

Utiliser la fonction min()

Utiliser la fonction range()

Utiliser la fonction substr()

Une variable de type chaîne de caractères doit être entourée par des guillemets simples sauf si on utilise l'auto-échappement avec les caractères {{ et }}.

Utiliser les fonctions spéciales

Utiliser les boucles {foreach …}

Manipuler les tableaux

Utilisation de la fonction in_array()

Utilisation de la fonction in_array() avec des chaînes de caractères *

Utilisation de la fonction array_match_any()

Utilisation de la fonction array_match_all()

Autres exemples

Les éléments

Il existe trois différents types d'élément de configuration :

• method : méthode de livraison (par défaut si non spécifié)
• data : données pouvant être utilisées dans une ou plusieurs méthodes de livraison (exemples)
• meta : données informatives (exemples)

Les propriétés

Chaque élément possède plusieurs propriétés :

• about : commentaire sur l'élément
• type : type de l'élément (method, meta ou data)

Propriétés spécifiques à un élément de type method :

• label : nom de la méthode de livraison
• description : description (visible seulement si le template l'affiche)
• enabled : méthode de livraison activée ou non
• fees : frais de port
• conditions : conditions d'activation
• shipto : pays (régions, codes postaux) autorisés à la livraison
• billto : pays (régions, codes postaux) autorisés à la facturation
• origin : pays (régions, codes postaux) autorisés en origine
• customer_groups : groupes de client autorisés
• tracking_url : URL de suivi (plus d'informations)

Voir les exemples

Utiliser les propriétés de type adresse (shipto, billto et origin)

Les codes pays utilisés sont ceux de Magento (à priori ils sont les mêmes que les codes ISO 3166-1 alpha-2).
Il est possible de spécifier les codes régions (uniquement avec shipto) ou les codes postaux que l'on veut filtrer ou exclure.

Vous pouvez utiliser le caractère jocker * ou les expressions régulières pour les codes postaux.
Une expression régulière doit commencer et se terminer par le caractère /. Si vous souhaitez utiliser les caractères (, ) ou ., vous devez les échapper avec le caractère \ (ex: "FR(/^25\([0-9]{3}\)$/)").
Vous pouvez utiliser l'option d'insensibilité à la casse (ex: "GB(/^PO.*$/i)").

Voir les exemples

L'identifiant unique

Chaque élément de configuration possède un identifiant unique. Cet identifiant permet ensuite de faire référence à l'élément.

Exemple :

Attention : pour éviter les conflicts, n'utiliser que les caractères a-z, A-Z, 0-9, - et _ pour former l'identifiant unique.
Vous devez également éviter les identifiants qui correspondent déjà à des noms de variable (cart, product, item…).

Les variables

Lorsque vous utilisez des variables qui ne sont pas numériques ou booléennes, vous devez les échapper avec des guillemets simples ou utiliser la syntaxe d'auto-échappement {{ }}.

Les variables suivantes peuvent être utilisées dans les formules.

• Le panier :
  • {cart.weight} : poids des marchandises
  • {cart.qty} : la quantité d'articles
  • {cart.price-tax+discount} : prix HT avec remise
  • {cart.price+tax+discount} : prix TTC avec remise
  • {cart.price-tax-discount} : prix HT sans remise
  • {cart.price+tax-discount} : prix TTC sans remise
  • {cart.coupon_code} : coupon de réduction
  • {cart.free_shipping} : frais de port offert (par une règle dans Magento) [true/false]
  • {cart.weight_unit} : l'unité de poids
  • {cart.weight_for_charge} : poids des marchandises dont la livraison n'est pas offerte (par les règles de prix panier de Magento)
• Le bon de commande :
  • {quote.subtotal}: sous-total HT
  • {quote.subtotal_with_discount}: sous-total HT avec remise
  • {quote.grand_total}: total TTC avec remise
  • {quote.base_subtotal}: sous-total HT dans la devise de base
  • {quote.base_subtotal_with_discount}: sous-total HT avec remise dans la devise de base
  • {quote.base_grand_total}: total TTC avec remise dans la devise de base
• Le group client :
  • {customer_group.id} : id du groupe client
  • {customer_group.code} : nom du groupe client
  • {customer_group.*} : propriété du groupe client (ex: {customer_group.tax_class_id})
• Le client :
  • {customer.id} : id du client
  • {customer.attribute.*} : attribut du client (ex: lastname, firstname, group_id…)
  • {customer.attribute.*.value} : dans le cas des attributs de type liste de sélection, {customer.attribute.*} retourne l'id, pour obtenir la valeur il faut utiliser {customer.attribute.*.value}
  • {customer.*} : identique à {customer.attribute.*}, sauf si la variable est déjà définie (ex: {customer.id} est déjà définie)
• Les variables personnalisées ou `Custom Variables` (depuis la version 1.4.0.1 de Magento) :
  • {customvar.*} : variable personnalisée de Magento (ex: {customvar.my_var})
• L'adresse de livraison :
  • {shipto.country_name} : le nom du pays
  • {shipto.country_id} : le code du pays
  • {shipto.region_id} : l'id de la région
  • {shipto.region_code} : le code de la région
  • {shipto.street} : la rue
  • {shipto.city} : la ville
  • {shipto.postcode} : le code postal
• L'adresse de facturation :
  • {billto.country_name} : le nom du pays
  • {billto.country_id} : le code du pays
  • {billto.postcode} : le code postal
  • {billto.*} : propriété de l'adresse de facturation (ex: {billto.city})
• L'adresse d'envoi :
  • {origin.country_name} : le nom du pays
  • {origin.country_id} : le code du pays
  • {origin.region_id} : l'id de la région
  • {origin.city} : la ville
  • {origin.postcode} : le code postal
• Le magasin :
  • {store.id} {store.code} {store.name} {store.address} {store.phone} : id, code, nom, adresse et téléphone du magasin
• La date courante :
  • {date.timestamp} : timestamp UNIX de la date actuelle
  • {date.year} {date.month} {date.day} {date.hour} {date.minute} {date.second} : année, mois, jour, heure, minute et seconde de la date actuelle
  • {date.weekday} : jour de la semaine de la date actuelle de 0 (dimanche) à 6 (samedi)
• L'objet request :
  • {request.*} : propriété de l'objet request (Mage_Shipping_Model_Rate_Request) passé en paramètre par Magento (ex: {request.package_qty}). Utiliser l'option "Déboguage" pour obtenir plus de détail sur les propriétés disponibles.

Les fonctions

Les fonctions numériques

• abs(x) : valeur absolue
• ceil(x) : arrondi supérieur
• exp(x) : exponentiel
• floor(x) : arrondi inférieur
• log(x) : logarithme népérien
• log(x, base) : logarithme
• max(x, y, …) : maximum, valeurs nulles ignorées
• min(x, y, …) : minimum, valeurs nulles ignorées
• pi() : nombre PI
• pow(x, puissance) : puissance
• rand(min, max) : entier aléatoire
• round(x) : arrondi
• sqrt(x) : racine carrée

Les fonctions pour manipuler des chaînes de caractères

• substr(string, start, length) : retourne un segment de chaîne de caractères.

Les fonctions pour manipuler des tableaux

• in_array(value, array(value1, value2, …)) : retourne vrai si la valeur se trouve dans le tableau.
• array_match_any(array(value1, value2, …), array(value1, value2, …)) : retourne vrai si au moins une valeur est présente dans les deux tableaux.
• array_match_all(array(value1, value2, …), array(value1, value2, …)) : retourne vrai si le contenu des tableaux est identique.

Fonctions diverses

• range(value, min, max, include_min, include_max) : retourne vrai si value est comprise entre min et max. Par défaut, include_min et include_max sont égales à true.

Les fonctions spéciales

• {table … in …} : définit des valeurs en fonction de seuils (exemples)
• {switch … in …} : définit une table de correspondance (exemples)

Le premier paramètre … des fonctions table et switch est la valeur de référence, il peut s'agir soit d'une variable, soit d'une formule.

• {count items[ where …]} : compte les articles remplissant les conditions (exemples)
• {count distinct …[ where …]} : compte les différentes valeurs d'une propriété pour les articles remplissant les conditions (exemples)
• {sum …[ where …]} : calcule la somme des valeurs d'une propriété pour les articles remplissant les conditions (exemples)
• {min …[ where …]} : retourne la valeur minimum d'une propriété pour les articles remplissant les conditions (exemples)
• {max …[ where …]} : retourne la valeur maximum d'une propriété pour les articles remplissant les conditions (exemples)

Le premier paramètre … des fonctions count distinct, sum, min et max doit être une propriété (ex: product.attribute.weight).

La condition where est facultative. Si elle est spécifiée, elle le sera sous la forme d'une formule.

Utilisation des boucles foreach

Les boucles foreach permettent d'effectuer un calcul sur des groupes de produits plutôt que de tenir compte de tous les produits du panier.
Le résultat global d'une boucle foreach est la somme des résultats de chaque passage dans la boucle.

A l'intérieur d'une boucle foreach, il est possible d'utiliser de nouvelles variables.

Exemples

Les variables dépréciées

Les variables suivantes doivent être remplacées par leur équivalente.

• {cart.coupon} {cart.coupon_code}
• {cart.quantity} {cart.qty}
• {cart.price_excluding_tax} {cart.price-tax+discount}
• {cart.price_including_tax} {cart.price+tax+discount}
• {cart.weight.for-charge} {cart.weight_for_charge}
• {cart.weight.unit} {cart.weight_unit}
• {customer.group.code} {customer_group.code}
• {customer.group.id} {customer_group.id}
• {{customVar code=*}} {customvar.*}
• {destination.country.code} {shipto.country_id}
• {destination.country.name} {shipto.country_name}
• {destination.postcode} {shipto.postcode}
• {destination.region.code} {shipto.region_code}
• {free_shipping} {cart.free_shipping}
• {origin.country.code} {origin.country_id}
• {origin.country.name} {origin.country_name}
• {origin.region.code} {origin.region_id}
• {selection.quantity} {selection.qty}

• product.quantity item.qty
• product.price-tax+discount item.price-tax+discount
• product.price-tax-discount item.price-tax-discount
• product.price+tax+discount item.price+tax+discount
• product.price+tax-discount item.price+tax-discount
• product.option.* item.option.*
• product.option.* item.option.*

L'URL de suivi tracking_url

L'utilisation de la propriété tracking_url est réservée aux utilisateurs expérimentés. Si vous ne comprenez pas les indications ci-dessous, il est préférable que vous évitiez d'utiliser cette fonctionnalité.

La propriété tracking_url permet de surcharger le champ "URL de suivi" d'un mode de livraison Advanced Shipping et ainsi de spécifier une URL de suivi par méthode de livraison plutôt qu'une pour tout le mode de livraison.

Pour insérer automatiquement le numéro de colis dans l'URL de suivi, vous devez utiliser {tracking_number}.

Magento ne gère pas les liens de tracking mais un statut de tracking. L'extension Advanced Shipping fournit un lien HTML à la place du statut, lien qui permet d'aller sur le site du transporteur et de suivre l'avancement de la livraison du colis.

Lorsque l'URL de suivi est construite par l'extension, la seule information disponible est le numéro de colis et on n'a nul part accès à la méthode de livraison sélectionnée. Afin de pouvoir retrouver l'url de suivi dans la configuration, il faut spécifier la méthode de livraison dans le numéro de tracking, par exemple : colissimo:8Lxxxxxxxxxxx où colissimo est le code de la méthode de livraison sélectionnée.
Si aucun code n'est spécifié (si vous saisissez uniquement le numéro de tracking), l'url utilisée sera celle globale au mode de livraison.

Pour répondre à une question récurrente, Magento affiche le statut de livraison depuis le back office ou le front office. Si vous souhaitez insérer l'URL de suivi dans les mails d'expédition, vous devrez développer vous même la récupération de l'URL de suivi et son insertion dans le mail, en effet, l'extension Advanced Shipping se contente de fournir des modes de livraison paramétrables sans apporter de grande modification au coeur de Magento afin de réduire les problèmes d'incompatibilité et de mise à jour.

Si vous obtenez un popup vide lorsque vous cliquez sur le lien de suivi, votre problème est très certainement lié au fait que vous n'avez pas spécifié le code de la méthode de livraison dans le numéro de suivi (voir indications plus haut) et que votre champ global "URL de suivi" est vide.

Il n'est actuellement pas prévu de modifier les fonctionnalitées de l'extension liées à l'URL de suivi.