CP/Sidebar Service

Automatically Created Sidebars

If you are automatically generating a sidebar in your add-on you can use either of these methods to customize the sidebar further:

• Modify the sidebar on every page load in the in the process() method of your ControlPanel/Routes/Sidebar.php file. The sidebar object is available using $this->getSidebar() You can also loop through each sidebar item with $this->getItems()`
• Modify the sidebar only when a specific route is loaded by accessing the sidebar instance in the process() function of the route file (ControlPanel/Routes/[route_name].php).You can modify the sidebar item connected to the current route by using $this->getCurrentSidebarItem() with the BasicItem Methods listed below. You can also use $this->getSidebar() to get the entire sidebar instance.

Simple Example

// The Control Panel's left sidebar is built with the Sidebar Service:
$sidebar = ee('CP/Sidebar')->make();

// You can add items:
$item = $sidebar->addItem(lang('new'), ee('CP/URL', 'addons/settings/fortune_cookie/create'));

// Items can have an icon:
$item->withIcon('truck');

// Items may be marked as active:
$item->isActive();

// You can add dividers:
$sidebar->addDivider();

// You can add a header:
$header = $sidebar->addHeader('Settings');

// 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);

// 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);

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.template_groups_reorder_url,
    data: { 'groups': template_groups },
    type: 'POST',
    dataType: 'json'
  });
});

CP/Sidebar Methods

class ExpressionEngine\Service\Sidebar\Sidebar

Header Methods

class ExpressionEngine\Service\Sidebar\Header

BasicList Methods

BasicItem Methods

class ExpressionEngine\Service\Sidebar\BasicItem

FolderList Methods

class ExpressionEngine\Service\Sidebar\FolderList

FolderItem Methods

class ExpressionEngine\Service\Sidebar\FolderItem

ActionBar Methods

class ExpressionEngine\Service\Sidebar\ActionBar