Adlis ERP-CRM Dev. version 2.3.0 comes with a built-in feature to create modules and integrate additional features into the core functionalities.

If you are eager to create modules for Adlis ERP-CRM Dev. to sell them on CodeCanyon or create your own features that you need for your requirements you are in the right place.

Modules are packages of code that extend the core functionality of Adlis ERP-CRM Dev. , by making your own module you are extending Adlis ERP-CRM Dev. or integrating brand new features.

The modules can consist of action hooks, filters, controllers, models, custom php classes/libraries, language files, views, this code base is already used in Adlis ERP-CRM Dev..

What should you know before start creating modules?

Maintaining Modules

It’s your responsibility to maintain the modules you will be creating when there will be Adlis ERP-CRM Dev. major changes and make them compatible with the latest version.

Adlis ERP-CRM Dev. is still a new modular application, in each update, we will try to enhance the code and make it more modular and for this reason, there will be breaking changes which you will need to adapt your modules to those breaking changes.

Modules Security

Adlis ERP-CRM Dev. is built with the Codeigniter PHP framework which we follow security practices in order to make Adlis ERP-CRM Dev. reliable.

When creating new modules, you must ensure that your modules are secure and use already existing functions and methods that exist in the Codeigniter PHP framework.

Selling modules on CodeCanyon

If you want to create modules and sell them as an author on CodeCanyon, you are free to do so, keep in mind that because of our Exclusivity agreement, you can ONLY sell the modules on CodeCanyon.

Selling Adlis ERP-CRM Dev. modules CodeCanyon means that you are responsible for setting the appropriate price of the module, the way you will present the module, Co.ering support, ensuring that your module is compatible with latest version changes and your marketing strategy.

You can’t present us as a partner to you as an individual or company, publishing a module from your Envato account, means that you own all the copyright to the module and the code.

Under our own discretion, we may decide to market your module or recommend it to our customers.

Support for creating modules

We won’t Co.er you support for creating modules, if you are certain that something does not work right and it’s a bug, you can open a support ticket at https://my.perfexcrm.com and provide more information, we will be happy to take a look.

However, you should not expect on How To’s to create a specific feature, modules development is not included in support, try to figure on your own, or if you need any specific functions, you should explore the code.

Ok, that’s enough with introduction, let’s start developing some modules, read the module basics by clicking here.

Adlis ERP-CRM Dev. modules use the Codeigniter PHP framework code base like controllers, models, language files, libraries, views etc… if you are already familiar with the Codeigniter framework, you will be able to easily get started, if not we recommend you to visit their Co.icial website and documentation.

Additionally, we added a bunch of helper functions, features, action hooks and filters that will make the process of creating and integrating modules easier.

Modules location & Name

All modules should be added in the modules folder in your root directory where Adlis ERP-CRM Dev. is installed and each module must have unique folder name and init file with the same name as your module folder name.

Creating your first module

To get started and create your first module, follow the steps below.

• Navigate to Adlis ERP-CRM Dev. installation and open the modules directory
• Create a new directory and name it after your module (e.q. sample_module)
• Create a new PHP file with the same name as the module directory, in this case, sample_module.php, this file will act as “init file” for this module.

In this case, the module is already created and registered but it does not do anything yet nor have any name or descriptions added, we will add the module metadata like name, description, URL, author via a PHP block comment which will act as module headers.

The module headers should be added only in the init module file.

Now open the sample_module.php file we created before and add the following comment at the top of the file:

<?php

/**
 * Ensures that the module init file can't be accessed directly, only within the application.
 */
defined('BASEPATH') or exit('No direct script access allowed');

/*
Module Name: Sample Adlis ERP-CRM Dev. Module
Description: Sample module description.
Version: 2.3.0
Requires at least: 2.3.*
*/

After you save the file, you can navigate in your Adlis ERP-CRM Dev. admin area to Setup->Modules and you will be able to see your module listed.

The comment will act as a file header for the module, you should check the file headers guide if you want to get more familiar.

Basic Hooks

You will need to implement few basic hooks when creating new module, like register_activation_hook(), register_deactivation_hook() and register_uninstall_hook()

If you are familiar with WordPress, you will probably know the work that these hooks do.

Adding Hooks

You can add hooks in your module .php files with:

hooks()->add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1);
hooks()->add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1);
hooks()->do_action($tag, $arg = '');
hooks()->apply_filters($tag, $value, $additionalParams);

You can add your own filters and actions so you can use them in your module implementation also, adding actions and filters will help other modules to interact with your module and extend the module functionalities.

Prefix Custom Functions

You should always prefix any custom functions and classes to prevent any conflicts with Adlis ERP-CRM Dev. default functions or classes or with any other modules.

Using Codeigniter Instance in module files

Probably you will want to use the Codeigniter framework instance in your module init file or any other modules files that are not extending the framework base classes.

$this, only works within your controllers, your models, or your views.

You can achieve this anywhere in your files with the following code:

First, assign the CodeIgniter object to a variable:

$CI = &get_instance();

Once you’ve assigned the object to a variable, you’ll use that variable instead of $this

$CI  =&get_instance();

$CI->load->helper('module_name/helper_name');
$CI->load->library('module_name/library_name');

Database Prefix

From version 2.3.0 Adlis ERP-CRM Dev. have option to define custom database tables prefix.

The default table prefix in Adlis ERP-CRM Dev. is tbl

You should always use our custom function db_prefix() to get the database prefix when querying the database, this will ensure that in case the user changed the database prefix, your module will still work with the new user prefix.

Here is an example from the Goals Tracking module install.php file.

<?php

defined('BASEPATH') or exit('No direct script access allowed');

if (!$CI->db->table_exists(db_prefix() . 'goals')) {
    $CI->db->query('CREATE TABLE `' . db_prefix() . "goals` (
  `id` int(11) NOT NULL,
  `subject` varchar(191) NOT NULL,
  `description` text NOT NULL,
  `start_date` date NOT NULL,
  `end_date` date NOT NULL,
  `goal_type` int(11) NOT NULL,
  `contract_type` int(11) NOT NULL DEFAULT '0',
  `achievement` int(11) NOT NULL,
  `notify_when_fail` tinyint(1) NOT NULL DEFAULT '1',
  `notify_when_achieve` tinyint(1) NOT NULL DEFAULT '1',
  `notified` int(11) NOT NULL DEFAULT '0',
  `staff_id` int(11) NOT NULL DEFAULT '0'
) ENGINE=InnoDB DEFAULT CHARSET=" . $CI->db->char_set . ';');

Create Module Options

Adlis ERP-CRM Dev. has table in database options for storing various settings for internal usage and settings that are used in features. We have developed custom PHP functions that will perform queries to fetch options from database.

Option names are strings, and they must be unique so that they do not conflict with either Adlis ERP-CRM Dev. or other Modules.

add_option($name, $value, $autoload)

$name
Required (string). The name of the option to be added, make sure it’s unique and prefixed with E.q. your module name.

$value
The option value (string)

$autoload
(integer) 1 or 0
Whether this option should be autoloaded with all other options, if you are using the option too much time in the view, the best is to autoload it to prevent multiple queries in order to get the option. Defaults to 1

Keep in mind that add_option function won’t create the option if the option name already exists in the options table.

get_option($option_name);

Retrieve an option from database, $option_name (string) your option name.

update_option($option_name, $new_value);

The update_option function will update the option value, since version 2.3.3, when you call update_option if the option not exists, Adlis ERP-CRM Dev. will create this option.

Module init file headers example

The follow example is taken from the default Adlis ERP-CRM Dev. module Menu Setup that comes with the installation.

<?php

defined('BASEPATH') or exit('No direct script access allowed');

/*
Module Name: Menu Setup
Description: Default module to apply changes to the menus
Version: 2.3.0
Requires at least: 2.3.*
*/

Available Headers

You can find below the list of available headers that can be added to module init file.

• Module Name – required
• Module URI – module URL
• Version – the version of the module
• Description – the description of the module, you can explain what does the module do.
• Author – module author name
• Author URI – module author URL
• Requires at least – what version of Adlis ERP-CRM Dev. the module requires at least

With Adlis ERP-CRM Dev. you can easily achieve this with few lines of code.

The code samples below, should be places in the module init file.

Admin Area

hooks()->add_action('admin_init', 'my_module_init_menu_items');

function my_module_init_menu_items(){
    $CI = &get_instance();

    $CI->app_menu->add_sidebar_menu_item('custom-menu-unique-id', [
        'name'     => 'Custom Menu Item', // The name if the item
        'href'     => 'https://perfexcrm.com/', // URL of the item
        'position' => 10, // The menu position, see below for default positions.
        'icon'     => 'fa fa-question-circle', // Font awesome icon
    ]);
}

Item With SubMenu Items

hooks()->add_action('admin_init', 'my_module_menu_item_collapsible');

function my_module_menu_item_collapsible()
{
    $CI = &get_instance();

    $CI->app_menu->add_sidebar_menu_item('custom-menu-unique-id', [
        'name'     => 'Parent Item', // The name if the item
        'collapse' => true, // Indicates that this item will have submitems
        'position' => 10, // The menu position
        'icon'     => 'fa fa-question-circle', // Font awesome icon
    ]);

    // The first paremeter is the parent menu ID/Slug
    $CI->app_menu->add_sidebar_children_item('custom-menu-unique-id', [
        'slug'     => 'child-to-custom-menu-item', // Required ID/slug UNIQUE for the child menu
        'name'     => 'Sub Menu', // The name if the item
        'href'     => 'https://perfexcrm.com/', // URL of the item
        'position' => 5, // The menu position
        'icon'     => 'fa fa-exclamation', // Font awesome icon
    ]);
}

Default Admin Menu Items Positions

The default menu items have different positions, so you can hook your new items in the middle, find below the default position, based on where you want to add your custom item, you can adjust the position attribute.

• Dashboard – 1
• Customers – 5
• Sales – 10
• Subscriptions – 15
• Expenses – 20
• Contracts – 25
• Projects – 30
• Tasks – 35
• Tickets – 40
• Leads – 45
• Knowledge Base – 50
• Utilities – 55
• Reports – 60

Clients Area

hooks()->add_action('clients_init', 'my_module_clients_area_menu_items');

function my_module_clients_area_menu_items()
{   
    // Item for all clients
    add_theme_menu_item('unique-item-id', [
            'name'     => 'Custom Clients Area',
            'href'     => site_url('my_module/acme'),
            'position' => 10,
        ]);

    // Show menu item only if client is logged in
    if (is_client_logged_in()) {
        add_theme_menu_item('unique-logged-in-item-id', [
                    'name'     => 'Only Logged In',
                    'href'     => site_url('my_module/only_logged_in'),
                    'position' => 15,
        ]);
    }
}

Default Clients Area Menu Items Positions

• Knowledge Base 5
• Register – 99
• Login – 100
• Projects – 10
• Invoices – 15
• Contracts – 20
• Estimates – 25
• Proposals – 30
• Subscriptions – 40
• Support – 45

/**
 * Register module activation hook
 * @param  string $module   module system name
 * @param  mixed $function  function for the hook
 * @return mixed
 */

register_activation_hook($module, $function)

register_deactivation_hook

/**
 * Register module deactivation hook
 * @param  string $module   module system name
 * @param  mixed $function  function for the hook
 * @return mixed
 */

register_deactivation_hook($module, $function)

register_uninstall_hook

/**
 * Register module uninstall hook
 * @param  string $module   module system name
 * @param  mixed $function  function for the hook
 * @return mixed
 */

register_uninstall_hook($module, $function)

register_cron_task

/**
 * Register module cron task, the cron task is executed after the core cron tasks are finished
 * @param  mixed $function  function/class parameter for the hook
 * @return null
 */

register_cron_task($function)

register_payment_gateway

 /**
     * Inject custom payment gateway into the payment gateways array
     * @param string $idpayment gateway id, should equal like the libraries/classname e.q. gateways/New_gateway
     * @param string $module       module name to load the gateway if not already loaded
     */

register_payment_gateway($id, $module)

register_language_files

/**
 * Register module language files to support custom_lang.php file
 * @param  string $module    module system name
 * @param  array  $languages array of language file names without the _lang.php
 * @return null
 */

register_language_files($module, $languages)

module_dir_url

/**
 * Module URL
 * e.q. https://crm-installation.com/module_name/
 * @param  string $module  module system name
 * @param  string $segment additional string to append to the URL
 * @return string
 */

module_dir_url($module, $segment = '')

module_dir_path

 /**
 * Module directory absolute path
 * @param  string $module module system name
 * @param  string $concat append additional string to the path
 * @return string
 */

module_dir_path($module, $concat = '')

module_libs_path

/**
 * Module libraries path
 * e.q. modules/module_name/libraries
 * @param  string $module module name
 * @param  string $concat append additional string to the path
 * @return string
 */

module_libs_path($module, $concat = '')

You can find below best practices to ensure that your module will be secure. Feel free to apply your own best practices for your module security.

Gather user data from requests

When a user is filling forms, the data is sent e.q. via a POST request to the controller after that you gather this data and insert into the database.

To ensure that this data is escaped, you should gather the data with the built-in CodeIgniter framework input class.

// Get data from POST request

$data = $this->input->post();
$client_id = $this->input->post('client_id');

// Get data from GET request

$data = $this->input->get();
$client_id = $this->input->get('client_id');

Do Not Allow Direct Access the Module Files

For each .php file you created for your module, you must add the code below at the top of the file to prevent the file to be accessed directly.

defined('BASEPATH') or exit('No direct script access allowed');

Include empty index.html files

Always add empty index.html file in each folder you will create in your module directory including your module root directory.

E.q. in modules/[your-module]/

E.q. in modules[your-module]/views

Before the start, we assume that you are already familiar with the modules basics, you created a blank module with all the required headers, and the module is activated and shown in the modules list.

• In modules/[module_name]/ create folder named libraries
• In modules/[module_name]/libraries create a class name e.q. Example_gateway.php, the filename must end with _gateway.php
• See below Sample implementation
• In your module init file, register the payment gateway with the following code:

register_payment_gateway('example_gateway', '[module_name]');

Replace [module_name] with your actual module system name and example_gateway with your module class name (in lowercase).

If you configured everything as it should, navigate to Setup->Settings->Payment Gateways, you will be able to see your Example gateway listed there with the options you specified.

Additionally, depends on the gateway API, you can create a controller to redirect from the process_payment gateway class method.

Sample Implementation

Because Adlis ERP-CRM Dev. uses Codeigniter framework to integrate the payment gateway you will need to create 1 gateway library (gateway config and process method) and 1 gateway controller (for HTTP requests, show form etc..), you can also take a look at the other gateways files in order to get the idea.

In the invoice HTML area when a customer clicks on the button PAY NOW, we call 1 method from the gateway library which will process everything additional that is required for this gateway eq redirect to gateway website and pass parameters or redirect to controller and show form etc…

We have simplified a little the process for creating new gateways e.q. the gateway will be auto showed in Setup->Settings->Payment Gateways, encrypting fields, 1 unique function from each gateway library to call etc… but this will still require effort to get started.

Let’s assume for this example your gateway name is Example

<?php

defined('BASEPATH') or exit('No direct script access allowed');

class Example_gateway extends App_gateway
{
    public function __construct()
    {
        /**
        * Call App_gateway __construct function
        */
        parent::__construct();

        /**
         * Gateway unique id - REQUIRED
	 * 
         * * The ID must be alphanumeric
         * * The filename (Example_gateway.php) and the class name must contain the id as ID_gateway
         * * In this case our id is "example"
         * * Filename will be Example_gateway.php (first letter is uppercase)
         * * Class name will be Example_gateway (first letter is uppercase)
         */
        $this->setId('example');

        /**
         * REQUIRED
         * Gateway name
         */
        $this->setName('Example');

        /**
         * Add gateway settings
         * You can add other settings here 
         * to fit for your gateway requirements
         *
         * Currently only 3 field types are accepted for gateway
         *
         * 'type'=>'yes_no'
         * 'type'=>'input'
         * 'type'=>'textarea'
         *
         */
        $this->setSettings(array(
            array(
                'name' => 'api_secret_key',
                'encrypted' => true,
                'label' => 'API KEY',
                'type'=>'input',
            ),
            array(
                'name' => 'api_publishable_key',
                'label' => 'SECRET KEY',
                'type'=>'input'
            ),
            array(
                'name' => 'currencies',
                'label' => 'settings_paymentmethod_currencies',
                'default_value' => 'USD,CAD'
            ),
        ));

    }

    /**
     * Each time a customer click PAY NOW button on the invoice HTML area, the script will process the payment via this function.
     * You can show forms here, redirect to gateway website, redirect to Codeigniter controller etc..
     * @param  array $data - Contains the total amount to pay and the invoice information
     * @return mixed
     */
    public function process_payment($data)
    {
        var_dump($data);
        die;
    }
}

There are comments on the functions and variables, you should spend some time to read them because they are important if you want to help you get started.

Additionally, you can take a look at the other gateway example in application/libraries/gateways or application/controllers/gateways.

Excluding URL from CSRF

If the module payment gateway is using webhooks and makes a POST request to a URL in Adlis ERP-CRM Dev. to notify about the payment updates, you will need to exclude this URL from CSRF in order for the request to pass.

You can follow this guide in order to achieve this.

To get more familiar how this works, visit this link:

https://codeigniter.com/userguide3/general/security.html?highlight=csrf#csrf-protection

More information about CSRF can be found here:
https://en.wikipedia.org/wiki/Cross-site_request_forgery

HTML Forms

You must use the CodeIgniter helper function for forms to open a form in order for the function to generate the CSRF form token.

All Adlis ERP-CRM Dev. forms that comes with the installation uses form_open() functions to open a form element.

Find below an example form that use form_open().

<?php echo form_open(admin_url('departments/department')); ?>
<!-- Your form input fields goes here -->
<?php echo form_close(); ?>

AJAX Request

Adlis ERP-CRM Dev. comes with jQuery on both clients and customers area, if you are submitting a form via AJAX Request and you are using the jQuery help functions e.q. $.post or $.ajax, you won’t need to perform any additional actions because the CSRF keys are already configured.

However, if you are using any external library for requests, you must include the CSRF key manually.

Exclude URL from CSRF (>= v2.9.0)

If the module is in need to exclude URL from a CSRF protection, you can achieve this by creating a configuration file [MODULE_NAME]/config/csrf_exclude_uris.php

The file must return an array with excluded URI’s.

return [
  'mypos/webhook',
  'api/other-uri',
  ...etc
];

Note that you can add regex matching to the URI’s as well, read more here in the Codeigniter guides.

Adlis ERP-CRM Dev. will determine whether there is a new upgrade for your module by the init file version header.

For example, you released a version 1.0.0 and the users are using this version, at the time the user will install your 1.0.0 version and and activate the module, Adlis ERP-CRM Dev. will store the activated module version number in database.

Then you release version 1.1.0 and the user re-upload/install the module files, Adlis ERP-CRM Dev. will determine that the version from the file header is not the same like the one stored in the database and will show a message to the user to upgrade the database.

Adlis ERP-CRM Dev. modules migration extends the CodeIgniter framework migration library and uses the Sequential migration type, keep in mind that there is no ability to change the Sequential type to Timestamp.

If you are not familiar with the CodeIgniter migration library, the best is to check their documentation.

Each migration is numbered in sequence, starting with 001. Each number must be three digits, and there must not be any gaps in the sequence.

Create (if not exists) a folder name migrations in the module directory, after you create the folder the location will be: modules/[module-name]/migrations

For our example, you must create a migration file e.q. 110_version_110.php with the following contents:

<?php

defined('BASEPATH') or exit('No direct script access allowed');

class Migration_Version_110 extends App_module_migration
{
    public function up()
    {
        // Perform database upgrade here
    }
}

The 110_version_110.php file will perform an upgrade for your module version 1.1.0.

Keep in mind that in your activation hook, you still must have the latest changes for the database, the migration files will run only for existing installation who are using an older version, the new module installation must get these DB changes from the install hook.

Caveats

Downgrade

There is no ability to downgrade to previous versions, for this reason, always just add the up method in your migration files.

Create migration file whenever the module header version is changed.

You must create a migration file each time you change the module version number even if there are no changes in the database.

Adlis ERP-CRM Dev. can’t determine if you have or not have a database upgrades but the migration file must be executed in order just to upgrade the version number in database.

In cases like this when there is no queries to perform in the migration file, just leave the method up empty e.q. as shown in the example above.

The user will see that there is database upgrade required, will click “Upgrade Database”, an empty migration will run and the database number will be successfully updated.

To add language files to your module so users can translate it, you must create a folder in modules/[module_name]/language/[language_name_folder]

At this time the [language_name_folder] must exist in the core language files located in application/language

For example, if you want to create English language translations, you will create the following folder(s): /modules/[module_name]/language/english

Language Files

In each language, you can create unlimited number of files e.q. if you want to separate specific features language files or you can include them in one general language file.

The file name must end with _lang.php, you should check the Codeigniter framework documentation for more info about the language file name and it’s usage.

In this example we will create sample_module_lang.php file in /modules/[module_name]/language/english/

For each additional language you want to have translations, you must include all files from your general language e.q. in this case English

For example, if you have 3 language files in the /english folder and you want to include new Spanish language, you must create new folder for the Spanish language and copy those 3 language files in the /spanish folder.

Registering Language Files

Instead of loading the language files directly there is a helper function to register the language files and allow your language to support using a custom_lang.php file so the end users can overwrite the translations.

More info about custom_lang.php file in the language directory can be found here

In your module init file add the following code:

register_language_files('module_name', ['sample_module']);

The first parameter to the register_language_files function is the module name, don’t forget to replace module_name with your actual module name.

The second parameter must be an array with language files names without the _lang.php.

Fetching a Line of Text

Instead of using the Codeigniter framework default method to fetch translation line of text, you can use Adlis ERP-CRM Dev. custom function:

/**
 * @param  string $line   language line key
 * @param  mixed $label   label e.q. if you have $lang['sample_module_create_new'] = 'Create New %s';
 * @return string         language text
 */
_l($line, $label = '', $log_errors = true);

Conflicts

Make sure that your language keys you add in the language files do not conflict with Adlis ERP-CRM Dev. language keys that are added in application/language or with any other modules.

For this reason, we recommend to add unique language keys or prefix them with your module name.