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

@@ -37,6 +37,11 @@ class LeftAndMain extends Controller implements PermissionProvider {
 	 */
 	static $menu_title;
 
+	/**
+	 * @var string
+	 */
+	static $menu_icon;
+	
 	/**
 	 * @var int
 	 */
@@ -433,6 +438,22 @@ class LeftAndMain extends Controller implements PermissionProvider {
 		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
 		if($request->param('ID')) $this->setCurrentPageID($request->param('ID'));
@@ -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())
@@ -527,6 +552,14 @@ class LeftAndMain extends Controller implements PermissionProvider {
 						$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,
 						"Title" => Convert::raw2xml($title),
@@ -536,6 +569,7 @@ class LeftAndMain extends Controller implements PermissionProvider {
 					)));
 				}
 			}
+			if ($menuIconStyling) Requirements::customCSS($menuIconStyling);
 
 			$this->_cache_MainMenu = $menu;
 		}

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 `<classname>.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)

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