ExpressionEngine

2.4.0 User Guide

CP Class

Calling the CP Class

This class is initialized automatically in the control panel.

Set Variables

This is a simple alternative for setting a page variable. It is used almost exclusively for setting the title of a control panel page:

$this->EE->cp->set_variable('cp_page_title', $this->EE->lang->line('page_title'));

Adding Header Data

The <head> tag of the control panel can be extended with new styles, meta tags, and other data. Multiple calls to this function are additive.

$this->EE->cp->add_to_head('<style type="text/css" media="screen">div { display: none; }</style>');

Loading Javascript Files

The javascript library will only load files from the main javascript directory. This function includes files from the current package’s javascript folder. It takes a simple file name, .js will be appended automatically.

$this->EE->cp->load_package_js('my_file');

Add a javascript file or files to the javascript combo loader

This function allows you to include scripts in the ‘combo load’ routine, thus reducing HTTP requests. The first parameter specifies the directories (if needed) and files to be added and the optional second parameter determines the placement of the resulting javascript link, defaulting to TRUE to place in the footer.

$this->EE->add_js_script(
        array(
                'ui' => array('core', 'widget', 'position', 'autocomplete'),
                'plugin' => array('fancybox')
        )
);

Control Panel Messages

The control panel class creates a default view variable $cp_messages, which you will typically use to display messages after form submission. By default, this is an empty array. Using the Session Class’s set_flashdata() (requires a redirect), you may specify a success and/or failure message. The message content will be displayed using the ./themes/cp_themes/default/_shared/message.php view, with a class of ‘success’ or ‘failure’ as needed. If javascript is enabled, the html notification will automatically be hidden and the message will be displayed by the notification plugin with the appropriate message type indicated.

$this->EE->session->set_flashdata('message_success', $this->EE->lang->line('updated'));
$this->EE->session->set_flashdata('message_failure', $this->EE->lang->line('write_failed'));
$this->EE->functions->redirect(BASE.AMP.'C=addons_modules'.AMP.'M=show_module_cp'.AMP.'module=my_module');

After redirecting, a javascript success notification bar would show briefly, followed by an error message. Error messages, if shown, remain visible until manually closed.

Allowed Group

When a user or logged in member visits an EE site, the Session class ascribes user data to them that, among other things, pertains to their member groups’s access to various parts of the site. Returns FALSE if they have access, TRUE if they do.

if ( ! $this->EE->cp->allowed_group('can_delete_all_entries'))
{
        show_error($this->lang->line('unauthorized_to_delete_others'));
}

Safe Refresh

Some pages of the control panel can only be reached after the user submits a form. If you need to perform an action elsewhere and the redirect to the current page, get_safe_refresh() will return a url that takes these considerations into account. To use the result, prefix it with BASE.AMP

<?=form_open('C=myaccount'.AMP.'M=notepad_update', array('id' => 'notepad_form'), array('redirect_to' => $this->cp->get_safe_refresh()))?>

Fetch an Action ID

Modules have certain actions for forms, links, etc. that are recognized via an action ids that are inserted into the database upon installation of that module. This function returns the action id number from the database. (See also functions->fetch_action_id)

$aid = $this->EE->cp->fetch_action_id($class, $method);

Publish Page Layout Functions

Administrators may extensively customize publish pages on a per member group and per channel basis. Since these custom layouts are saved as a serialized array in the database, any additions or deletions to publish page tabs and fields must be synced to any saved layouts. The control panel library provides 4 functions to facilitate custom layout updates. (See also Module Tutorial: Update file.)

Add Tabs

NOTE: This function has been moved to the Layout Class and will be removed from the CP Class in a future release.

Adds tabs and any associated fields to currently saved publish layouts. If there is an existing tab with the same name, the function will return false

$this->EE->cp->add_layout_tabs($tabs);

$tabs must be an associative array where the top level array(s) is the name of the tab. If the tab contains any fields, as it likely does, include them as elements of their tab’s array, with the field name as a key and containing the required elements: visible, collapse, htmlbuttons and width.

$tabs['pages'] = array(
        'pages_uri'     => array(
                                'visible'       => 'true',
                                'collapse'      => 'false',
                                'htmlbuttons'   => 'true',
                                'width'         => '100%'
                                ),
        'pages_template_id'     => array(
                                'visible'       => 'true',
                                'collapse'      => 'false',
                                'htmlbuttons'   => 'true',
                                'width'         => '100%'
                                )
        );

Delete Tabs

NOTE: This function has been moved to the Layout Class and will be removed from the CP Class in a future release.

This function will remove tabs and all associated fields from the saved publish page layouts. The $tabs variable must be an associative array, with the top level array’s key the name of the tab. As in the add_layout_tabs() function, any associated fields should be included as keys within the tab’s array.

$this->EE->cp->delete_layout_tabs($tabs);

Add Fields

NOTE: This function has been moved to the Layout Class and will be removed from the CP Class in a future release.

Used to add new fields to an already existing tab. Because custom layouts may have moved the field(s) to a different tab and deleted the tab originally associated with the fields, a new tab will be created if none exists in the layout. The $tabs array takes the same format as the add_layout_tabs() function, while $channel_id is an optional parameter that limits the update to layouts associated with a given channel and should generally be omitted from third party usage.

$this->EE->cp->add_layout_fields($tabs, $channel_id);

Delete Fields

NOTE: This function has been moved to the Layout Class and will be removed from the CP Class in a future release.

Used to delete fields without removing the existing tab. This function removes all matching field names from the saved layouts, regardless of the tab they are currently saved in. The $tabs array takes the same format as the add_layout_tabs() function, while $channel_id is an optional parameter that limits the update to layouts associated with a given channel and should generally be omitted from third party usage.

$this->EE->cp->delete_layout_fields($tabs, $channel_id);

User Contributed Notes

Posted by: Lodewijk on 26 January 2010 4:03am
Lodewijk's avatar

If you’re loading an external JavaScript file, make sure you put it in a folder called ‘javascript’, so:

$this->EE->cp->load_package_js('my_file'); 

will load:

/third_party/my_package/javascript/my_file.js 

You must have an ExpressionEngine license and have attained a forum rank of "Lab Assistant" (100 posts) to contribute notes to the User Guide