Creating LiteCommerce module
First of all, you need to choose unique identifiers for you (your company) and your module. Identifiers may contain maximum 64 letters/digits and must have an uppercase first character. It makes sense to make identifiers of your company name and the name of the module you are going to develop.
Note: The "CDev" developer identifier is reserved for modules created and maintained by the LiteCommerce team.
Although in your module you can use an identifier some other developer uses for his module, we do not recommend doing so because that may confuse LiteCommerce users, installed both the modules. Moreover, if you decide to list the module in our Module Marketplace, it is likely that we will ask you to rename it.
Also, if it is a translation or a theme module, it would be a good idea to name it like "<Language>Translation" and "<Name>Theme".
Further in the tutorial, the "module name" may mean (depending on the context) either a display module name (the one that LiteCommerce users see in the back-end), a module identifier or a full module identifier, including the developer identifier, as: "<Developer>/<Module>".
When a module is installed, it has the following structure (paths are relative to the directory where LiteCommerce is installed; "language" is an ISO 639-1 language code):
classes/XLite/Module/<Developer>/<Module>/Main.php - module descriptor class
classes/XLite/Module/<Developer>/<Module>/icon.png - optional module icon (can be .png, .jpg or .gif)
classes/XLite/Module/<Developer>/<Module>/install.yaml - data to be imported into the database when the module is enabled
classes/XLite/Module/<Developer>/<Module>/Controller/... - new or modified controller classes
classes/XLite/Module/<Developer>/<Module>/View/... - new or modified view classes
classes/XLite/Module/<Developer>/<Module>/... - other classes added or modified by the module
skins/admin/<language>/modules/<Developer>/<Module>/... - new and custom back-end templates/resources
skins/default/<language>/modules/<Developer>/<Module>/... - new and custom store-front templates/resources
The module descriptor class provides LiteCommerce with basic information on the module.
Note: Although a disabled module doesn’t affect LiteCommerce functionality, design and database, a broken descriptor class can make it impossible to access pages generated by LiteCommerce.
The descriptor class defines module version, made of 3 numbers; for example, "1.1.4". The first two numbers are the "major version" of the module that determines what LiteCommerce version the module is written for (1.1.x). The last number is the "minor version" of the module that indicates how many revisions of the module have been released till this one (4). A module shouldn’t define the full module version directly; instead, it should define the major and the minor versions.
On installing updates with the built-in automatic upgrade function, LiteCommerce follows this convention: it assumes that the most recent module revision is always compatible with the most recent LiteCommerce revision of the same major version, but may not work with earlier LiteCommerce revisions of that major version and is incompatible with other major LiteCommerce versions. That’s why the automatic upgrade function always installs all available updates and never updates one module only when updates for the other modules are available. What you should remember is that it is the module author’s responsibility to keep the module compatible with newer LiteCommerce revisions (and LiteCommerce modules the module depends on) and release newer module revisions when needed.
Here is an example of the Main.php script:
<?php
// vim: set ts=4 sw=4 sts=4 et:
/**
* <Your license notice>
*
* @category LiteCommerce
* @author <Your name and contact e-mail>
* @copyright <Your copyright notice>
* @license <URL and your license>
* @version <File version in your version control system>
*/
namespace XLite\Module\<Developer>\<Module>;
/**
* <Brief information on what the module does>.
*/
abstract class Main extends \XLite\Module\AModule
{
/**
* Return the developer name (company name).
*
* @return string
*/
public static function getAuthorName()
{
return '<Your name or your company name>';
}
/**
* Return the module display name.
*
* @return string
*/
public static function getModuleName()
{
return '<Module display name>';
}
/**
* Return the major module version.
*
* You must declare this method otherwise your module will
* be disabled with the next run of the upgrade function.
*
* @return string
*/
public static function getMajorVersion()
{
return '<Major module version>';
}
/**
* Return the minor module version (revision number).
*
* @return string
*/
public static function getMinorVersion()
{
return '<Module revision number>';
}
/**
* Return an URL to the module icon.
* If an empty string is returned "icon.png" from the module directory will be used.
*
* @return string
*/
public static function getIconURL()
{
return '<URL to your module icon>';
}
/**
* Return a brief module description.
*
* @return string
*/
public static function getDescription()
{
return '<Brief module description>';
}
/**
* Return a list of modules the module depends on.
* Each item should be a full module identifier: "<Developer>\<Module>".
*
* @return array
*/
public static function getDependencies()
{
return array();
}
}
-
Define the settings in the module install.yaml file
XLite\Model\Config: - name: <machine name of the first setting> category: <Developer>\<Module> type: <type: select, text> orderby: <position among other settings> value: <default value> translations: - code: en option_name: <description in English> - code: <another language code> option_name: <description in another language> - name: <machine name of the second setting> category: <Developer>\<Module> type: <type: select, text> orderby: <position among other settings> value: <default value> translations: - code: en option_name: <description in English> -
Enable the settings form by adding the following method to the module descriptor file (Main.php):
/** * Determines whether the module has a settings form, or not. * * @return boolean */ public static function showSettingsForm() { return true; }
If your module will require a custom table, you will need to declare the name and structure of this table in a file within your module's "Model" sub-folder:
classes/XLite/Module/<Developer>/<Module>/Model/<TableDeclaration>
The following is a very simple code snippet to create a sample table called "xlite_test_mod" with a primary key integer "id" and a 1-letter character "letter." It is located in a file called "Test.php":
namespace XLite\Module\<Developer>\<Module>\Model;
/**
* Test Module
*
* @see ____class_see____
* @since 1.0.0
*
* @Entity
* @Table (name="test_mod")
*/
class Test extends \XLite\Model\AEntity
{
/**
* Unique id
*
* @var integer
* @see ____var_see____
* @since 1.0.0
*
* @Id
* @GeneratedValue (strategy="AUTO")
* @Column (type="integer")
*/
protected $id;
/**
* A sample letter
*
* @var char
* @see ____var_see____
* @since 1.0.0
*
* @Column (type="fixedstring", length="1")
*/
protected $letter = 'A';
}
To enable your module the first time:
-
Get into the LiteCommerce backend and select the "Maintenance" -> "Re-build cache" item on the top menu. LiteCommerce will look through new files and will list your module among other modules on the "Manage add-ons" page ("Add-ons" menu tab).
-
If you module doesn't have the "install.yaml" file you can just enable it there and start customizing LiteCommerce. Otherwise, to get data from the file imported into the database, create a module package (see the section below) and install it by clicking the "Upload add-on" button.
When you have made any changes to a module, you should rebuild LiteCommerce cache in order to let LiteCommerce see the changes. Get into the LiteCommerce back-end and select the "Maintenance" -> "Re-build cache" item on the top menu.
If there were any changes to the "install.yaml" file, you should uninstall the module (that will delete all data associated with the module) and re-install it once again as explained above.
To create a module package:
-
Enable the "developer_mode" option in your LC3 installation.
Instead of editing "config.php" you can create new "config.local.php" and put there the "developer_mode" option only:
[performance] developer_mode = On -
Get into the shop backend, find your module on the "Manage add-ons" page ("Add-ons" menu tab) and click "Pack it" button next to it. That will create a module package from the module files on your server.
To install the package click "Upload add-on" button on the "Manage add-ons" page ("Add-ons" menu tab in the shop backend) and upload the package. That will install the module and import data from your "install.yaml" file.
See this wiki article.
See this wiki article.