Custom Module for Oxid eShop

Oxid eShop, a prominent eCommerce solution widely recognized for its flexibility and modularity, empowers businesses worldwide. It provides an ideal platform for building and managing online stores effortlessly. However, the real beauty of Oxid eShop lies in its extensibility. With the ability to develop custom modules, users can tailor their eCommerce store to their unique requirements, bolstering functionality, and enhancing user experience.

Creating a custom module for Oxid eShop allows you to modify or extend the core functionalities without altering the platform’s basic structure. This is crucial for maintaining the integrity of your online shop while ensuring upgradability for future releases. This article will provide an introduction to creating your own module for the Oxid eShop platform.

Before we delve into the practical steps, it’s essential to understand what a module is in the context of Oxid eShop. A module is essentially a package of PHP, JavaScript, CSS, and template files that add new functionalities or change existing ones in the eShop system. The primary benefit of using modules is that they operate independently from the core system, meaning you can add, edit, or remove them without disrupting the main application.

The process of creating a module for Oxid eShop involves the following steps:

1. 1. Module Directory Creation: The first step in creating a custom module is to make a directory within the modules directory of your Oxid eShop installation. Every Oxid eShop module has a specific directory structure, starting with a root directory named after your module. In our example, this directory will be myModule. This directory houses all the classes, templates, translations, and other files your module will use. Your directory should be organized in a certain way to function correctly. For instance, the Application directory within your module directory will hold all your classes, and a views directory within Application will hold your template files. Let’s consider your company name is ‘myCompany’, and you are creating a module named ‘myModule’. Then, your directory should be source/modules/myCompany/myModule.
   2. Metadata.php: The metadata.php file gives Oxid eShop information about your module. This file has a very specific structure and uses certain keys to inform Oxid eShop about your module’s functionality.
      Understanding these keys is crucial:
      • id : the unique identifier of your module. It should be the same as your module directory name.
      • title : the name of your module as it will appear in the admin interface.
      • description : a short description of what your module does.
      • settings : This key allows you to add settings to the Oxid eShop admin interface for your module. These settings can then be used in your module’s code. Each setting is an associative array that specifies a group, a name, a type, and a default value.
      • blocks : This key is used to add new blocks to Oxid eShop’s Smarty templates. Each block is an associative array that specifies a template file, a block in that template file, and a file in your module that will add content to that block.
      • extend : an array that maps the names of core Oxid eShop classes to the names of your module’s classes that extend them.

      Here is an example of a basic metadata.php file:

      <?php

      $sMetadataVersion = '1.1';

      $aModule = array(

      'id'           => 'myModule',

      'title'        => 'My Module',

      'description'  => 'This module does amazing things!',

      'extend'       => array(

      'oxarticle' => 'myCompany/myModule/application/models/myModuleOxarticle',

      ),

      );

   3. Class Creation: Your module will contain one or more PHP classes that extend Oxid’s classes. When creating these classes, you need to follow Oxid’s conventions. First, your class files should be located in the Application directory within your module’s directory. Second, your class names should follow the format Vendor_ModuleName_ClassName. Lastly, your classes should always extend the class they are modifying in Oxid eShop.
      Here is a basic example of such a class:

      class myModuleOxarticle extends myModuleOxarticle_parent {
// Override the getTitle method in oxarticle
public function getTitle() {
return parent::getTitle() . ' (Modified by my module!)';
}
}

   4. Template Files: If your module affects the shop’s frontend, you will likely need to create Smarty template files (.tpl filesin the views directory within your module’s directory. Each file should correspond to a different view your module provides. In your metadata.php file, you should then use the templates key to tell Oxid eShop where to find your templates.You can override existing templates or create new ones.
   5. Blocks and Settings: As mentioned above, blocks and settings are defined in your metadata.php file. Blocks allow you to insert HTML and Smarty code into existing templates. Settings, on the other hand, allow you to add configuration options for your module in the admin interface.
      Here is how you could define a block and a setting:

      <?php
$sMetadataVersion = '1.1';
$aModule = array(
// ...
'blocks' => array(
array('template' => 'page/details/inc/productmain.tpl', 'block' => 'details_productmain_shortdesc', 'file' => '/application/views/blocks/myBlock.tpl'),
),
'settings' => array(
array('group' => 'main', 'name' => 'sMySetting', 'type' => 'str', 'value' => ''),
),
);

   6. Language Files: If you want your module to be multilingual, you can create language files in your module. These files should be placed in a ‘translations’ directory within your module’s directory. The names of these files should be the respective ISO language abbreviations, for example, ‘en’ for English.
   7. Installation and Activation: After creating your module, you can install it in your Oxid eShop via the admin panel. You have to navigate to Extensions > Modules. Your new module should appear in the list. After installation, you have to activate the module.
   8. Testing : Thorough testing is essential to ensure that your module works correctly and does not interfere with the other parts of your eShop system. Be sure to test in different environments (development, staging, production) and cover as many different use cases as possible.

Building a custom module for Oxid eShop might seem daunting initially, but once you grasp the basic structure and components, it becomes an empowering tool to tailor your online store to your specific needs.