Simple Example¶

The Control Panel’s left sidebar is built with the Sidebar Service:

$sidebar = ee('CP/Sidebar')->make();

You can add a header:

$header = $sidebar->addHeader($text, $url);

Headers may have a button:

$header->withButton($text, $url);

Header’s may have a list. A list may be a basic list or a folder list:

$basic_list  = $header->addBasicList();
$folder_list = $header->addFolderList($name);

Lists have items:

$basic_item  = $basic_list->addItem($text, $url);
$folder_item = $folder_list->addItem($text, $url)
  ->withEditUrl($url)
  ->withRemoveConfirmation($msg)
  ->identifiedBy($id);

All list items may be marked as active:

$item->isActive();

Folder list items may also be marked as default:

$folder_item->asDefaultItem();

Basic list items may also be marked as a delete action:

$basic_item->asDeleteAction();

You can add a folder list directly to a sidebar without a header:

$folder_list = $sidebar->addFolderList($name);

Sidebars can have an action bar at the bottom with one or two buttons:

$sidebar->addActionBar()
  ->withLeftButton(
    $left_button_text,
    $left_button_url
  )->withRightButton(
    $right_button_text,
    $right_button_url
  );

Complete Example¶

This will build a sidebar with a header, which has a button and two items underneath it:

$sidebar = ee('CP/Sidebar')->make();

$fortunes = $sidebar->addHeader(lang('fortunes'))
  ->withButton(lang('new'), ee('CP/URL', 'addons/settings/fortune_cookie/create'));

$fortunes_list = $fortunes->addBasicList();
$fortunes_list->addItem(lang('recent_fortunes'), ee('CP/URL', 'addons/settings/fortune_cookie/recent'));
$fortunes_list->addItem(lang('archived_fortunes'), ee('CP/URL', 'addons/settings/fortune_cookie/archived'));

Reorderable Folder Lists¶

Folder lists can be reordered:

$folder_list->canReorder();

Calling canReorder() will automatically bind the appropriate JavaScript and styles to the list to enable its folder items to be dragged and sorted. Reordering list items won’t cause them to stick from request to request, that’s something you would need to implement to suit your particular add-on. To hook into the sort event to perform custom operations on sort, set a callback like so:

EE.cp.folderList.onSort('list-name', function(list) {
  // Do as you wish with the passed list object
});

Where 'list-name' is the unique name you have your folder list. A jQuery object of the folder list element will be passed to the callback, in which you have access to various data about your list items. For example, you may want to gather the unique identifiers for the folder items and send them to an AJAX request, as we do for template groups:

// Reorder template groups
EE.cp.folderList.onSort('template-group', function(list) {
  // Create an array of template group names
  var template_groups = $.map($('> li', list), function(list_item) {
    return $(list_item).data('group_name');
  });

  $.ajax({
    url: EE.templage_groups_reorder_url,
    data: { 'groups': template_groups },
    type: 'POST',
    dataType: 'json'
  });
});

CP/Sidebar Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\Sidebar¶

EllisLab\ExpressionEngine\Service\Sidebar\Sidebar::make()¶

Makes a new Sidebar object.

Returns:	$this
Return type:	URL

EllisLab\ExpressionEngine\Service\Sidebar\Sidebar::render()¶

Renders the sidebar

Returns:	The rendered HTML of the sidebar
Return type:	String

EllisLab\ExpressionEngine\Service\Sidebar\Sidebar::addHeader($text, $url = NULL)¶

Adds a header to the sidebar

Parameters:	$text (string) – The text of the header $url (CP/URL or string) – An optional CPURL object or string containing the URL for the text.
Returns:	A new Header object.
Return type:	Header

EllisLab\ExpressionEngine\Service\Sidebar\Sidebar::addFolderList($name)¶

Adds a folder list to the sidebar

Parameters:	$name (string) – The name of the folder list
Returns:	A new FolderList object
Return type:	FolderList

EllisLab\ExpressionEngine\Service\Sidebar\Sidebar::addActionBar()¶

Adds an action bar to the bottom of the sidebar

Returns:	A new ActionBar object
Return type:	ActionBar

Header Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\Header¶

EllisLab\ExpressionEngine\Service\Sidebar\Header::withUrl($url)¶

Sets the URL property of the header

Parameters:	$url (CP/URL or string) – A CPURL object or string containing the URL for the header.
Returns:	$this
Return type:	Header

EllisLab\ExpressionEngine\Service\Sidebar\Header::urlIsExternal($external = TRUE)¶

Sets the URL is external property

Parameters:	$external (bool) – (optional) TRUE if it is external, FALSE if not
Returns:	$this
Return type:	Header

EllisLab\ExpressionEngine\Service\Sidebar\Header::isActive()¶

Marks the header as active

Returns:	$this
Return type:	Header

EllisLab\ExpressionEngine\Service\Sidebar\Header::withButton($text, $url)¶

Sets the button property of the header

Parameters:	$text (string) – The text of the button $url (CP/URL or string) – A CPURL object or string containing the URL for the button.
Returns:	$this
Return type:	Header

EllisLab\ExpressionEngine\Service\Sidebar\Header::addBasicList()¶

Adds a basic list under this header

Returns:	A new BasicList object
Return type:	BasicList

EllisLab\ExpressionEngine\Service\Sidebar\Header::addFolderList($name)¶

Adds a folder list under this header

Parameters:	$name (string) – The name of the folder list
Returns:	A new FolderList object
Return type:	FolderList

BasicList Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\BasicList¶

EllisLab\ExpressionEngine\Service\Sidebar\BasicList::addItem($text, $url = NULL)¶

Adds an item to the list

Parameters:	$text (string) – The text of the item $url (CP/URL or string) – A CPURL object or string containing the URL for the item.
Returns:	A new BasicItem object.
Return type:	BasicItem

BasicItem Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\BasicItem¶

EllisLab\ExpressionEngine\Service\Sidebar\BasicItem::withUrl($url)¶

Sets the URL property of the item

Parameters:	$url (CP/URL or string) – A CPURL object or string containing the URL for the item.
Returns:	$this
Return type:	BasicItem

EllisLab\ExpressionEngine\Service\Sidebar\BasicItem::urlIsExternal($external = TRUE)¶

Sets the URL is external property

Parameters:	$external (bool) – (optional) TRUE if it is external, FALSE if not
Returns:	$this
Return type:	BasicItem

EllisLab\ExpressionEngine\Service\Sidebar\BasicItem::isActive()¶

Marks the item as active

Returns:	$this
Return type:	BasicItem

EllisLab\ExpressionEngine\Service\Sidebar\BasicItem::asDeleteAction($modal_name = '')¶

Marks the item as a delete action

Parameters:	$modal_name (string) – The name of the modal this delete action will trigger
Returns:	$this
Return type:	BasicItem

FolderList Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\FolderList¶

EllisLab\ExpressionEngine\Service\Sidebar\FolderList::addItem($text, $url = NULL)¶

Adds an item to the list

Parameters:	$text (string) – The text of the item $url (CP/URL or string) – An optional CPURL object or string containing the URL for the item.
Returns:	A new FolderList object.
Return type:	FolderList

EllisLab\ExpressionEngine\Service\Sidebar\FolderList::withRemoveUrl($url)¶

Sets the URL to use when removing an item

Parameters:	$url (CP/URL or string) – A CPURL object or string containing the URL to use when removing an item.
Returns:	$this
Return type:	FolderList

EllisLab\ExpressionEngine\Service\Sidebar\FolderList::withRemovalKey($key)¶

Sets the name of variable passed with the removal action.

Parameters:	$key (string) – The name of the variable with.
Returns:	$this
Return type:	FolderList

EllisLab\ExpressionEngine\Service\Sidebar\FolderList::withNoResultsText($msg)¶

Sets the no results text which will display if this header’s list(s) are empty.

Parameters:	$msg (string) – The text to display when the list(s) are empty.
Returns:	$this
Return type:	FolderList

EllisLab\ExpressionEngine\Service\Sidebar\FolderList::canReorder()¶

Allows the folder list to be reordered.

Returns:	$this
Return type:	FolderList

FolderItem Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\FolderItem¶

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::withUrl($url)¶

Sets the URL property of the item

Parameters:	$url (CP/URL or string) – A CPURL object or string containing the URL for the item.
Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::urlIsExternal($external = TRUE)¶

Sets the URL is external property

Parameters:	$external (bool) – (optional) TRUE if it is external, FALSE if not
Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::isActive()¶

Marks the item as active

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::asDefaultItem()¶

Marks the item as default

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::canEdit()¶

Shows the edit button on the sidebar item.

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::cannotEdit()¶

Hides the edit button on the sidebar item.

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::canRemove()¶

Shows the delete button on the sidebar item.

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::cannotRemove()¶

Hides the delete button on the sidebar item.

Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::withEditUrl($url)¶

Sets the edit URL property of the item

Parameters:	$url (CP/URL or string) – A CPURL object or string containing the URL in order to edit the item.
Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::withRemoveConfirmation($msg)¶

Sets the remove confirmation message for this item.

Parameters:	$msg (string) – The message that will be displayed as the confirmation when attempting to remove this item
Returns:	$this
Return type:	FolderItem

EllisLab\ExpressionEngine\Service\Sidebar\FolderItem::identifiedBy($val)¶

Sets the identity value for this item which is used when this item is removed.

Parameters:	$val (string) – The value to place in the data attribute for use when removing an item
Returns:	$this
Return type:	FolderItem

ActionBar Methods¶

class EllisLab\ExpressionEngine\Service\Sidebar\ActionBar¶

EllisLab\ExpressionEngine\Service\Sidebar\ActionBar::withLeftButton($text, $url, $rel = NULL)¶

Sets the button that appears on the left side of the bar.

Parameters:	$text (string) – The text of the item $url (CP/URL or string) – A CPURL object or string containing the URL for the item. $rel (string) – Optional string to set on the rel= attribute of the button.
Returns:	$this
Return type:	ActionBar

EllisLab\ExpressionEngine\Service\Sidebar\ActionBar::withRightButton($text, $url, $rel = NULL)¶

Sets the button that appears on the right side of the bar.

Parameters:	$text (string) – The text of the item $url (CP/URL or string) – A CPURL object or string containing the URL for the item. $rel (string) – Optional string to set on the rel= attribute of the button.
Returns:	$this
Return type:	ActionBar