v3 Add-on Migration

CP URLs

cp_url(...) has been deprecated, please use ee('CP/URL', '...'). For the full documentation see Control Panel Styles.

Model Service

The model service helps smooth out interacting with ExpressionEngine’s data types by providing an API that mimics their natural language description as closely as is feasible. You do not query for channel_data joined on channel_titles; instead, you simply get a channel entry:

$oscar = ee('Model')->get('Member')
  ->filter('screen_name’, ‘Oscar')
  ->first();

$oscar->bio = 'I got this.';
$oscar->save();

For the full documentation see Model Service.

New URL Logic

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 method to list our cookies its URL might 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. For this URL:

addons/settings/fortune_cookie/edit_cookie/3

We would need to have the following method signature:

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

Control Panel 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. The body key should contain an HTML string which will be used in the “body” section of the Control Panel layout inside our Add-On Manager. The breadcrumb key should contain an associative array of URLs as keys and strings for the bodies. The header value will be added as the final segment in the breadcrumb. The heading key should contain a string for use as the heading (i.e. Fortune Cookie Management).

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

$url = ee('CP/URL', 'addons/settings/fortune_cookie')->compile();

return array(
  'body'       => ee('View')->make('fortune_cookie:index')->render($vars),
  'breadcrumb' => array(
    $url => lang('fortune_cookie_management')
  ),
  'heading'  => lang('edit_fortune_cookie'),
);

The Table Service

Tables are the most common way to view and navigate data in the ExpressionEngine control panel. Since tables share a lot of common functionality, we’ve abstracted most of it out to a Table service to handle tasks such as displaying the table markup, and sorting and filtering tabular content:

$table = ee('CP/Table', array('autosort' => TRUE, 'autosearch' => FALSE, 'limit' => 20));
$table->setColumns(
  array(
    'tool_set',
    'status',
    'manage' => array(
      'type'  => Table::COL_TOOLBAR
    ),
    array(
      'type'  => Table::COL_CHECKBOX
    )
  )
);

$table->setData($data);

See CP/Table Service for full documentation.

The Pagination Service

Adding pagination to the control panel is a common task and we created a pagination service to assist. This service handles all the mathematical calculations. All you need is the number of items you are going to paginate and a URL object:

$base_url = ee('CP/URL', 'publish/edit');
$pagination = ee('CP/Pagination')->make($total_count)
  ->render($base_url);

See CP/Pagination Service for full documentation.

The CP/Alert Service

Alerts are for providing feedback on an action and calling attention to warnings or errors. We have created an Alert Service for creating alerts in your code. For example:

ee('CP/Alert')->makeInline('fortune-cookie-form')
  ->asIssue()
  ->withTitle(lang('fortune_cookie_save_error'))
  ->addToBody(lang('fortune_cookie_save_error_desc'))
  ->now();

And:

<?=ee('CP/Alert')->get('fortune-cookie-form')?>

See CP/Alert Service for full documentation.

The Shared Settings Form

Forms are created by creating an array of field descriptions. This keeps the view code consistent and modular. Below is an example of a simple form with a text input and a checkbox:

$vars['sections'] = array(
  array(
      array(
          'title' => 'tool_set_name',
          'desc' => 'tool_set_name_desc',
          'fields' => array(
              'toolset_name' => array(
                  'type' => 'text',
                  'value' => $toolset_name,
                  'required' => TRUE
              )
          )
      ),
      array(
          'title' => 'choose_tools',
          'desc' => 'choose_tools_desc',
          'fields' => array(
              'tools' => array(
                  'type' => 'checkbox',
                  'choices' => $tools,
                  'value' => $toolset['tools'],
                  'wrap' => FALSE
              )
          )
      )
  )
);

And:

<?php $this->embed('ee:_shared/form')?>

See Shared Form View for full documentation.

Modals

Under 3.0 modals belong to a specific spot in the Control Panel’s DOM, and that place isn’t accessible from a module’s view. To solve that we have created a modal service. There are two basic calls to use it within your view files, ee('CP/Modal')->startModal($name); and ee('CP/Modal')->endModal();. Everything between those two lines will be be stored in the modals block and output in the correct spot of the DOM.

<?php ee('CP/Modal')->startModal($name); ?>
<div class="modal-wrap modal-test">
  <div class="modal">
      <div class="col-group">
          <div class="col w-16">
              <div class="box">
                  ...
              </div>
          </div>
      </div>
  </div>
</div>
<?php ee('CP/Modal')->endModal(); ?>

See CP/Modal Service for full documentation.

External Links

To protect the users control panel URL from ending up in web server referrer logs, use Cp::masked_url from the Control Panel Class:

ee()->cp->masked_url('https://www.google.com');

Will result in:

https://example.com?URL=https://www.google.com

Internal Links

Internal control panel links should be generated with the ee('CP/URL') helper function which generates control panel URLs based on parameters passed in.

For example, to link to the publish controller, pass it in as the first parameter to ee('CP/URL'):

ee('CP/URL', 'publish');

To link to a particular method in a controller, add it to the parameter with a slash:

ee('CP/URL', 'publish/method_name');

If the method accepts arguments, they can be passed in cleanly by adding them on the end separated by a slash:

ee('CP/URL', 'publish/method_name/5');

If the link requires any other GET parameters, they can be passed in via an associative array in the second parameter:

ee('CP/URL', 'publish/edit', array('filter_by_channel' => $channel_id));

See CP/URL Service for the full documentation.

Control Panel Constants

• BASE - Name of control panel file with the users session id
• AMP - Will render &
• AJAX_REQUEST - Returns Boolean TRUE if a request was made via an Ajax Request
• QUERY_MARKER - Renders a query marker (?)
• APPPATH - Server path to the system/ee/legacy directory
• PATH_ADDONS - Server path to the first-party add-ons directory
• PATH_THIRD - Server path to the third-party add-ons directory
• PATH_JQUERY - Server path to jQuery files at themes/ee/javascript/compressed/jquery