Inital commit

local/modules/BestSellers/Readme.md

@@ -0,0 +1,164 @@
+# Best Sellers
+
+# en_US
+
+This modules provides a loop which return the best (or the worst) sales.
+
+## Installation
+
+Manually, or with composer :
+
+```
+composer require cqfdev/best-sellers-module:~1.0
+```
+
+## Usage
+
+This module shows the 4 best sales of your shop on the front page via the `home.body` hook.
+
+You can also add where you want in your template (front or back-office), a loop `best_selling_products` to show your best or your worst sales. 
+
+In the back-office, you can see your best sales in the "Tools" menu.
+
+Finally, the total number of sales of a product appears on the product sheet. 
+
+## Hook
+
+This module shows the 4 best sales of your shop on the front page via the `home.body` hook.
+
+## Loop
+
+The module provide the loop `best_selling_product`, which extend the loop `product`. All the arguments of the `product` loop are therefore available.
+
+`best_selling_products` loop
+
+### Input parameters
+
+All the arguments of the loop `product` are available.
+
+The loop offers two new values for the parameter `order` of the loop `product``
+- sold_count_reverse : sort by number of sales in decreasing order
+- sold_count : sort by number of sales in increasing order
+
+|Argument |Description |
+|---      |--- |
+|**start-date** | The period start date to be consider. By default, january 1st 1970. |
+|**end-date** | The period end date to be consider. By default, today's date. |
+
+### Output variables
+
+All the variables of the loop `product`are available. 
+
+|Variable   |Description |
+|---        |--- |
+|$SOLD_QUANTITY | The quantity of sold product on the considered period |
+|$SOLD_AMOUNT | The total amount untaxed of sales on the considered period |
+|$SALE_RATIO | The percentage of sales on the considered period |
+
+### Example
+
+To get your 10 best sales of all time:
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers" limit=10 order='sold_count_reverse'}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}²²
+    </ul>
+
+To get your 5 best sales of the month :
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers-this-month" order='sold_count_reverse' start_date={$smarty.now|date_format:'%Y-%m-01'} limit=5}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}
+    </ul>
+
+To get your 10 worst sales of all time :     
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers" limit=10 order='sold_count'}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}
+    </ul>
+
+
+# fr_FR
+
+Ce module vous fournit une boucle qui retourne vos meilleures (ou vos pires) ventes.
+
+## Installation
+
+Manuellement, ou avec composer :
+
+```
+composer require cqfdev/best-sellers-module:~1.0
+```
+
+## Usage
+
+Ce module affiche les 4 meilleures ventes de votre boutique sur la page d'accueil, via le hook 'home.body'
+
+Vous pouvez aussi ajouter où vous voulez dans votre template front office ou back-office une boucle `best_selling_products` pour afficher vos meilleures ou pires ventes.
+
+Dans le back-office, vous pouvez voir vos meilleures ventes dans le menu "Outil".
+
+Enfin, le nombre de ventes total d'un produit apparaît sur la fiche produit.
+ 
+## Hook
+
+Le module affiche les 4 meilleures ventes de votre boutique sur la page d'accueil, via le hook `home.body`
+
+## Loop
+
+Le module vous propose la boucle `best_selling_products`, qui étend la boucle `product`. Tous les arguments de la boucle `product` sont donc disponibles.
+
+`best_selling_products` loop
+
+### Paramètres en entrée
+
+Tous les arguments de la boucle `product` sont disponibles.
+
+La boucle propose deux valeurs supplémentaires pour le paramètre `order` de la boucle `product`:
+- sold_count_reverse : trier par nombre de ventes décroissantes
+- sold_count : trier par nombre de ventes croissantes
+
+|Argument |Description |
+|---      |--- |
+|**start-date** | la date de début de période à prendre en compte. Par défaut, le 1er janvier 1970. |
+|**end-date** | la date de fin de période à prendre en compte. Par défaut, la date du jour. |
+
+### Variables en sortie
+
+Toutes les variables de la boucle `product` sont disponibles.
+
+|Variable   |Description |
+|---        |--- |
+|$SOLD_QUANTITY | La quantité de produit vendue sur la période considérée |
+|$SOLD_AMOUNT | Le montant total HT des ventes sur la période considérée |
+|$SALE_RATIO | Le pourcentage du CA sur la période considérée |
+
+### Exemple
+
+Pour obtenir vos 10 meilleures ventes de tous les temps :
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers" limit=10 order='sold_count_reverse'}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}
+    </ul>
+
+Pour obtenir les 5 meilleures ventes du mois :
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers-this-month" order='sold_count_reverse' start_date={$smarty.now|date_format:'%Y-%m-01'} limit=5}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}
+    </ul>
+    
+Pour obtenir vos 10 pires ventes de tous les temps :
+
+    <ul>
+        {loop type="best_selling_products" name="best-sellers" limit=10 order='sold_count'}
+            <li>{$REF} : {$TITLE} : {$SOLD_QUANTITY}</li>
+        {/loop}
+    </ul>