Modifying the administrator left hand menu

Overview

Preside provides a simple mechanism for configuring the left hand menu of the administrator, either to add new main navigational sections, take existing ones away or to modify the order of menu items.

Configuration

Each top level item of the menu is stored in an array that is set in settings.adminSideBarItems in Config.cfc. The core implementation looks like this:

component {

    public void function configure() {

        // ... other settings ...

        settings.adminSideBarItems = [
              "sitetree"
            , "assetmanager"
            , "datamanager"
            , "usermanager"
            , "websiteUserManager"
            , "systemConfiguration"
            , "updateManager"
        ];

        // ... other settings ...

    }
}

Menu items

As of 10.17.0 each menu item should have a corresponding entry in the settings.adminMenuItems struct.

See Configuring admin menu items for documentation on specifying a menu item.

Pre 10.17.0 implementation (still supported)

Prior to 10.17.0, all side bar items are implemented as a view that lives under a /views/admin/layout/sidebar/ folder. This method is still supported, but deprecated in favour of the Admin menu items method above.

For example, for a 'sitetree' item, there existed a view at /views/admin/layout/sidebar/sitetree.cfm that looked like this:

// /views/admin/layout/sidebar/sitetree.cfm

if ( hasCmsPermission( "sitetree.navigate" ) ) {
    Echo( renderView(
          view = "/admin/layout/sidebar/_menuItem"
        , args = {
              active  = ListLast( event.getCurrentHandler(), ".") eq "sitetree"
            , link    = event.buildAdminLink( linkTo="sitetree" )
            , gotoKey = "s"
            , icon    = "fa-sitemap"
            , title   = translateResource( 'cms:sitetree' )
          }
    ) );
}

Core view helpers

There are two core views that can be used when rendering your menu items, /admin/layout/sidebar/_menuItem and /admin/layout/sidebar/_subMenuItem.

/admin/layout/sidebar/_menuItem

Renders a top level menu item.

Arguments

Argument	Description
active	Boolean. Whether or not the current page lives within this part of the CMS.
link	Where this menu item points to. Not needed when the menu item has a submenu.
title	Title of the menu item
icon	Icon class for the menu item. We use font awesome, so "fa-users" for example.
subMenu	Rendered submenu items.
subMenuItems	Array of sub menu items to render (alternative to supplying a rendered sub menu). Each item should be a struct with `link`, `title` and optional `gotoKey` keys
gotoKey	Optional key that when used in combination with the `g` key, will send the user to the item's link. e.g. `g+s` takes you to the site tree.

Example

<cfscript>
    subMenuItems = [];

    if ( hasCmsPermission( "mynewsubfeature.access" ) ) {
        subMenuItems.append( {
            link  = event.buildAdminLink( linkTo="mynewsubfeature" )
            , title = translateResource( uri="mynewsubfeature:menu.title" )
        } );
    }

    if ( hasCmsPermission( "myothernewsubfeature.access" ) ) {
        subMenuItems.append( {
              link  = event.buildAdminLink( linkTo="myothernewsubfeature" )
            , title = translateResource( uri="myothernewsubfeature:menu.title" )
        } );
    }
</cfscript>

#renderView( view="/admin/layout/sidebar/_menuItem", args={
      active       = ReFindNoCase( "my(other)?newsubfeature$", event.getCurrentHandler() )
    , title        = translateResource( uri="mynewfeature:menu.title" )
    , icon         = "fa-world-domination"
    , subMenuItems = subMenuItems
} )#

/admin/layout/sidebar/_subMenuItem

Renders a sub menu item.

Arguments

Argument	Description
link	Where this menu item points to.
title	Title of the menu item
gotoKey	Optional key that when used in combination with the `g` key, will send the user to the item's link. e.g. `g+s` takes you to the site tree.

Example

<cfif hasCmsPermission( "mynewsubfeature.access" )>
    #renderView( view="/admin/layout/sidebar/_subMenuItem", args={
          link    = event.buildAdminLink( linkTo="mynewsubfeature" )
        , title   = translateResource( uri="mynewsubfeature:menu.title" )
        , gotoKey = "f"
    } )#
</cfif>

Examples

Adding a new item

Firstly, add the item to our array of sidebar items in your site or extension's Config.cfc:

// ...

settings.adminSideBarItems.append( "mynewfeature" );

// ...

Finally, create the view for the side bar item:

<!-- /views/admin/layout/sidebar/mynewfeature.cfm -->
<cfif hasCmsPermission( "mynewfeature.access" )>
    <cfoutput>
        #renderView( view="/admin/layout/sidebar/_menuItem", args={
              active       = ReFindNoCase( "mynewfeature$", event.getCurrentHandler() )
            , title        = translateResource( uri="mynewfeature:menu.title" )
            , link         = event.buildAdminLink( linkTo="mynewfeature" )
            , icon         = "fa-world-domination"
            , subMenuItems = subMenuItems
        } )#
    </cfoutput>
</cfif>

Info

In order for the calls to hasCmsPermission() and translateResource() to do anything useful, you will need to have setup the necessary permission keys (see permissioning) and resource bundle keys (see i18n).

Remove an existing item

In your site or extension's Config.cfc file:

// ...

// delete the site tree menu item, for example:
settings.adminSideBarItems.delete( "sitetree" );

// ...