Skip to content
Browse files

MINOR Documentation for CMS tree and new SiteTree->getStatusFlags()

  • Loading branch information...
1 parent 40d7312 commit 63ff91e41b6af077823794119fc8d62b37e64fea @normann normann committed with chillu
View
BIN docs/en/_images/page_node_deleted_as_normal.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN docs/en/_images/page_node_normal.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN docs/en/_images/page_node_removed.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN docs/en/_images/page_node_scheduled.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN docs/en/_images/sss.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN docs/en/_images/tree_node.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
76 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
+ ...
+ <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="admin/page/edit/show/15">
+ <ins class="jstree-checkbox">&nbsp;</ins>
+ <ins class="jstree-icon">&nbsp;</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>
+ ...
+ </ul>
+ ...
+
+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 &lt;li&gt; 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.
View
1 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
View
1 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)

0 comments on commit 63ff91e

Please sign in to comment.
Something went wrong with that request. Please try again.