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

make()

Makes a new Sidebar object.

render()

Renders the sidebar

addHeader($text, $url = NULL)

Adds a header to the sidebar

addItem($text, $url = NULL)

Adds a BasicItem to the sidebar

addDivider()

Adds a divider to the sidebar

addFolderList($name)

Adds a folder list to the sidebar

addActionBar()

Adds an action bar to the bottom of the sidebar

Header Methods

class ExpressionEngine\Service\Sidebar\Header

isActive()

Marks the header as active

withButton($text, $url)

Sets the button property of the header

addBasicList()

Adds a basic list under this header

addFolderList($name)

Adds a folder list under this header

withUrl($url)

Sets the URL property of the header

Deprecated since v6.0.0. When a link is needed, a sidebar item should be used instead: $sidebar->addItem(). Headers should be used to mark sections of the sidebar, not as links.

urlIsExternal($external = TRUE)

Sets the URL is external property

Deprecated since v6.0.0. When a link is needed, a sidebar item should be used instead: $sidebar->addItem(). Headers should be used to mark sections of the sidebar, not as links.

BasicList Methods

addItem($text, $url = NULL)

Adds an item to the list

BasicItem Methods

class ExpressionEngine\Service\Sidebar\BasicItem

withIcon($icon)

Sets the icon for the item

withUrl($url)

Sets the URL property of the item

urlIsExternal($external = TRUE)

Sets the URL is external property

isActive()

Marks the item as active

asDeleteAction($modal_name = '')

Marks the item as a delete action

FolderList Methods

class ExpressionEngine\Service\Sidebar\FolderList

addItem($text, $url = NULL)

Adds an item to the list

withRemoveUrl($url)

Sets the URL to use when removing an item

withRemovalKey($key)

Sets the name of variable passed with the removal action.

withNoResultsText($msg)

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

canReorder()

Allows the folder list to be reordered.

FolderItem Methods

class ExpressionEngine\Service\Sidebar\FolderItem

withIcon($icon)

Sets the icon for the item

withUrl($url)

Sets the URL property of the item

urlIsExternal($external = TRUE)

Sets the URL is external property

isActive()

Marks the item as active

asDefaultItem()

Marks the item as default

canEdit()

Shows the edit button on the sidebar item.

cannotEdit()

Hides the edit button on the sidebar item.

canRemove()

Shows the delete button on the sidebar item.

cannotRemove()

Hides the delete button on the sidebar item.

withEditUrl($url)

Sets the edit URL property of the item

withRemoveConfirmation($msg)

Sets the remove confirmation message for this item.

identifiedBy($val)

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

ActionBar Methods

class ExpressionEngine\Service\Sidebar\ActionBar

withLeftButton($text, $url, $rel = NULL)

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

withRightButton($text, $url, $rel = NULL)

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

---

ExpressionEngine 7 Docs
©2002–2024 Packet Tide,LLC. Edit this page