Retired Documentation
You are using the documentation for version 2.11.9. Go here for the latest version or check here for your available upgrades to the latest version.
CP Class¶
- Calling the CP Class
- Breadcrumbs
- Sub Navigation
- Set Variables
- Adding Header Data
- Add JavaScript Files to the JavaScript Combo Loader
- Loading Third-Party JavaScript Files
- Masking the Control Panel URL in links
- Allowed Group
- Safe Refresh
- Fetch an Action ID
- Control Panel Messages
- Publish Page Layout Methods
Calling the CP Class¶
-
class
Cp
¶ This class is initialized automatically in the control panel.
Breadcrumbs¶
Adds a new breadcrumb to the initial breadcrumb array. The system will automatically output the final array:
ee()->cp->set_breadcrumb($link, $title);
Parameters: - $link (type) – URL the breadcrumb should go to
- $title (type) – Text to go in the link
Return type: Void
Set Variables¶
-
Cp::
set_variable
($name, $value)¶ Deprecated since version 2.6: Use
$this->EE->view->cp_page_title = '...'
instead.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', lang('page_title'));
Parameters: - $name (string) – Name of the variable to set
- $value (string) – Value to set
Return type: Void
Adding Header Data¶
-
Cp::
add_to_head
($data)¶ The
<head>
tag of the control panel can be extended with new styles, meta tags, and other data. Multiple calls to this method are additive:ee()->cp->add_to_head('<style type="text/css" media="screen">div { display: none; }</style>');
Parameters: - $data (string) – String to add to the
<head>
of the control panel
Return type: Void
- $data (string) – String to add to the
Add JavaScript Files to the JavaScript Combo Loader¶
-
Cp::
add_js_script
($script_type, $script_name)¶ This method allows you to include scripts found in the main JavaScript directory in the combo load routine, thus reducing HTTP requests. As an example, the call to load
filename.js
file from thethemes/javascript
directory would look like this:ee()->add_js_script('file', 'filename');
Parameters: - $script_type (string) – Type of script to load
- $script_name (string) – Name of script to load
Returns: Associative array of loaded js files
Return type: Array
Note
This method will only load files from the
themes/javascript
directory. To load a third-party add-on package’s JavaScript files, useCp::load_package_js
.Several custom jQuery plugins are included with ExpressionEngine and available for third-party developers to use. Plugins available include ee_interact.event, ee_notice, tablesorter, ee_table, and wysihat.
An example call to load one of the jQuery plugins:
ee()->add_js_script('plugin', 'tablesorter');
The jQuery UI interactions and widgets are also included with ExpressionEngine for third-party developers to use. The call to load the jQuery UI Autocomplete plugin would look like this, for example:
ee()->add_js_script('ui', 'autocomplete');
-
Cp::
add_js_script
([$script = array()[, $in_footer = TRUE]]) Several scripts can be included in a single call as an array:
ee()->add_js_script( array( 'ui' => array('widget', 'position', 'autocomplete'), 'plugins' => array('ee_notice', 'ee_table') ) );
Parameters: - $script (array) – Associative array containing the scripts you need to load
- $in_footer (boolean) – Adds to the footer if set to
TRUE
, otherwise it’s added to the<head>
Returns: Associative array of loaded js files
Return type: Array
Loading Third-Party JavaScript Files¶
-
Cp::
load_package_js
($file)¶ Use this method to load a third-party add-on package’s JavaScript files:
ee()->cp->load_package_js('my_file');
This will load from the current package’s
javascript
directory:/third_party/my_package/javascript/my_file.js
Parameters: - $file (string) – JavaScript file to load, path relative to the current package’s JavaScript directory
Return type: Void
Masking the Control Panel URL in links¶
-
Cp::
masked_url
($url)¶ When creating external links in the users Control Panel, the system folder should not show in server referral logs:
ee()->cp->masked_url('http://example.com');
Creates the a the following link:
http://example.com/index.php?URL=http://example.com
Parameters: - $url (string) – URL to mask
Returns: The masked URL
Return type: String
Allowed Group¶
-
Cp::
allowed_group
($which)¶ 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 ( ! ee()->cp->allowed_group('can_delete_all_entries')) { show_error(lang('unauthorized_to_delete_others')); }
Parameters: - $which (string) – permission string to check for
Returns: TRUE
if they have access,FALSE
if they don’t or if the permission doesn’t existReturn type: String
Safe Refresh¶
-
Cp::
get_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 withBASE.AMP
:<?=form_open( 'C=myaccount'.AMP.'M=notepad_update', array('id' => 'notepad_form'), array('redirect_to' => $this->cp->get_safe_refresh()) )?>
Returns: URL to the current page unless POST
data exists, in that case it goes to the root controllerReturn type: String
Fetch an Action ID¶
-
Cp::
fetch_action_id
($class, $method)¶ 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 method returns the action id number from the database. (See also functions->fetch_action_id):
$aid = $this->EE->cp->fetch_action_id($class, $method);
Parameters: - $class (string) – Class that contains the method
- $method (string) – Name of the method
Returns: Action ID
Return type: Integer
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
Session::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. After redirecting, a javascript success notification bar
would show briefly, followed by an error message. Error messages, if
shown, remain visible until manually closed.
Publish Page Layout Methods¶
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 methods to facilitate custom layout updates. (See also Module Tutorial: Update file.)