diff --git a/docs/en/howto/extend-cms-interface.md b/docs/en/howto/extend-cms-interface.md index 4a6500ea8..f7e73c3a2 100644 --- a/docs/en/howto/extend-cms-interface.md +++ b/docs/en/howto/extend-cms-interface.md @@ -4,54 +4,136 @@ The CMS interface works just like any other part of your website: It consists of PHP controllers, templates, CSS stylesheets and JavaScript. Because it uses the same base elements, -it is relatively easy to extend. +it is relatively easy to extend. +As an example, we're going to add a permanent "bookmarks" bar to popular pages at the bottom of the CMS. +A page can be bookmarked by a CMS author through a simple checkbox. -The CMS is built on principles of "[unobtrusive JavaScript](http://en.wikipedia.org/wiki/Unobtrusive_JavaScript)". +## Overload a CMS template ## -## Add a panel to the CMS interface ## - -The CMS uses a JavaScript layout manager called [jLayout](http://www.bramstein.com/projects/jlayout/), -which allows us to build complex layouts with minimal JavaScript configuration. -As an example, we're going to add a permanent "quicklinks" bar to popular pages at the bottom -of the "Pages" area (but leave it out of other areas like "Users"). - -CMS templates are inherited based on their controllers, similiar to subclasses of -the common `Page` object (a new PHP class `MyPage` will look for a `MyPage.ss` template). -We can use this fact to target one specific area only: the `CMSPageEditController` class. - -1. Create a new template in `mysite/templates/CMSPageEditController.ss` -2. Copy the template markup of the base implementation at `sapphire/admin/templates/LeftAndMain.ss` into the file. -It will automatically be picked up by the CMS logic. -3. Add a new section after the `$Content` tag: +First of all, create a new folder structure in your SilverStripe webroot, which will +form our module for this example. - :::ss - ... -
- $Menu - $Content -
- -
+ cms/ + sapphire/ + zzz_admin/ + _config.php + code/ + css/ + admin/ + templates/ + +Note: The `zzz_` prefix and `admin/` subfolder are only a temporary measure necessary to ensure our templates +are included *after* the original CMS templates. At the moment, you can't use the `mysite/` folder +to achieve the same result. + +CMS templates are inherited based on their controllers, similar to subclasses of +the common `Page` object (a new PHP class `MyPage` will look for a `MyPage.ss` template). +We can use this to create a different base template with `LeftAndMain.ss` +(which corresponds to the `LeftAndMain` PHP controller class). + +Copy the template markup of the base implementation at `sapphire/admin/templates/LeftAndMain.ss` into `zzz_admin/admin/templates/LeftAndMain.ss`. It will automatically be picked up by the CMS logic. Add a new section after the `$Content` tag: + + :::ss + ... +
+ $Menu + $Content +
+
- ... +
+ ... + +Refresh the CMS interface with `admin/?flush=all`, and you should see the new bottom bar with some hardcoded links. +We'll make these dynamic further down. -4. Create a new `mysite/css/CMSPageEditController.css` file and paste the following content: - - :::css - .cms-bottom-bar {height: 20px;} - -5. Load the new CSS file into the CMS, by adding the following line to `mysite/_config.php`: - - :::php - LeftAndMain::require_css('mysite/css/CMSPageEditController.css'); - -Done! You might have noticed that we didn't write any JavaScript to add our layout manager. +You might have noticed that we didn't write any JavaScript to add our layout manager. The important piece of information is the `south` class in our new `
` structure, plus the height value in our CSS. It instructs the existing parent layout how to render the element. +This layout manager ([jLayout](http://www.bramstein.com/projects/jlayout/)) +allows us to build complex layouts with minimal JavaScript configuration. + +## Include custom CSS in the CMS -The page list itself is hardcoded for now, we'll leave it to the reader to make -this a dynamic and prettier list. Hint: Take a look at the [LeftAndMain](../reference/leftandmain) documentation to find -out how to subclass and replace an admin interface with your own PHP code. \ No newline at end of file +In order to show the links in one line, we'll add some CSS, and get it to load with the CMS interface. +Paste the following content into a new file called `zzz_mysite/css/BookmarkedPages.css`: + + :::css + .cms-bottom-bar {height: 20px; padding: 5px; background: #C6D7DF;} + .cms-bottom-bar ul {list-style: none; margin: 0; padding: 0;} + .cms-bottom-bar ul li {float: left; margin-left: 1em;} + .cms-bottom-bar a {color: #444444;} + +Load the new CSS file into the CMS, by adding the following line to `zzz_admin/_config.php`: + + :::php + array('IsBookmarked' => 'Boolean')); + } + function updateCMSFields(&$fields) { + $fields->addFieldToTab('Root.Main', + new CheckboxField('IsBookmarked', "Show in CMS bookmarks?") + ); + } + } + +Enable the extension with the following line in `zzz_mysite/_config.php`: + + :::php + Object::add_extension('SiteTree', 'BookmarkedPageExtension'); + +In order to add the field to the database, run a `dev/build/?flush=all`. +Refresh the CMS, open a page for editing and you should see the new checkbox. + +## Retrieve the list of bookmarks from the database + +One piece in the puzzle is still missing: How do we get the list of bookmarked +pages from the datbase into the template we've already created (with hardcoded links)? +Again, we extend a core class: The main CMS controller called `LeftAndMain`. + +Add the following code to a new file `zzz_admin/code/BookmarkedLeftAndMainExtension.php`; + + :::php + where('"IsBookmarked" = 1'); + } + } + +Enable the extension with the following line in `zzz_mysite/_config.php`: + + :::php + Object::add_extension('LeftAndMain', 'BookmarkedPagesLeftAndMainExtension'); + +As the last step, replace the hardcoded links with our list from the database. +Find the `