Tutorials/Extending Promotions module

Promotions are dedicated to attract customers attention about expired, current and upcoming shop events. Usually it can be used to increase shop sales. Standard version allows to design promotion look and, if needed, setup it for specific user groups.

Tutorial explains how extended standard functionality by creating custom module for the "promotion queue" business case. Tutorial show how to: 1. create promotions products administration; 2. frontend setup for promotions queuing; 3. queue logics implementation.

Administration
To access standard promotions administration area go to "Admin &gt; Customer Info &gt; Promotions". You can modify promotion description, HTML/Smarty code, change images, leading urls and other parameters. "Active" or "Active From/To" fields allows to define expiration status. Additionally its allowed to assign user groups.

In case your business model requires specific promotion relations with other objects e.g. products, you should create your own assignment solution. Example shows how to create AJAX based product assignment popup.

Product assignment
1. You should extend current promotion administration class "admin/actions_main.php" to define your own template and AJAX popup (object assignment) handling logic:

2. Copy and customize standard "out/admin/tpl/actions_main.tpl" template and add object assignment button:  3. Object assignment functionality should be created (e.g. "admin/inc/custpromotions_products.inc.php"):  If you need other type of assignment you can find examples in "admin/inc/". 4. Now you need to create AJAX popup "out/admin/tpl/pupups/custpromotions_products.inc.tpl": In "out/admin/tpl/popups/" folder you can find other assignment popup examples. As now you created all needed components, you may easily assign preferred object by draging them from left to right side.

Front-end
This example does not affect standard promotions module appearance so no special template changes required. In case you want to customize UI please modify related files:

Module logic
"custPromotions_oxActions" class extends oxActions. It adds additional functionality such as: 1. getting next promotion (from the sorted list (queue)); 2. retrieving stock sum of all related products; 3. functionality to stop current promotion and start next one recursively checking the stock. custPromotions_oxActions::getNextAction implements next action object getter by using oxsort database field. custPromotions_oxActions::getArticlesStock retrieves sum of articles stock by using object to promotion (oxobject2action) relation table. custPromotions_oxActions::checkStock method implements logic of the business model:

Firstly, this promotion is checked if it is "running" - only active promotions can be stopped and the next one activated. Then the count of this promotions related articles stock is tested. If the articles are sold out, the promotion is stopped by calling the parent method "stop". If there is a next promotion available, it is started, and the stock checking is performed on it.

custPromotions_oxArticle module class adds the related promotions getter and the promotion stock checking functionlity invoker after saving a product. custPromotions_oxArticle::_getRelatedActions method uses same oxobject2action table for retrieving list of promotions, which have this product assigned. After saving a product, all related promotions are notified, and stock checking functionality is invoked in the method custPromotions_oxArticle::save. For better performance, this functionality is invoked only if the current article stock is 0.

Module installation
1. Module files should be copied to related folders:

2. Open "Admin &gt; Core settings &gt; Settings" and append "Modules" field with:

Note: if the base promotion functionality is used as a module, then custpromotions_oxactions should extend not the oxactions class of OXID eShop, but the class from the base module: