diff --git a/docs/en/_images/page_node_deleted_as_normal.png b/docs/en/_images/page_node_deleted_as_normal.png new file mode 100644 index 00000000000..0b9424d6fc9 Binary files /dev/null and b/docs/en/_images/page_node_deleted_as_normal.png differ diff --git a/docs/en/_images/page_node_normal.png b/docs/en/_images/page_node_normal.png new file mode 100644 index 00000000000..0b9424d6fc9 Binary files /dev/null and b/docs/en/_images/page_node_normal.png differ diff --git a/docs/en/_images/page_node_removed.png b/docs/en/_images/page_node_removed.png new file mode 100644 index 00000000000..9012670081c Binary files /dev/null and b/docs/en/_images/page_node_removed.png differ diff --git a/docs/en/_images/page_node_scheduled.png b/docs/en/_images/page_node_scheduled.png new file mode 100644 index 00000000000..44f4ee3aaaa Binary files /dev/null and b/docs/en/_images/page_node_scheduled.png differ diff --git a/docs/en/_images/sss.png b/docs/en/_images/sss.png new file mode 100644 index 00000000000..6c7342c70d8 Binary files /dev/null and b/docs/en/_images/sss.png differ diff --git a/docs/en/_images/tree_node.png b/docs/en/_images/tree_node.png new file mode 100644 index 00000000000..f9991155e93 Binary files /dev/null and b/docs/en/_images/tree_node.png differ diff --git a/docs/en/howto/customize-cms-tree.md b/docs/en/howto/customize-cms-tree.md new file mode 100644 index 00000000000..450c9af50b4 --- /dev/null +++ b/docs/en/howto/customize-cms-tree.md @@ -0,0 +1,76 @@ +# How to customize the CMS tree # + +## Overview + +The tree is rendered through `[api:LeftAndMain->getSiteTreeFor()]`, +which recursively collects all nodes based on various filtering criteria. +The node strictly just has to implement the `[api:Hierarchy]` extension, +but in the CMS usually is a `[api:SiteTree]` object. + +## Add status lozenges 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 tree node will be typically rendered into html +code like this: + + :::ss + ... + + ... + +By applying the proper style sheet, the snippet html above could produce the look of: +![Page Node Screenshot](../_images/tree_node.png "Page Node") + +SiteTree is a `[api:DataObject]` which is versioned by `[api:Versioned]` extension. +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 +inherited subclass or `[api:DataExtension]`. It is just really about how we change the return +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. + +### Add new flag ### +__Example: using a subclass__ + + :::php + class Page extends SiteTree { + function getScheduledToPublish(){ + // return either true or false + } + + function getStatusFlags(){ + $flags = parent::getStatusFlags(); + $flags['scheduledtopublish'] = "Scheduled To Publish"; + return $flags; + } + } + +The above subclass of `[api:SiteTree]` will add a new flag for indicating its +__'Scheduled To Publish'__ status. The look of the page node will be changed +from ![Normal Page Node](../_images/page_node_normal.png") to ![Scheduled Page Node](../_images/page_node_scheduled.png). The getStatusFlags has an `updateStatusFlags()` +extension point, so the flags can be modified through `DataExtension` rather than +inheritance as well. Deleting existing flags works by simply unsetting the array key. \ No newline at end of file diff --git a/docs/en/howto/index.md b/docs/en/howto/index.md index 5a330898653..6c5e979a1c9 100644 --- a/docs/en/howto/index.md +++ b/docs/en/howto/index.md @@ -11,6 +11,7 @@ the language and functions which are used in the guides. * [Grouping DataObjectSets](grouping-dataobjectsets). Group results in a [api:DataObjectSet] to create sub sections. * [PHPUnit Configuration](phpunit-configuration). How to setup your testing environment with PHPUnit * [Extend the CMS Interface](extend-cms-interface). +* [How to customize CMS Tree](customize-cms-tree). ## Feedback diff --git a/docs/en/reference/cms-architecture.md b/docs/en/reference/cms-architecture.md index 63f6117ff3f..076b5f8f33e 100644 --- a/docs/en/reference/cms-architecture.md +++ b/docs/en/reference/cms-architecture.md @@ -259,5 +259,6 @@ Note: You can see any additional HTTP headers through the web developer tools in ## Related * [Howto: Extend the CMS Interface](../howto/extend-cms-interface) + * [Howto: Customize the CMS tree](../howto/customize-cms-tree) * [Reference: ModelAdmin](../reference/modeladmin) * [Topics: Rich Text Editing](../topics/rich-text-editing) \ No newline at end of file