How to customise the CMS tree#

Overview#

The CMS tree for viewing hierarchical structures (mostly pages) is powered by the jstree library. It is configured through client/src/legacy/LeftAndMain.Tree.js in the silverstripe/admin module, as well as some HTML5 metadata generated on its container (see the data-hints attribute).

The tree is rendered through CMSMain::getTreeFor(), which recursively collects all nodes based on various filtering criteria. The node strictly just has to implement the Hierarchy extension, but in the CMS usually is a SiteTree object.

Add status flags to tree nodes#

A tree node in CMS could be rendered with lot of extra information but a node title, such as a link that wraps around the node title, a node's id which is given as id attribute of the node <li> tag, a extra checkbox beside the tree title, tree icon class or extra <span> tags showing the node status, etc. Silverstripe CMS tree node will be typically rendered into html code like this:

...
<ul>
    ...
    <li id="record-15" class="class-Page closed jstree-leaf jstree-unchecked" data-id="15">
    <ins class="jstree-icon">&nbsp;</ins>
        <a class="" title="Page type: Page" href="$AdminURL('page/edit/show/15')">
            <ins class="jstree-checkbox">&nbsp;</ins>
            <ins class="jstree-icon">&nbsp;</ins>
            <span class="text">
                <span class="jstree-recordicon"></span>
                <span class="item" title="Deleted">New Page</span>
                <span class="badge deletedonlive">Deleted</span>
            </span>
        </a>
    </li>
    ...
</ul>
...

By applying the proper style sheet, the snippet html above could produce the look of:

In the above screenshot "DELETED" is the status flag.

To learn how to add, remove, and update status flags see status flags.

Customising page icons#

The page tree in the CMS is a central element to manage page hierarchies, hence its display of pages can be customised as well. You can specify a custom page icon to make it easier for CMS authors to identify pages of this type, when navigating the tree or adding a new page:

namespace App\PageType;

use Page;

class HomePage extends Page
{
    private static $cms_icon_class = 'font-icon-p-home';

    // ...
}

The CMS uses an icon set from Fontastic. New icons may be requested and added to the core icon set. The benefit of having icons added to the core set is that you can use icons more consistently across different modules allowing every module to use a different icon with the same style.

You can also add your own icon by specifying an image path to override the Fontastic icon set:

namespace App\PageType;

use Page;

class HomePage extends Page
{
    private static $icon = 'app/images/homepage-icon.svg';

    // ...
}