Creating Extension from Scratch

Intro

Extension is the tool that allows to deploy not only the minor basic function modifications, but also create the independent extensions based on the system. In this lecture we will review all the extension elements in detail and deploy them in our first extension on practice. We recommend to get familiarized with this whole article. Even without having the great knowledge of the system you will be able to create your own extension sooner or later. But following the general principles will allow the majority of developers to understand your code quickly and easily.

First look

Conceptually extension is the system mini copy. By engaging all its means you will be able to create the frontend analogue easily or create the report for backend, based on the data analysis.  

Image 1

On the image 1 (above) you can see the general architecture scheme of the extension constituent parts. For easy perception all the parts are divided into 4 categories.

The founding elements are indicated as the Basic functionality. This is the minimum set that we will require to perform the simplest manipulations within the system.

First of all, the functions are the static methods, realized in the main extension class or the traits if your extension allows it. Usually, the methods are not intended for querying directly, but, if necessary, backend allows to do it via the special controller extensions?module=YourExtensionName&action=adminAction. For frontend such approach is considered to be unsafe and is unavailable.

The next founding element is the hooks. These are the access points, allowing to execute your code in different places. Hooks can be as both the php file and the tpl template. As a rule, the similar files are placed in the subdirectory hooks and are described in the static method getAdminHooks in the main class or in the installing class which we will review later. You can always find the list of the available hooks within the system by checking the file /lib/common/extensions/methodology.txt And the final element of the first extension part is render. This is the template class processor. We did not make it general to provide with enough freedom for realizing within extension. It is worth mentioning that usually this class Render is located in the root extension folder. In this case the template files should be placed in the directory view on the same level.

Image 2

On practice all the three elements organize the chain of the sequential actions as on the image 2.

First step

We suggest you to realize the following idea: the additional field on the customer editing page for backend. To make it simple let it be the text field. An administrator will be able to fill in a word for defining a customer, for example a rank. It is enough for us at the moment.

Thus, let us start working on this task. We assume that our new field will be called Rank. The whole task comes down to adding some classification of these ranks, let us call our extension Customers rank.

After reviewing the system architecture you should be familiar with the start point for any extension. This is the folder /lib/common/extensions/ where all the extensions regardless of their purpose are located. Let us define the place for our new extension and create the new folder. It should be taken into account that the words beginning with the capital letter and without spaces in the title, so called CamelCase. Then we create the folder CustomersRank. Within this folder we create the file CustomersRank.php which content will look in the following way:

<?php

namespace common\extensions\CustomersRank;

class CustomersRank extends \common\classes\modules\ModuleExtensions {

}

It is important to remember that the folder title, the main file title and the class title will always be the same, the letter case should always be taken into account. In our file namespace indicates the extension location, that is the path to the folder in fact. Also it is necessary to pay attention to the parent class that we inherit. For all the extensions it will be the same and will have the set of ready-made instructions for working with extension. On practice, it means that at this stage your extension is ready for installation already and you will be able to see it in the list of the uninstalled extensions:

Image 3

You can install extension and switch it on. But since we did not want our extension to do we get the corresponding result. Let us add some more content to our main file. In order to do it we will need the elements from the section basic functionality. First of all, functions. It is the usual static method located in the main class. We indeed start from this element since its performance can be checked directly via controller, despite that in the future query will be managed by the second element from our set - hooks. Let us add render function of the additional customer field to our class:

    public static function renderCustomerField() 
    {
        return 'I want render new field';
    }

Now in order to see the returned text let us use the direct query from the controller backend:

extensions?module=CustomersRank&action=renderCustomerField Depending on if you switch extension on or off the result will differ:

You have not rights for this extension: CustomersRank

or

I want render new field

It is important to remember that such method is not safe and is available for the admin area only. It should always be taken into account and perform the necessary checks within function. The next step as it was promised will be the connection of extension to the customer editing page. The list of the possible values can be seen in the file lib/common/extensions/methodology.txt in the corresponding section Hooks. Let us see into what kind of list it is and how to understand what place should be exactly used. Open any customer editing page in backend and pay attention to page url

admin/customers/customeredit?customers_id=XXX

And now let us pay attention to the query list. The one that interests us will be similar to the page url. Let us select the ones that meet our requirement:

'customers/customeredit', ''
'customers/customeredit/before-render', ''
'customers/customeredit', 'personal-block'
'customers/customeredit', 'left-column'
'customers/customeredit', 'right-column'