install() *¶

Module_name_upd::install()¶

Installs the module, adding a record to the exp_modules table, creates and populates and necessary database tables, adds any necessary records to the exp_actions table, and if custom tabs are to be used, adds those fields to any saved publish layouts.

• Add the module to the exp_modules table—this step is required. Note has_cp_backend should be 'y' if the module has a control panel, 'n' otherwise; has_publish_fields’ should be 'y' if the module adds tabs/fields to the publish page, 'n' otherwise:

  $data = array(
     'module_name' => 'Module_name' ,
     'module_version' => $this->version,
     'has_cp_backend' => 'y',
     'has_publish_fields' => 'y'
  );
  
  ee()->db->insert('modules', $data);
  

• Optionally add records to the exp_actions table—used if your module needs to invoke actions based on frontend behavior such as form submission:

  $data = array(
     'class'     => 'Module_name' ,
     'method'    => 'method_to_call'
  );
  
  ee()->db->insert('actions', $data);
  

• Optionally add the publish page tab fields to any saved publish layouts. This is ONLY used if the module adds a tab to the publish page and it requires the tabs() function:

  ee()->load->library('layout');
  ee()->layout->add_layout_tabs($this->tabs(), 'module_name');
  

Returns:	TRUE if everything installed properly, FALSE if not
Return type:	Boolean

update($current = ‘’) *¶

Module_name_upd::update($current = '')¶

This function is checked on any visit to the module’s control panel, and compares the current version number in the file to the recorded version in the database. This allows you to easily make database or other changes as new versions of the module come out:

function update($current = '')
{
    if (version_compare($current, '2.0', '='))
    {
        return FALSE;
    }

    if (version_compare($current, '2.0', '<'))
    {
        // Do your update code here
    }

    return TRUE;
}

Parameters:	$current (string) – The last recorded version of the module in the exp_modules table
Returns:	FALSE if no update is needed, TRUE otherwise
Return type:	Boolean

uninstall() *¶

Module_name_upd::uninstall()¶

Deletes the module record from exp_modules, any associated actions from exp_actions, and uninstalls any tables created by the module. Returns TRUE

• Optionally delete any publish page tab fields saved in publish layouts. This is ONLY used if the module adds a tab to the publish page and it requires the tabs() function:

  ee()->load->library('layout');
  ee()->layout->delete_layout_tabs($this->tabs(), 'module_name');
  

Returns:	TRUE if everything uninstalled properly, FALSE otherwise
Return type:	Boolean

tabs()¶

Module_name_upd::tabs()¶

An optional function, included only if the module adds a tab to the publish page. This function should return an multidimensional associative array, the top array key consisting of the tab name, followed by any field names, with each field having a variety of default settings. Note that when the fields are added to the publish page, they are namespaced to prevent variable collisions:

function tabs()
{
    $tabs['tab_name'] = array(
        'field_name_one'=> array(
            'visible'   => 'true',
            'collapse'  => 'false',
            'htmlbuttons'   => 'true',
            'width'     => '100%'
            ),
        'field_name_two'=> array(
            'visible'   => 'true',
            'collapse'  => 'false',
            'htmlbuttons'   => 'true',
            'width'     => '100%'
            ),
        );

    return $tabs;
}

Returns:	Associative array of the tab name and tab fields
Return type:	Array

module tab label¶

In addition to the two required fields you can have a custom tab label for your publish fields. Just assign the desired label to a key which shares the name of your module name:

// Additional Key => Value pairs go here

/**
 * Tab Label for publish fields
 *
 * Assign the label you wish to use to the module_name array key
 * Remember only alphanumeric characters, underscores, dashes and spaces are allowed.
 */

'module_name' => 'Tab label'

display($channel_id, $entry_id = ‘’) *¶

Module_name_tab::display($channel_id[, $entry_id = ''])¶

This function creates the fields that will be displayed on the publish page. It must return $settings, an associative array specifying the display settings and values associated with each of your fields.

Parameters:	$channel_id (int) – Channel ID where the entry is being created or edited $entry_id (int) – Entry ID if this is an edit, empty otherwise
Returns:	Settings (see below)
Return type:	Array

The settings array elements:

Array(
  '...' => Array( // name of the field (same as 'field_id' below)
    'field_id'              => '...', // name of the field
    'field_label'           => '...', // field label, typically a language variable is used here
    'field_required'        => '...', // whether to include the 'required' class next to the field label: y/n
    'field_data'            => '...', // current data, if applicable
    'field_list_items'      => '...', // array of options, otherwise empty string
    'options'               => '...', // array of options, otherwise empty string
    'selected'              => '...', // selected value if applicable to the field_type
    'field_fmt'             => '...', // allowed field format options, if applicable
    'field_instructions'    => '...', // instructions to be displayed for this field on the publish page
    'field_show_fmt'        => '...', // whether the field format dropdown shows: y/n. Note: if 'y', you must specify the options available in field_fmt
    'field_pre_populate'    => '...', // can pre-populate a field when it's a new entry
    'field_text_direction'  => '...', // direction of the text: ltr/rtl
    'field_type'            => '...'  // may be any existing field type
  )
)

validate($entry, $values) *¶

Module_name_tab::validate($entry, $values)¶

Allows you to validate the data after the publish form has been submitted but before any additions to the database:

function validate($entry, $values)
{
  $validator = ee('Validation')->make(array(
    'foo_field_one' => 'required',
    'foo_field_two' => 'required|enum[y,n]',
  ));

  return $validator->validate($values);
}

Parameters:	$entry (EllisLabExpressionEngineModuleChannelModelChannelEntry) – The channel entry entity $values (array) – an associative array with field names as keys and form submission data as the value (i.e. array('fortune' => 'All your hard work will soon pay off.')). The keys are derrived from the data returned by display().
Returns:	A result object
Return type:	EllisLabExpressionEngineServiceValidationResult

save($entry, $values) *¶

Module_name_tab::save($entry, $values)¶

Called during a ChannelEntry entity’s afterSave event, this allows you to insert data/update data:

function save($entry, $values)
{
    if (! isset($values['field_name_one']) OR $values['field_name_one'] == '')
    {
        return;
    }

    $data = array(
        'entry_id' => $entry->entry_id,
        'file_id' => $values['field_name_one']
    );

    ee()->db->insert('table_name', $data);
}

Parameters:	$entry (EllisLabExpressionEngineModuleChannelModelChannelEntry) – The channel entry entity $values (array) – an associative array with field names as keys and form submission data as the value (i.e. array('fortune' => 'Do not make extra work for yourself.')). The keys are derrived from the data returned by display().
Return type:	Void

delete($entry_ids) *¶

Module_name_tab::delete($entry_ids)¶

Called during a ChannelEntry entity’s beforeDelete event, this allows you to sync your records if any are tied to channel entry_ids.

Parameters:	$entry_ids (array) – An indexed array of entry IDs that were deleted
Return type:	Void

Control Panel URLS¶

The Control Panel URLs for your module follow the pattern addons/settings/package_name/method_name/arguments. For example, if we had a fortune cookie module with a view for list our cookies its URL would be addons/settings/fortune_cookie/cookies. Like 2.x the routing is automatic; all public methods in your mcp.package_name.php are automatically routed. We will also pass any arguments to your method found in the url. If the URL is addons/settings/fortune_cookie/edit_cookie/3 we would need to have the following method signature:

public function edit_cookie($id) {...}

We have a CP/URL Service to help you construct your URLs.

Output, Breadcrumbs, and Headings¶

There are two ways to output your control panels. You may either return an HTML string, or you may return an associative array.

If you return a string that data will be used in the “body” section of the Control Panel layout inside our Add-On Manager. The breadcrumb will default to Add-On Manager / Your Add-On Name and the heading will default to Your Add-On Name Configuration. In our fortune cookie module example we would have Add-On Manager / Fortune Cookies as the breadcrumb and Fortune Cookie Configuration as the heading.

If you return an associative array it must contain the key body and may contain the keys breadcrumb, and heading:

return array(
  'body'       => $html,
  'breadcrumb' => array(
    ee('CP/URL')->make('addons/settings/module_name')->compile() => lang('module_name')
  ),
  'heading' => lang('module_name_settings')
);

• body (string): HTML string which will be used in the “body” section of the Control Panel layout inside the Add-On manager
• breadcrumb (array): Associative array containing key/value pairs where the key is the CP/URL and the value is the string to display as the breadcrumb
• heading (string): The string to display as the page <title> and the Section Header

If your add-on needs a sidebar use the Sidebar Service.

ee()->cp->header = array(
  'toolbar_items' => array(
    'settings' => array(
      'href' => ee('CP/URL')->make('settings/template'),
      'title' => lang('settings')
    ),
  )
);

Javascript¶

ExpressionEngine includes both its own JavaScript library as well as the The jQuery JavaScript library, enabling developers to easily include JavaScript enhancements. It is worth noting some ‘best practices’ when using JavaScript in your control panel:

• Loading jQuery plugins:

  ee()->cp->add_js_script(array('plugin' => 'dataTables'));
  

• Outputting JavaScript to the browser:

  ee()->javascript->output();
  

• After defining any JavaScript output, you must compile in order to display it:

  ee()->javascript->compile();
  

Working with Forms¶

While creating forms for the backend is fairly routine, there are several differences/additions worth noting:

• The Form Validation library is available, but the best means of checking submitted form data and returning in-line errors is to either use Model Validation or the Validation Service.
• After form submission, you will generally want to output a success (or failure) message using the CP/Alert Service.

Outputting Pages¶

There are two ways to output content to the screen. For very simple pages, you may want to simply return the desired output in a string. Any string that the method returns is placed inside the cp page’s content container. With all but the simplest of output, the use of View files will be the preferred method for handling your markup and presentation.

The Core Module File (mod.module_name.php)¶

class Module_name¶

The Core Module file is used for outputting content via Templates and doing any processing that is required by both the Control Panel and any module tags contained in a template. It includes a class with a name that matches the package (the first letter of the class name must be capitalized). There is one required class variable, $return_data, which will contain the module’s outputted content and is retrieved by the Template parser after the module is done processing.

The tag structure of a module follows the same rules as the Plugins API:

{exp:module_name:method}