Date de publication: le mercredi 23 novembre 2011 à 14h47
Dernière modification: par Pascal BOYER le mercredi 23 novembre 2011 à 18h58

13/09/2010 3:57

Versions 4.x

eZ Publish 3.8 makes it possible to define custom shipping options for your webshop (e.g. the cost of shipping may depend on the product properties). This could be done by implementing a shipping handler i.e. PHP class providing a mechanism that keeps shipping information for a product collection (basket or order) and calculates the cost of shipping for it. eZ Publish does not include any built-in shipping handlers so you will need to extend the system by creating your own shipping handler in order to add shipping options for your webshop. Using two or more shipping handlers at the same time is not supported (within one siteaccess). The shipping handler to use must be specified in the "Handler" INI setting described in the "INI settings" subsection.
eZ Publish 3.8 permet de définir des options d'envoi personnalisées pour votre commerce en ligne (e.g: le coût des frais de port peut dépendre des caractéristiques des produits). Cette fonctionnalité est mise en œuvre grâce à l'implémentation d'un gestionnaire d'envoi, c'est à dire par le biais d'une classe PHP fournissant un mécanisme qui conserve les informations de frais de port de produits choisis/sélectionnés (panier ou commande) puis qui calcule le coût de leur envoi. eZ Publish n’intégrant aucun gestionnaire d'envoi par défaut, vous devrez créer le votre afin de proposer cette option sur votre boutique en ligne. L'utilisation simultanée de deux gestionnaires ou plus n'est pas supportée (pour un seul siteaccess). Quant au gestionnaire à utiliser, il sera défini par le paramètre Handler décrit au paragraphe Paramètres INI .

When a user is viewing a product page, no shipping cost will be displayed and included into product price. After adding some products to the basket the system will calculate their shipping cost that will be shown under the list of items and included into order total. A shipping handler returns not only shipping cost but also shipping options summary and a link to the shipping management interface where shipping options can be modified. This information will be displayed in the basket together with the shipping cost. The system will also show shipping cost and shipping options summary when asking a user to confirm his/her order and in the order view interface for site administrators.
Lorsqu'un utilisateur parcourt une page produits, aucun frais de port n'est affiché ni inclus au prix des produits. Quelques produits étant ajoutés au panier, le système calcule alors leur coût d'envoi puis l'affiche sous la listes des produits et l'inclut au coût total de la commande. Un gestionnaire d'envoi ne retourne pas seulement le coût des frais de port mais également un résumé des options d'expédition ainsi qu'un lien vers l'interface de gestion des frais de port où ils pourront être modifiés. Ces informations seront affichées dans le panier en même temps que les frais de port. Les frais d'expédition et le résumé des options d'envoi seront aussi affichés par le système d'une part, lorsque ce dernier demandera à l'utilisateur confirmation de son ordre d'achat et, d'autre part, dans l'interface d'administration des commandes côté interface d'administration du site.

INI settings / Paramètres INI

The "[ShippingSettings]" section of the "settings/shop.ini" configuration file defines the shipping handler that will be used for calculating the cost of shipping for your products. Under this section, the following settings can be specified:
La section [ShippingSettings] du fichier de configuration settings/shop.ini définit le gestionnaire d'envoi qui sera utilisé pour calculer le coût des frais d’expédition de vos produits. Sous cette section, les paramètres suivants peuvent être spécifiés:

• The "Handler" setting specifies the shipping handler that will be used.
  Le paramètre Handler définit le gestionnaire à utiliser

• The "RepositoryDirectories[]" array specifies the directories where eZ publish will search for built-in shipping handlers.
  Le tableau RepositoryDirectories[] définit les répertoires où eZ Publish recherchera les gestionnaires d'envoi intégrés

• The "ExtensionDirectories[]" array specifies the extension directories where eZ publish will search for additional shipping handlers. By default eZ publish will search in the "shippinghandlers" subdirectory inside your extension.
  Le tableau ExtensionDirectories[] définit les répertoires où eZ Publish recherchera des gestionnaires d'envoi supplémentaires. Par défaut, cette recherche s'effectuera dans le sous-répertoire shippinghandlers de votre extension.

Exemple 1

The following lines can be specified under the "[ShippingSettings]" section of the "shop.ini" configuration file:
Les lignes ci-dessous peuvent être déclarées sous la section [ShippingSettings] du fichier de configuration settings/shop.ini:

[ShippingSettings]
Handler=ezcustom
RepositoryDirectories[]=kernel/classes/shippinghandlers

These settings will instruct eZ Publish to use the shipping handler located at "kernel/classes/shippinghandlers/ezcustomshippinghandler.php".
Ces paramètres informent eZ Publish d'utiliser le gestionnaire d'expédition placé dans le répertoire kernel/classes/shippinghandlers/ezcustomshippinghandler.php.

Exemple 2

If you have an extension "myextension" that includes a shipping handler "mycost", you can put the following lines into an override for the "shop.ini" configuration file:
Si vous disposez d'une extension myextension incluant un gestionnaire d'envoi mycost alors vous pouvez ajouter les lignes suivantes dans une surcharge du fichier de configuration shop.ini:

[ShippingSettings]
Handler=mycost
ExtensionDirectories[]=myextension

ou bien:

[ShippingSettings]
Handler=mycost
RepositoryDirectories[]=extension/myextension/shippinghandlers

These settings will instruct eZ Publish to use the VAT handler located at "extension/myextension/shippinghandlers/mycostshippinghandler.php".
Ces paramètres indiquent à eZ Publish d'utiliser le gestionnaire de TVA (???) situé dans extension/myextension/shippinghandlers/mycostshippinghandler.php.

Creating new shipping handlers / Créer de nouveaux gestionnaires d'expédition

This section reveals some helpful tips for those developers who want to create a new shipping handler (only for people who are familiar with PHP). Please note that it is not recommended to modify the eZ Publish kernel and thus you should implement it as an extension.
Ce paragraphe dévoile quelques conseils utiles aux développeurs qui souhaiteraient créer un nouveau gestionnaire d'envoi (réservé aux personnes familiarisées avec PHP). Veuillez noter que puisqu'il n'est pas recommandé de modifier le noyau d'eZ Publish vous devez implémenter votre gestionnaire en tant qu'extension.

Implementation details / Détails de l'implémentation

A shipping handler is a file that contains a class implementing the following methods:
Un gestionnaire d'envoi n'est rein d'autre qu'un fichier contenant une classe implémentant les méthodes suivantes:

/**
* Invoked to get shipping information for given product collection.
* \public
* \static
*/
function getShippingInfo( $productCollectionID );
 
/*
* Invoked when shopping basket contents is changed
* to update shipping info/cost appropriately.
* \public
* \static
*/
function updateShippingInfo( $productCollectionID );
 
/**
* Invoked when the associated product collection is removed
* to clean up shipping information.
* \public
* \static
*/
function purgeShippingInfo( $productCollectionID );

A handler is called via eZShippingManager class that has the same methods.
Un gestionnaire est appelé via la classe eZShippingManager ayant les mêmes méthodes.

$shippingInfo = eZShippingManager::getShippingInfo( $productCollection );

All that getShippingInfo() method does is invoking getShippingInfo() method of the shipping handler that is specified in the "Handler" INI setting. This method returns shipping information for a given product collection as a hash containing the following elements:
Tout ce que réalise la méthode getShippingInfo() est d'invoquer la méthode getShippingInfo() du gestionnaire déclaré par le paramètre Handler. Cette méthode renvoie, sous la forme d'un tableau (hash) contenant les éléments ci-dessous, des informations sur l'expédition de produits donnés:

The next subsection explains how you can implement your own shipping handler.
Le prochain paragraphe explique comment implémenter votre propre gestionnaire.

Creating your own handler / Créez votre propre gestionnaire

The following text describes the implementation of a trivial shipping handler for demonstration purposes.
Les étapes ci-dessous décrivent, à des fins de démonstration, la procédure d'implémentation d'un gestionnaire d'envoi trivial.

1. Create the following subdirectories in the "extension" directory of your eZ Publish installation:
   Créez les sous-répertoires suivants dans le répertoire extension de votre installation eZ Publish:
   • myextension
   • myextension/settings
   • myextension/shippinghandlers

2. Create a file called "mycostshippinghandler.php" in the "myextension/shippinghandlers/" directory (this file must contain a PHP class called "MyCostShippingHandler") and add the following lines into it:
   Créez un fichier mycostshippinghandler.php dans le répertoire myextension/shippinghandlers/ (ce fichier doit contenir une classe PHP nommée MyCostShippingHandler) et ajoutez-y les lignes suivantes:

   <?php
   class MyCostShippingHandler
   {
       function getShippingInfo( $productCollectionID )
       {
           return array(
           'description' => 'Manual',
           'cost' => 10,
           'management_link' => '/shop/basket/' // dummy
           );
       }
       function purgeShippingInfo( $productCollectionID )
       {
           // nothing to purge
       }
       function updateShippingInfo( $productCollectionID )
       {
           // nothing to update
       }
   }
   ?>

3. Create a file called "shop.ini.append.php" in the "myextension/settings" directory and add the following lines into it:
   Créez un fichier shop.ini.append.php dans le répertoire myextension/settings/ est ajoutez-y les lignes suivantes:

   [ShippingSettings]
   Handler=mycost
   ExtensionDirectories[]=myextension

4. To activate your extension in eZ Publish, log in to your eZ Publish administration interface, click on the "Setup" tab, and then click "Extensions" on the left. You will see the list of available extensions. Select the "myextension" item and click the "Apply changes" button.
   Pour activer votre extension dans eZ Publish, connectez-vous à l'interface d'administration, cliquez sur l'onglet Administration puis sur le lien Extensions dans le menu de gauche. Dans la liste des extensions disponibles qui s'affiche alors, sélectionnez la votre, myextension, et cliquez sur le bouton Appliquer les changements.

This will make the system add the fixed cost of shipping to any set of products being purchased from your site.
Cela aura pour effet que le système ajoute le coût d'expédition à tous les produits achetés sur votre site.

If you need more complicated shipping options, you can try to use the advanced example from http://ez.no/community/contribs/examples/sample_shipping_handler or develop your own shipping handler.
Si vous souhaitez des options d'expédition plus complexes, vous pouvez essayer d'utiliser l'exemple proposé par cette page http://projects.ez.no/sample_shipping_handler ou bien développer votre propre gestionnaire.

Commentaires