From 82500dd4c4c608d858fce3683035e130be6b1a3b Mon Sep 17 00:00:00 2001 From: martimiz Date: Sun, 19 Aug 2012 14:14:41 +0200 Subject: [PATCH] NEW Custom menu icons for the CMS main menu Add optional custom menu icons to the CMS main menu for every class extending LeftAndMain (ModelAdmin). Works by setting optional static $menu_icon = '/path/to/image' and providing custom styling for added icons. Works for the menu as well as icon in the right-side (GridField) pane header. --- admin/code/LeftAndMain.php | 34 +++++++++++++++++++++++++ docs/en/howto/customize-cms-menu.md | 39 +++++++++++++++++++++++++++++ docs/en/howto/index.md | 5 ++++ 3 files changed, 78 insertions(+) create mode 100644 docs/en/howto/customize-cms-menu.md diff --git a/admin/code/LeftAndMain.php b/admin/code/LeftAndMain.php index a923ab6cd..241e74ef6 100644 --- a/admin/code/LeftAndMain.php +++ b/admin/code/LeftAndMain.php @@ -36,6 +36,11 @@ class LeftAndMain extends Controller implements PermissionProvider { * @var string */ static $menu_title; + + /** + * @var string + */ + static $menu_icon; /** * @var int @@ -432,6 +437,22 @@ class LeftAndMain extends Controller implements PermissionProvider { if(!$title) $title = preg_replace('/Admin$/', '', $class); return $title; } + + /** + * Return styling for the menu icon, if a custom icon is set for this class + * + * Example: static $menu-icon = '/path/to/image/'; + * @param type $class + * @return string + */ + static function menu_icon_for_class($class) { + $icon = Config::inst()->get($class, 'menu_icon', Config::FIRST_SET); + if (!empty($icon)) { + $class = strtolower($class); + return ".icon.icon-16.icon-{$class} { background: url('{$icon}'); } "; + } + return ''; + } public function show($request) { // TODO Necessary for TableListField URLs to work properly @@ -486,6 +507,10 @@ class LeftAndMain extends Controller implements PermissionProvider { // Encode into DO set $menu = new ArrayList(); $menuItems = CMSMenu::get_viewable_menu_items(); + + // extra styling for custom menu-icons + $menuIconStyling = ''; + if($menuItems) { foreach($menuItems as $code => $menuItem) { // alternate permission checks (in addition to LeftAndMain->canView()) @@ -526,6 +551,14 @@ class LeftAndMain extends Controller implements PermissionProvider { } else { $title = $menuItem->title; } + + // Provide styling for custom $menu-icon. Done here instead of in + // CMSMenu::populate_menu(), because the icon is part of + // the CMS right pane for the specified class as well... + if($menuItem->controller) { + $menuIcon = LeftAndMain::menu_icon_for_class($menuItem->controller); + if (!empty($menuIcon)) $menuIconStyling .= $menuIcon; + } $menu->push(new ArrayData(array( "MenuItem" => $menuItem, @@ -536,6 +569,7 @@ class LeftAndMain extends Controller implements PermissionProvider { ))); } } + if ($menuIconStyling) Requirements::customCSS($menuIconStyling); $this->_cache_MainMenu = $menu; } diff --git a/docs/en/howto/customize-cms-menu.md b/docs/en/howto/customize-cms-menu.md new file mode 100644 index 000000000..815ca469d --- /dev/null +++ b/docs/en/howto/customize-cms-menu.md @@ -0,0 +1,39 @@ +# How to customize the CMS Menu # + +## Defining a Custom Icon ## + +Every time you add a new extension of the `api:LeftAndMain` class to the CMS, SilverStripe will automatically create a new menu-item for it, with a default title and icon. +We can easily change that behaviour by using the static `$menu_title` and `$menu_icon` statics to +provide a custom title and icon. + +The most popular extension of LeftAndMain is the `api:ModelAdmin` class, so we'll use that for an example. +We'll take the `ProductAdmin` class used in the [ModelAdmin reference](../reference/modeladmin#setup). + +First we'll need a custom icon. For this purpose SilverStripe uses 16x16 black-and-transparent PNG graphics. +In this case we'll place the icon in `mysite/images`, but you are free to use any location. + + :::php + class ProductAdmin extends ModelAdmin { + // ... + static $menu_icon = 'mysite/images/product-icon.png'; + } + +## Defining a Custom Title ## + +The title of menu entries is configured through the `$menu_title` static. +If its not defined, the CMS falls back to using the class name of the controller, +removing the "Admin" bit at the end. + + :::php + class ProductAdmin extends ModelAdmin { + // ... + static $menu_title = 'My Custom Admin'; + } + +In order to localize the menu title in different languages, use the `.MENUTITLE` +entity name, which is automatically created when running the i18n text collection. +For more information on language and translations, please refer to the [i18n](../reference/ii8n) docs. + +## Related + + * [How to extend the CMS interface](extend-cms-interface) \ No newline at end of file diff --git a/docs/en/howto/index.md b/docs/en/howto/index.md index f57f0ab75..570e8a077 100644 --- a/docs/en/howto/index.md +++ b/docs/en/howto/index.md @@ -12,6 +12,11 @@ the language and functions which are used in the guides. * [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). +* [Cache control](cache-control). Override the default PHP cache-control settings. +* [Howto customize the CMS menu](customize-cms-menu). +* [How to create a navigation menu](navigation-menu). Create primary navigation for your website. +* [Paginating A List](pagination). Add pagination for an SS_List object. +* [How to make a simple contact form](simple-contact-form). ## Feedback