2016-03-30 02:17:28 +02:00
# How to customise the CMS tree
2012-03-29 23:10:59 +02:00
## Overview
2012-08-05 20:35:06 +02:00
The CMS tree for viewing hierarchical structures (mostly pages) is powered
by the [jstree ](http://jstree.com ) library. It is configured through
2017-10-06 17:00:32 +02:00
`client/src/legacy/LeftAndMain.Tree.js` in the `silverstripe/admin` module, as well as some
2012-08-05 20:35:06 +02:00
HTML5 metadata generated on its container (see the `data-hints` attribute).
2017-07-03 03:22:12 +02:00
The tree is rendered through [LeftAndMain::getSiteTreeFor() ](api:SilverStripe\Admin\LeftAndMain::getSiteTreeFor( )),
2012-03-29 23:10:59 +02:00
which recursively collects all nodes based on various filtering criteria.
2017-07-03 03:22:12 +02:00
The node strictly just has to implement the [Hierarchy ](api:SilverStripe\ORM\Hierarchy\Hierarchy ) extension,
but in the CMS usually is a [SiteTree ](api:SilverStripe\CMS\Model\SiteTree ) object.
2012-03-29 23:10:59 +02:00
2014-12-22 01:00:51 +01:00
## Add status lozenges to tree nodes
2012-03-29 23:10:59 +02:00
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 tree node will be typically rendered into html
code like this:
2017-08-03 02:51:32 +02:00
```ss
2017-10-27 04:38:27 +02:00
...
< ul >
2017-08-07 05:11:17 +02:00
...
2017-10-27 04:38:27 +02:00
< li id = "record-15" class = "class-Page closed jstree-leaf jstree-unchecked" data-id = "15" >
< ins class = "jstree-icon" > < / ins >
< a class = "" title = "Page type: Page" href = "{$AdminURL}page/edit/show/15" >
< ins class = "jstree-checkbox" > < / ins >
< ins class = "jstree-icon" > < / ins >
< span class = "text" >
< span class = "jstree-pageicon" > < / span >
< span class = "item" title = "Deleted" > New Page< / span >
< span class = "badge deletedonlive" > Deleted< / span >
< / span >
< / a >
< / li >
2017-08-07 05:11:17 +02:00
...
2017-10-27 04:38:27 +02:00
< / ul >
...
2017-08-03 02:51:32 +02:00
```
2014-11-07 20:43:57 +01:00
2012-03-29 23:10:59 +02:00
By applying the proper style sheet, the snippet html above could produce the look of:
2014-12-18 00:11:57 +01:00
![Page Node Screenshot ](../../../_images/tree_node.png "Page Node" )
2012-03-29 23:10:59 +02:00
2017-07-03 03:22:12 +02:00
SiteTree is a [DataObject ](api:SilverStripe\ORM\DataObject ) which is versioned by [Versioned ](api:SilverStripe\Versioned\Versioned ) extension.
2012-03-29 23:10:59 +02:00
Each node can optionally have publication status flags, e.g. "Removed from draft".
Each flag has a unique identifier, which is also used as a CSS class for easier styling.
Developers can easily add a new flag, delete or alter an existing flag on how it is looked
or changing the flag label. The customization of these lozenges could be done either through
2017-07-03 03:22:12 +02:00
inherited subclass or [DataExtension ](api:SilverStripe\ORM\DataExtension ). It is just really about how we change the return
2012-03-29 23:10:59 +02:00
value of function `SiteTree->getTreeTitle()` by two easily extendable methods
`SiteTree->getStatusClass()` and `SiteTree->getStatusFlags()` .
Note: Though the flag is not necessarily tie to its status of __publication__ and it could
be used for flagging anything you like, we should keep this lozenge to show version-related
status, while let `SiteTree->CMSTreeClasses()` to deal with other customised classes, which
will be used for the class attribute of < li> tag of the tree node.
2014-12-22 01:00:51 +01:00
### Add new flag
2012-03-29 23:10:59 +02:00
__Example: using a subclass__
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
use SilverStripe\CMS\Model\SiteTree;
2017-08-07 05:11:17 +02:00
2017-10-27 04:38:27 +02:00
class Page extends SiteTree
{
public function getScheduledToPublish()
2017-08-07 05:11:17 +02:00
{
2017-10-27 04:38:27 +02:00
// return either true or false
2017-08-07 05:11:17 +02:00
}
2017-10-27 04:38:27 +02:00
public function getStatusFlags($cached = true)
{
$flags = parent::getStatusFlags($cached);
$flags['scheduledtopublish'] = "Scheduled To Publish";
return $flags;
}
}
2017-08-03 02:51:32 +02:00
```
2012-03-29 23:10:59 +02:00
2017-07-03 03:22:12 +02:00
The above subclass of [SiteTree ](api:SilverStripe\CMS\Model\SiteTree ) will add a new flag for indicating its
2012-03-29 23:10:59 +02:00
__'Scheduled To Publish'__ status. The look of the page node will be changed
2014-12-18 00:11:57 +01:00
from ![Normal Page Node ](../../../_images/page_node_normal.png ) to ![Scheduled Page Node ](../../../_images/page_node_scheduled.png ). The getStatusFlags has an `updateStatusFlags()`
2012-03-29 23:10:59 +02:00
extension point, so the flags can be modified through `DataExtension` rather than
2014-04-23 13:39:57 +02:00
inheritance as well. Deleting existing flags works by simply unsetting the array key.