Build your own module

Looking to add features to your End-user Interface to gain a competitive advantage? Looking for another revenue stream?

With CakeMail’s Plugin Module API you can by-pass API and easily create Plugin Modules, integrating your application into CakeMail, so you can offer your software to your customers OR the entire CakeMail user community as a “one-click” Plugin to CakeMail.

Tips

Each module should be contained in its own folder under the htdocs/modules/ folder.

The module code should be contained in the file:

ROOT . modules/[module name]/index.php

Templates

Modules use Smarty templates. These templates are located within the folder:

ROOT . modules/[module name]/templates/

Languages

Languages are processed using gettext. Your language .mo file should be installed in the following folder:

ROOT . modules/[module name]/locales/system/[lang_code]/LC_MESSAGES/messages.mo

All modules must have a en_US language file. Other languages are optional.

Text in templates

No text should be hardcoded within templates. Every text strings must be represented as a text tag that will be replaced by gettext with the appropriate string depending on the selected language. The text tags must be unique and must be named according to the following patern:

[module_name].[template_name]_MSG_##

where [module_name] is replaced by the module name, [template_name] is replaced by the full template file name and ## replaced by a unique incrementing number.

Examples

• my_module.general_statistics.tpl_MSG_00
• my_module.module_admin.tpl_MSG_48

within templates already defined the following variables:

• {$mod_name}: Name of the module.
• {$mod_url_path}: Relative URL path to the module.

index.php structure

Your index.php must have the following structure:

require_once(ROOT . "modules/CakeModule.php");

class <module_name> extends CakeModule{

// Your module code here

}

Note: the <module_name> in the code above should NOT be modified by the actual name of your module name. It is normal that PHP reports an error on this string. The index.php code is preprocessed and the string will be automatically replaced with your actual module name.

CakeModule class

CakeModule class is abstact class and must be used as the base class for the module class in the index.php described above.

Properties

conf

Configuration array.

• enabled: 1 if the module is enabled, 0 otherwise
• enabled_4all: 1 if the module is enabled for all clients, use clients for details if the value is 0
• clients: array of the enabled clients who can use this module

error

Null, reserved for later usage.

path

Absolute path to the module's folder.

name

Name of the module.

url_path

Relative URL path to the module.

Methods

init($p)

Called when the module is loaded.

• $p: configuration array (identical to the conf property)

uninit($p)

Called when the module is unloaded

• $p: an empty array, reserved for later usage

api_cb($function, $params, $locales, $result, $has_result)

Method to catch API calls. api_cb() executes for each (one) API call twice, first time for preprocessing parameters send to the API and second for postprocessing the result.

• $function: name of the method
• $params: array of the call parameters
• $locales: name of the locale
• $result: null for first call and contains result data from the API for second
• $has_result: if contains false the $result is null and this is first call, otherwise the value is true

function api_cb($function, $params, $locales, $result, $has_result) {
  if ($has_result) {
    // code for postprocessing
    switch ($function) {
      case "cake_list_GetList":
        // your code here
        break;
      case "cake_list_GetInfo":
        // your code here
        break;
      }
    } 
  } else {
    // your code for preprocessing
  }
}

fetch_html_cb($p)

The main method of the module. Executes each time when an template is ready to fetch.
$p: array of parameters

• template: name of the template
• smarty: smarty object reference
• html_dom: CakeHtmlDom object with html content that should be output

function fetch_html_cb($p) {
  switch ($p["template"]) {
    case "mailing/email.tpl":
      // your code here, for example:
      $p["html_dom"]->replace_html("texarea[id=html_message]", "This module replaces any html message of mailings by this text", "after_start");
      break;
    case "campaign/templates_edit.tpl":
      // your code here, for example:
      $module_html = $p["smarty"]->fetch($this->path . "templates/main.tpl");
      $p["html_dom"]->add_html("div[id=some-div]", $module_html, "after_end");
      break;
    }
  }
}

proc_req_cb()

Process the _REQUEST array. This function is called at the beginning of each script.

function proc_req_cb() {
  $_REQUEST["some_parameter"] = trim($_REQUEST["some_parameter"]);
}

CakeHtmlDom class

CakeHtmlDom is a child class of the PHP Simple HTML DOM Parser. Read manual for details and examples here.

Methods

add_html($str, $html, $where)

Adds html code to an element.

• $str: a string identifying the element
• $html: the html code to add
• $where: a string indicating where to add the code
  possible values are:
  • before_start
  • after_start
  • before_end
  • after_end

delete_html($str)

Deletes an element.

• $str: string identifying the element

replace_attribute($str, $attr, $value)

Replaces the attribute value of all identified elements.

• $str: string identifying the element
• $attr: attribute name
• $value: new atrribute value

delete_html($str)

Deletes an element.

• $str: string identifying the element

replace_dom($html)

Replaces the whole document with another.

• $html: the new html code

replace_html($str, $html, $completely)

Replaces the whole document with another.

• $str: string identifying the element
• $html: html code replacing old code
• $completely: if true, the whole element is replaced, otherwise only the content is replaced