Documentation officielle de l'extension Magento Owebia Shipping version 2.4.7 - 20/03/2012

Sommaire

Introduction

Si vous souhaitez poser une question, utilisez le sujet suivant : http://www.magentocommerce.com/boards/viewthread/38223/

La syntaxe de configuration est une syntaxe proche de la syntaxe JSON.

Exemple :

Le caractère `#` en début de ligne indique un commentaire.
Un élément de configuration débute par le caractère `{` et se termine par `}`.
Un élément de configuration contient plusieurs propriétés associées à des valeurs.
Les propriétés sont alphanumériques (a-z0-9_), le séparateur propriété/valeur est le caractère `:`, les valeurs sont numériques, booléennes ou des chaînes de caractères délimitées par des guillemets. En fin de ligne, une virgule sert de séparateur entre les différentes propriétés.

Liste des propriétés :

• label: nom (libellé)
• description: description (visible seulement si le template l'affiche)
• code: code de la méthode de livraison (facultatif mais s'il est spécifié il doit être unique)
• enabled: bloc de configuration activé ou non (ex: true ou false)
• fees: frais de port (ex: "15.00" ou "{table {cart.weight} in 0.5:5.30, 1.0:6.50}" ou "100 * {cart.weight}")
• conditions: conditions d'activation (ex: "{cart.weight}>=1.0" ou "{cart.price_excluding_tax}<100.00" ou "({cart.weight}<=1.0) and ({cart.weight}>3.0) and {free_shipping}" ou "{count products where product.attribute.color=='Bleu'}>1 or {count products where product.option.size=='2m'}>2")
• destination: pays (éventuellement régions) autorisés en destination (ex: "FR,DE,US" ou "FR(2A,2B,25000)" ou "FR-(2A,2B)" ou "FR(01,02,39600),CH,DE")
• origin: pays (éventuellement régions) autorisés en origine (ex: "FR,DE,US" ou "FR(2A,2B,25000)" ou "FR-(2A,2B)" ou "FR(01,02,39600),CH,DE")
• customer_groups: groupes de client autorisés (ex: "NOT LOGGED IN,Retailer" ou "0,3")

Le libellé : `label`

Il s'agit du nom qui sera donné à la méthode de livraison.

On peut insérer certains éléments comme le poids des marchandises dans le libellé.
Pour ce faire, utiliser les variables suivantes :

• {destination.country.name}: le pays de destination
• {destination.country.code}: le code du pays de destination
• {destination.region.code}: le code de la région de destination
• {destination.postcode}: le code postal de destination
• {origin.country.name}: le pays d'envoi
• {origin.country.code}: le code du pays d'envoi
• {origin.region.code}: le code de la région d'envoi
• {origin.postcode}: le code postal d'envoi
• {cart.weight}: poids des marchandises
• {cart.weight.unit}: l'unité de poids
• {cart.quantity}: la quantité d'articles
• {cart.price_excluding_tax}: prix HT (équivaut à {cart.price-tax+discount})
• {cart.price_including_tax}: prix TTC (équivaut à {cart.price+tax+discount})
• {cart.price-tax+discount}: prix HT avec remise
• {cart.price-tax-discount}: prix HT sans remise
• {cart.price+tax+discount}: prix TTC avec remise
• {cart.price+tax-discount}: prix TTC sans remise
• {cart.coupon}: coupon de réduction
• {store.code}: code du magasin
• {store.name}: nom du magasin
• {store.address}: adresse du magasin
• {store.phone}: téléphone du magasin
• {date.timestamp}: timestamp UNIX de la date actuelle
• {date.year}: année de la date actuelle
• {date.month}: mois de la date actuelle
• {date.day}: jour de la date actuelle
• {date.hour}: heure de la date actuelle
• {date.minute}: minute de la date actuelle
• {date.second}: seconde de la date actuelle

La ligne ci-dessus affichera par exemple "Colissimo (3.0kg / France)".

Les frais de port : `fees`

La propriété `fees` se spécifie sous la forme d'une formule (voir l'initiation aux formules).

Initiation aux formules

Les propriétés `fees` et `conditions` sont spécifiées sous la forme de formules.

Signes mathématiques disponibles :

• opérateurs : *, /, + et -
• modulo : %
• parenthèses : ( et )
• les opérateurs booléens &&, and, ||, or, ==, <, >, <=, >=
• les opérateurs binaires & et |
• le groupe d'opérateur C ? X : Y (ex: "{cart.price_exluding_tax}>100 ? 15*{cart.weight} : 20*{cart.weight}")

Fonctions disponibles :

• arrondis : round(x), floor(x), ceil(x)
• valeur absolue : abs(x)
• maximum : max(x,y)
• minimum : min(x,y)
• entier aléatoire : rand(min,max)
• puissance : pow(x,puissance)
• nombre PI : pi()
• racine carrée : sqrt(x)
• logarithme : log(x) pour le logarithme népérien ou log(x,base)
• exponentiel : exp(x)

Possibilité d'utiliser les fonctionnalités avancées suivantes : casting en entier (int) ou en nombre flottant (float), comparaison avec la valeur null ou les valeurs booléennes true et false.

Variables disponibles :

• {cart.weight}: poids des marchandises
• {cart.weight.for-charge}: poids des marchandises dont la livraison n'est pas offerte (par les règles de prix panier de Magento)
• {cart.quantity}: nombre d'articles dans le panier
• {cart.coupon}: coupon de réduction (chaîne de caractère)
• Prix :
  • {cart.price_excluding_tax}: prix HT (équivaut à {cart.price-tax+discount})
  • {cart.price_including_tax}: prix TTC (équivaut à {cart.price+tax+discount})
  • {cart.price-tax+discount} : prix HT après remise
  • {cart.price-tax-discount} : prix HT avant remise
  • {cart.price+tax+discount} : prix TTC après remise
  • {cart.price+tax-discount}: prix TTC avant remise
• 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
• Destination :
  • {destination.country.code}: code du pays de destination
  • {destination.country.name}: nom du pays de destination
  • {destination.region.code}: code de la région de destination
  • {destination.postcode}: code postal de destination
• Origine (idem destination) : {origin.country.code}, {origin.country.name}, {origin.region.code}, {origin.postcode}
• {free_shipping}: frais de port offert (par une règle dans Magento) [true/false]
• Autres variables en vrac : {cart.weight.unit}, {customer.group.id}, {customer.group.code}, {store.id}, {store.code}, {store.name}, {store.address}, {store.phone}

Vous avez la possibilité de mettre des espaces et des retours à la ligne dans les formules (pour aérer).

Vous pouvez également utiliser des fonctionnalités avancées telles que les tables de tarifs, la copie d'une propriété d'une autre méthode, les fonctions spéciales, l'utilisation des attributs et des options des produits ou encore l'utilisation des variables personnalisées.

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 {{ }}.

Utilisation des tables de tarifs

Dans une table, on peut inclure ou exclure une valeur limite avec les caractères '[' et ']' :

Dans une table, on doit spécifier la valeur de référence. Pour cela, on peut utiliser une des variables disponibles.
Vous pouvez aussi utiliser une formule afin de définir une autre variable de référence.

Utilisation des "switch" (tables de correspondances)

Dans un switch, on doit spécifier la valeur de référence. Pour cela, on peut utiliser une des variables disponibles.
Vous pouvez aussi utiliser une formule afin de définir une autre variable de référence.

Faire une copie d'une propriété d'une autre méthode

Il est possible de faire une copie d'une propriété dans une autre à l'aide de la syntaxe ci-dessous.

Vous pouvez utiliser cette technique dans les propriétés 'conditions', 'fees', 'enabled', 'label', 'description', 'destination', 'origin', 'customer_groups' et 'tracking_url' mais pas dans la propriété 'code'.

Fonctions spéciales dans les formules

Vous pouvez utiliser dans les formules des fonctions spéciales.

Liste des fonctions spéciales :

• min(x,y) : calcule le minimum entre plusieurs valeurs (éventuellement plus de deux valeurs). Si l'une des valeurs est nulle, elle est ignorée.
• max(x,y) : calcule le maximum entre plusieurs valeurs (éventuellement plus de deux valeurs). Si l'une des valeurs est nulle, elle est ignorée.
• substr(string, start, length) : retourne un segment de chaîne de caractères.
• in_array(value, array(value1, value2)) : indique si une valeur appartient à un tableau.

* Concernant l'échappement des chaînes de caractères, se référer à l'inititation aux formules.

Utilisation des attributs ou des options des produits

Il est possible d'utiliser les attributs ou les options des produits à l'aide de la syntaxe ci-dessous.

Pour utiliser les catégories des produits dans les conditions, voir la rubrique explicative.

Vous pouvez utiliser cette technique dans les propriétés 'conditions' et 'fees'.

Liste des préfixes possibles :

• count : nombre (toujours suivi de 'products')
• count distinct : nombre distinct (toujours suivi d'une propriété)
• sum : somme (toujours suivi d'une propriété)
• min : minimum (toujours suivi d'une propriété)
• max : maximum (toujours suivi d'une propriété)

Liste des propriétés possibles :

• product.quantity : quantité de l'article dans le panier
• product.category : nom de la première catégorie du produit
• product.category.id : id de la première catégorie du produit
• product.attribute_set : nom du jeu d'attributs
• product.attribute_set.id : id du jeu d'attributs
• product.attribute.* : attribut
  Liste d'attributs intéressants :
  • sku : la référence
  • name : le nom
  • weight : le poids
  • price : le prix (tel qu'il a été saisi sur la fiche du produit)
  • special_price : le prix promotionnel (tel qu'il a été saisi sur la fiche du produit)
  Quelques pseudos-attributs sont également disponibles pour faciliter certains calculs :
  • price-tax+discount : le prix HT avec remise
  • price-tax-discount : le prix HT sans remise
  • price+tax+discount : le prix TTC avec remise
  • price+tax-discount : le prix TTC sans remise
• product.option.* : option
• product.stock.is_in_stock : disponibilité du produit
• product.stock.quantity : stock du produit

Il est possible de spécifier des conditions que doivent remplir les produits pour être pris en compte. Pour cela, il suffit d'ajouter where suivi d'une formule.

Si la propriété est de type Oui/Non, vous devez utiliser les valeurs true/false ou 1/0 sans les guillemets.

Si la propriété est de type Liste de sélection et que vous souhaitez faire une comparaison avec l'id plutôt qu'avec la valeur, vous devez utiliser la syntaxe suivante :

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.

Pour utiliser les catégories des produits comme itération ou à l'intérieur des boucles foreach, voir la rubrique explicative.

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

• {selection.weight}: poids de la sélection
• {selection.quantity}: nombre d'articles dans la sélection

Lorsque la sélection se fait sur le sku, chaque sélection est composée d'un seul article. On peut donc utiliser d'autres variables :

• {product.weight}: poids de l'article sélectionné
• {product.quantity}: quantité de l'article sélectionné
• {product.category}: nom de la première catégorie du produit
• {product.category.id}: id de la première catégorie du produit
• {product.attribute_set}: nom du jeu d'attributs
• {product.attribute_set.id}: id du jeu d'attributs
• {product.attribute.*}: attribut de l'article sélectionné
  Quelques pseudos-attributs sont également disponibles pour faciliter certains calculs :
  • price-tax+discount : le prix HT avec remise
  • price-tax-discount : le prix HT sans remise
  • price+tax+discount : le prix TTC avec remise
  • price+tax-discount : le prix TTC sans remise
• {product.option.*}: option de l'article sélectionné

Utilisation des catégories dans les boucles foreach ou dans les fonctions spéciales

Depuis la version 2.4.2, il est possible d'utiliser les catégories des produits dans les formules.

Attention, il est à noter que dans Magento, un produit peut être dans plusieurs catégories. Faites donc particulièrement attention à la façon dont vous utilisez cette propriété.

Voici quelques exemples d'utilisation :

Utilisation des variables personnalisées de Magento (Custom Variables)

Depuis la version 1.4.0.1 de Magento, il est possible de définir des variables personnalisées.

La version 2.2.7 d'Owebia Shipping vous permet d'utiliser ces variables personnalisées grâce à la syntaxe suivante :

Les conditions : `conditions`

La propriété `conditions` se spécifie sous la forme d'une formule (voir l'initiation aux formules) qui doit retourner une valeur booléenne (true ou false).

La destination : `destination`

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 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}\)$/)").

L'activation : `enabled`

Permet d'activer ou de désactiver la méthode de livraison.

La valeur doit être booléenne.

Le code : `code`

C'est l'identifiant de la méthode de livraison.

Il doit être unique. S'il n'est pas unique, il sera modifié.

La description : `description`

Il s'agit de la description de la méthode de livraison.

Le fonctionnement est identique à la propriété label.

L'origine : `origin`

Idem que la destination mais pour filtrer l'origine de livraison.
La syntaxe est identique au filtrage de la destination.

Les groupes client : `customer_groups`

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

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 Owebia 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 Owebia Shipping 2 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 Owebia Shipping 2 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.

Commentaires

Vous pouvez ajouter un commentaire sur la méthode de livraison. Celui-ci ne sera affiché nul part mais vous pouvez y mettre des annotations.

Changelog