ENHANCEMENT: add optional custom menu icon to CMS main menu

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 @@ static function menu_title_for_class($class) {
 		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 @@ public function MainMenu($cached = true) {
 			// 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 @@ public function MainMenu($cached = true) {
 					} 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 @@ public function MainMenu($cached = true) {
 					)));
 				}
 			}
+			if ($menuIconStyling) Requirements::CustomCSS($menuIconStyling);
 
 			$this->_cache_MainMenu = $menu;
 		}
@@ -1614,4 +1648,4 @@ function setIsCurrent($bool) {
 		return $this;
 	}
 
-}
+}

docs/en/howto/customize-cms-menu.md

@@ -0,0 +1,54 @@
+# Howto customize the CMS Menu #
+
+## Introduction ##
+
+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, title and the default 'cogs' icon included.
+But we can easily change that behaviour by using the static `$menu-title` and `$menu-icon` variables to
+provide a custom title and icon.
+
+The most popular extension of LeftAndMain is by far 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: the icon ##
+
+First we'll need a custom icon. For this purpose SilverStripe uses 16x16 black-and-transparent png icons.
+In this case we'll place the icon in mysite/images, but you are free to use any location, as long as you 
+provide the right path.
+
+## ProductAdmin ##
+
+	:::php
+	class ProductAdmin extends ModelAdmin {
+		public static $managed_models = array('Product','Category'); // Can manage multiple models
+ 		static $url_segment = 'products'; // Linked as /admin/products/	
+
+		static $menu_title = 'My Product Admin';
+		static $menu-icon = 'mysite/images/product-icon.png'; 
+	}
+
+## Language file: MENUTITLE ##
+
+By default, when displaying the title for the menu item, SilverStripe will look for the `MENUTITLE` entity in 
+your module's current language file and use that. This is true even for the default language (lang/en.yml):  
+
+	:::yml
+	...
+	ProductAdmin:
+		MENUTITLE: 'My Product Admin'
+
+Only when no language file is found for the current language, or the MENUITEM entity is not present in them, will 
+$menu_title be used directly. 
+
+The correct value for MENUTITLE will be created automatically if you use 
+[i18nTextCollector](../reference/ii8n#collecting-text) to create your languagefile. 
+If you're changing the menu title for a module with existing languagefiles, please check the values for 
+MENUTITLE and adapt.
+
+For more information on language and translations,please refer to [i18n](../reference/ii8n).
+
+## Other changes ##
+
+Other changes to the appearance of the menu buttons, or any other parts of the CMS for that matter, should 
+preferrably be done using stylesheets. Have a look at [How to extend the CMS interface](extend-cms-interface) for 
+an extensive howto on extending the CMS.

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