CP/Sidebar Service

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

make()

Makes a new Sidebar object.

render()

Renders the sidebar

addHeader($text, $url = NULL)

Adds a header 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 EllisLab\ExpressionEngine\Service\Sidebar\Header

withUrl($url)

Sets the URL property of the header

urlIsExternal($external = TRUE)

Sets the URL is external property

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

BasicList Methods

addItem($text, $url = NULL)

Adds an item to the list

BasicItem Methods

class EllisLab\ExpressionEngine\Service\Sidebar\BasicItem

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 EllisLab\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 EllisLab\ExpressionEngine\Service\Sidebar\FolderItem

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 EllisLab\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 5.4.2 Docs
©2002–2021 Packet Tide,LLC. Edit this page