• Register
Plug-in Tutorial Build an EC-CUBE plug-in

Top Commentators

114

1

EC Mike

SHOGUNSHOGUN

32

2

hrbabu

SAMURAISAMURAI

29

3

Sumant Jha

SAMURAISAMURAI

29

4

justcubed

SAMURAISAMURAI

21

5

Ashok Kafle

SAMURAISAMURAI

21

6

shahith

SAMURAISAMURAI

14

7

Jeemusu

KABUKIKABUKI

14

8

Yangsin

KABUKIKABUKI

9

9

Zaw Hlaing Bwar

GEISYAGEISYA

8

10

Fei Liu

GEISYAGEISYA

Ranking Key

  • FUJISANFUJISAN1,000+ posts
  • SAKURASAKURA500+ posts
  • SHOGUNSHOGUN100+ posts
  • NINJYANINJYA50+ posts
  • SAMURAISAMURAI20+ posts
  • KABUKIKABUKI10+ posts
  • GEISYAGEISYALess than 10 posts

Simple plug-in guide in English

Many people have requested a guide on how to make plug-ins for EC-CUBE. Plug-ins are a great way to increase the functionality of your shopping cart. Even if you are not familiar with coding, this article should make it easy to build a plug-in.


In this guide, we will add text to the product details page. We will create a table in the database to store the text string. We will also create an admin settings page to modify the string.


Download source code


1. Create a folder for your project.

a. Create an image file (logo) for the project.

b. Name the image: logo.png with the dimensions: 65x65 pixels.

c. Place it in the directory of your project.

2. Create a file called plugin_info.php.

The contents should be the following:

class plugin_info{
static $PLUGIN_CODE           = "SamplePlugin";
    static $PLUGIN_NAME       = "SamplePlugin";
    static $PLUGIN_VERSION    = "1.1";
    static $COMPLIANT_VERSION = "2.12.3en-p1,2.12.3en-p2";
    static $AUTHOR            = "Your Name";
    static $DESCRIPTION       = "My sample plug-in";
    static $PLUGIN_SITE_URL   = "http://example.com";
    static $AUTHOR_SITE_URL   = "http://example.com";
//The class name is very important. You will write your code in the class you define here.
    static $CLASS_NAME       = "plg_SamplePlugin";  
   //***Add hook points here***
    static $LICENSE        = "LGPL";
}

3. Adding hook points to plugin_info.php.

Hook points allow you to access the dataflow/workflow of EC-CUBE. Think of a hook point as a time based trigger at a certain location in the program. For example, if you want to retrieve data from an input field, you do not want to trigger your code before the page loads, but after someone submits data. If you trigger your code before the page loads, you will not receive any data.


For this lesson, we want to add text near the top of the products detail page before the page renders. In order to accomplish this, place this code in the plugin_info.php.


  	      static $HOOK_POINTS       = array(
	        array("prefilterTransform", 'prefilterTransform'),
	      array("LC_Page_Products_Detail_action_after", 'dataafter'));
We will call the “prefilterTransform” hook point and 
“LC_Page_Products_Detail_action_after”  from our code later.

4. Create a php file with the same name as the class you previously defined in the plugin_info.php.

class plg_SamplePlugin extends SC_Plugin_Base {

 /**
 * Constructor
 */
    public function __construct(array $arrSelfInfo) {
        parent::__construct($arrSelfInfo);
    }

    /**
     * Install
     * Executed when plug-in is installed.
     * Information is automatically written to the table dtb_plugin.
     *
     * @param array $arrPlugin plugin_info - from the dtb_plugin
     * @return void
     */
 function install($arrPlugin) {
copy(PLUGIN_UPLOAD_REALDIR . $arrPlugin['plugin_code'] . "/logo.png", PLUGIN_HTML_REALDIR . $arrPlugin['plugin_code'] . "/logo.png");
    }

    /**
     * Uninstall
     * 
     * Executed when plug-in is uninstalled.
     * @param array $arrPlugin 
     * @return void
     */
 function uninstall($arrPlugin) {
unlink(PLUGIN_HTML_REALDIR . $arrPlugin['plugin_code'] . "/logo.png");
    }

    /**
     * Enable plug-in
     * 
     * When enabled, the plug-in will start.
     *    
     * @param array $arrPlugin
     * @return void
     */
    function enable($arrPlugin) {
        // nop
    }

    /**
     * Disable  plug-in
     * 
     * When disabled, the plug-in will turn off.
     *    
     * @param array $arrPlugin
     * @return void
     */
    function disable($arrPlugin) {
        // nop
    }

The above code will allow the plugin to install and uninstall without any issues.


5. PrefilterTransform

Let’s call the prefilterTransform hook point we defined earlier. We will check if the user has landed on the details page and then we will insert a new template.



/**
     * PrefilterTransform hookpoint
     * 
     * Modifies the template
     *
     * @param string &$source Template html source
     * @param LC_Page_Ex $objPage Page object
     * @param string $filename Template filename
     * @return void
     */
    function prefilterTransform(&$source, LC_Page_Ex $objPage, $filename) {
        // SC_Helper_Transform
        $objTransform = new SC_Helper_Transform($source);
        switch ($objPage->arrPageLayout['device_type_id']) {
          case DEVICE_TYPE_MOBILE:
            case DEVICE_TYPE_SMARTPHONE:
                break;
            case DEVICE_TYPE_PC: // PC  
                if (strpos($filename, 'products/detail.tpl') !== false) {
                    $template_dir = PLUGIN_UPLOAD_REALDIR . $this->arrSelfInfo['plugin_code'] . '/templates/';
                    $objTransform->select('.normal_price')->insertBefore(file_get_contents($template_dir . 'sample_plugin_add.tpl'));
                }
                break;
            case DEVICE_TYPE_ADMIN:
                break;
            default:
                break;
        }

        $source = $objTransform->getHTML();
    }


6. Create the template “sample_plugin_add.tpl” and place it in the templates folder.

Write the code and save the file. The string doesn’t exist yet, but we will add the logic behind it in the next step.


<!--{$arrForm.sampletext|h}-->

Let’s pretend “arrForm.sampletext” contains the word “test.” If you were to run this plug-in now, “test” would appear on the details page. However if you changed test to something else, it would stay the same. Files are cached by default, so even if you alter a file, the old data will remain on the page. Therefore we need to use the other hook point we defined earlier called: “LC_Page_Products_Detail_action_after.” Remember we named it “dataafter.”


7. LC_Page_Products_Detail_action_after (dataafter)>

   /**
     * LC_Page_Products_Detail_action_after hookpoint
     * 
     * Modifies the template
     * @param LC_Page_Ex $objPage Page object
     * 
     */
function dataafter($objPage) {
        $objPage->arrForm['sampletext'] =””;
    }


Let’s populate “sampletext” from the database. First we will create a table.


8. Modify install/uninstall function to add a table to the database
We will add the table creation process to the install function we created earlier.

   function install($arrPlugin) {
        $objQuery = & SC_Query_Ex::getSingletonInstance();
        $objQuery->query("CREATE TABLE plg_sampleplugin (id INT,sampletext VARCHAR(255),update_date TIMESTAMP)");
        $arrModule = array();
        $arrModule['id'] = 1;
        $arrModule['sampletext'] = "Test";
        $arrModule['update_date'] = 'CURRENT_TIMESTAMP';
        $objQuery->insert('plg_sampleplugin', $arrModule);
        copy(PLUGIN_UPLOAD_REALDIR . $arrPlugin['plugin_code'] . "/logo.png", PLUGIN_HTML_REALDIR . $arrPlugin['plugin_code'] . "/logo.png");
    }

Also make sure to add the below code the uninstall function


function uninstall($arrPlugin) {
        $objQuery = & SC_Query_Ex::getSingletonInstance();
        $objQuery->query("DROP TABLE plg_sampleplugin");
        unlink(PLUGIN_HTML_REALDIR . $arrPlugin['plugin_code'] . "/logo.png");
    }

9. Retrieve the data from the newly created table.

Now that the tables are setup, it is possible to retrieve the data from the database.

    /**
     * LC_Page_Products_Detail_action_after hookpoint
     * 
     * Modifies the template
     * @param LC_Page_Ex $objPage Page object
     * 
     */
    function dataafter($objPage) {
        $objPage->arrForm['sampletext'] = $this->getdata();
    }

    /**
     * Select sampletext from table.
     * 
     * @return data 
     * 
     */
    function getdata() {
        $objQuery = & SC_Query_Ex::getSingletonInstance();
        $sql = "SELECT sampletext FROM plg_sampleplugin";
        $data = $objQuery->getOne($sql);
        return $data;
    }

10. Admin settings page


Add a config.php file to the main directory to allow administrators to modify the data in our table from the admin panel.


require_once PLUGIN_UPLOAD_REALDIR .  'SamplePlugin/LC_Page_Plugin_SamplePluginConfig.php';

$objPage = new LC_Page_Plugin_SamplePluginConfig();
register_shutdown_function(array($objPage, 'destroy'));
$objPage->init();
$objPage->process();


11. Populating Admin settings page.

Let’s create the page “LC_Page_Plugin_SamplePluginConfig.php.” In the action function, we will call the database to display data on the page. We also call the function “updateData” to update the database.


require_once CLASS_EX_REALDIR . 'page_extends/admin/LC_Page_Admin_Ex.php';

class LC_Page_Plugin_SamplePluginConfig extends LC_Page_Admin_Ex {

    var $arrForm = array();

    /**
     * Initialize.
     *
     * @return void
     */
    function init() {
        parent::init();
        $this->tpl_mainpage = PLUGIN_UPLOAD_REALDIR . "SamplePlugin/templates/config.tpl";
        $this->tpl_subtitle = "Sample Plug-in config";
    }

    /**
     * Process.
     *
     * @return void
     */
    function process() {
        $this->action();
        $this->sendResponse();
    }

    /**
     * Page action
     *
     * @return void
     */
    function action() {
        $objFormParam = new SC_FormParam_Ex();
        $this->lfInitParam($objFormParam);
        $objFormParam->setParam($_POST);
        $objFormParam->convParam();

        $arrForm = array();
        switch ($this->getMode()) {
            case 'edit':
                $this->arrErr = $this->lfCheckError($objFormParam);
                $arrForm = $objFormParam->getHashArray();

                //If there are no errors, update the table.
                if (SC_Utils_Ex::isBlank($this->arrErr)) {
                    $this->updateData($arrForm);
                    $this->tpl_onload .= 'window.close();';
                }
                break;
            default:
                $arrForm['sampletext'] = $this->getdata();
                break;
        }
        $this->arrForm = $arrForm;
        $this->setTemplate($this->tpl_mainpage);
    }

    /**
     * Destructor.
     *
     * @return void
     */
    function destroy() {
        parent::destroy();
    }

    /**
     * Paramater info initialization 
     *
     * @param object $objFormParam SC_FormParam instance
     * @return void
     */
    function lfInitParam(&$objFormParam) {
        $objFormParam->addParam('Sampletext', 'sampletext', STEXT_LEN, ``, array('MAX_LENGTH_CHECK'));
    }

    /**
     * Check for errors of inputed data
     * @param Object $objFormParam
     * @return Array error 
     */
    function lfCheckError(&$objFormParam) {
        $objErr = new SC_CheckError_Ex();
        $objErr->arrErr = $objFormParam->checkError();
        return $objErr->arrErr;
    }

    /**
     * Select sampletext from table
     * 
     * @return data 
     */
    function getdata() {
        $objQuery = & SC_Query_Ex::getSingletonInstance();
        $sql = "SELECT sampletext FROM plg_sampleplugin";
        $data = $objQuery->getOne($sql);
        return $data;
    }

    /**
     * Update sampletext and update_date in table
     * 
     * @param Array $arrData
     */
    function updateData($arrData) {
        $objQuery = & SC_Query_Ex::getSingletonInstance();
        $sqlval = array();
        $sqlval['sampletext'] = $arrData['sampletext'];
        $sqlval['update_date'] = 'CURRENT_TIMESTAMP';
        $objQuery->update('plg_sampleplugin', $sqlval);
    }

}


12. Display data on settings page

Next create a simple form page to display the data.


Create the file: config.tpl and add it to the templates folder.


<!--{include file="`$smarty.const.TEMPLATE_ADMIN_REALDIR`admin_popup_header.tpl"}-->
<script type="text/javascript">
</script>
<h2><!--{$tpl_subtitle}--></h2>
<form name="form1" id="form1" method="post" action="<!--{$smarty.server.REQUEST_URI|h}-->">
<input type="hidden" name="<!--{$smarty.const.TRANSACTION_ID_NAME}-->" value="<!--{$transactionid}-->" />
<input type="hidden" name="mode" value="edit">
<p>Settings<br/>
<br/>
</p>
<table border="0" cellspacing="1" cellpadding="8" summary="Test">
<tr>
<td bgcolor="#f3f3f3">Sample Plug-in product message </td>
<td><!--{$arrErr.sampletext}--> </span>
<input type="text" name="sampletext" value="<!--{$arrForm.sampletext|h}-->" /> <br/>
</td>
</tr>
</table>
<div class="btn-area">
<ul>
<li>
<a class="btn-action" href="javascript:;" onclick="document.form1.submit();return false;"> <span class="btn-next">Save and close </span> </a>
</li>
</ul>
</div>
</form>
<!--{include file="`$smarty.const.TEMPLATE_ADMIN_REALDIR`admin_popup_footer.tpl"}-->

13. Build tar/tar.gz file for installation

The plug-in should now be complete and ready to install.


a. Select all of the files in the main directory of the project and save your project as a tar or tar.gz. DO NOT SELECT THE MAIN DIRECTORY ITSELF.

b. Login to the admin panel, and select “plugin-in management” from the “owner’s store” dropdown. Upload your project. If it uploaded successfully, click activate.

c. Click on “Plug-in Settings” to load the settings page you just created. Enter in: “Sample Plug-in Test” and click “Save and close.”

d. When you view a product, you should see the new text you added.

Not too difficult right? You can download the source code directly from here.

We will add more detailed documentation soon, but for now if you have any questions, be sure to post on our form.

...