Enable custom bullets/icons for specific menu items

We want 4.7 out the door ASAP, i'm changing this to a feature request for cvs not 4.7.0-beta2.

I had an email discussion with the menu maintainer several weeks ago on this topic. And he confirmed that it should be as easy as adding an 'icon' field to the menu structure in the existing menu hook. In other words, he didn't think there would be any changes in core. I have not yet tried this myself but I plan to give it a shot soon. Here's what the hook code would look like.

$items[] = array(
'path' => 'admin/user/create',
'title' => t('add user'),
'callback' => 'user_admin',
'access' => $admin_access,
'icon' => 'actions/contact-new.png',
'type' => MENU_LOCAL_TASK);

Enabling custom menu icons would be a useful addition. Likely the way to do this is through classes rather than hard-coded icon path references. Here's a rough and untested idea of some of the steps. To use this, we would add a 'class' attribute to a menu item definition:

$item[] = array(
  'path' => 'a/path',
  'class' => 'aclass',
  ...
);

I am very much in favor of including class information in menu items for optional use by menus.

Looks an interesting idea.

Have this been thought for cvs?

I'm reviving this old issue because there's some interest in getting this in core, due to #511286: D7UX: Implement customizable shortcuts.

Drupal currently provides the ability to add classes to menu links (and there are a number of contributed modules that exist to add icon support via this method). However, although this is the most flexible method from a theme perspective, it's not necessarily the best method from a module-developer's perspective. If I write a module and want to directly associate some default icons with the paths in my module, how do I do it? It seems like for that, a dedicated "icon" key in hook_menu() makes more sense.

Another interesting feature that the menu system provides is the ability to inherit icons. So I can define a default set of icons for admin/mymodule, or core can define a default icon for admin/config/media, and any menu items that exist under those paths would automatically inherit the default icon for that section (unless they provide their own). This is definitely useful for #511286: D7UX: Implement customizable shortcuts -- maybe less so in the general case, but I think it has some merit.

In any case, the attached patch (and screenshot) is a very rough initial implementation of the idea. Don't pay any attention to the theming - it looks quite ugly and I just used some nonsensical icons that already happened to be in core :) However, the basic idea of the patch is that icons can be specified in hook_menu(), inherited by their children if not overridden, and that it is possible to specify on a per-menu basis whether or not icons should be enabled and what image style to use for them (so that, for example, you could say toolbar shortcuts menu uses 60x60 pixel versions of the menu icons, the management menu uses 15x15 pixel versions of the same icons, and the navigation menu doesn't use icons at all).

This is not a complete implementation, but hopefully a good start. Currently the icons can be overridden or changed by themes because they are generated in theme functions, but it might be good to add more flexibility here (better classes, etc). Also, it currently only works for menu items that are themed as standard menu links, but there are other places (main/secondary menus, admin pages, the toolbar, etc) that might also want to support using the icons also. Finally, it's awfully tempting to add "icon callback" and "icon arguments" functionality to hook_menu() as well - so that you could then specify different icons for different nodes, for example - but that is probably overkill to try in one issue :)

There is not intended to be any user interface for changing icons as part of this patch - I suggest leaving that to #288179: Provide a user interface for assigning icons to menu items, and it's probably not going to happen for Drupal 7. For now, this is hopefully just about the ability for modules to define default icons for their menu items and for themes to use those icons, if they so choose.

executive summary:

the basic idea of the patch is that icons can be specified in hook_menu(), inherited by their children if not overridden, and that it is possible to specify on a per-menu basis whether or not icons should be enabled and what image style to use for them (so that, for example, you could say toolbar shortcuts menu uses 60x60 pixel versions of the menu icons, the management menu uses 15x15 pixel versions of the same icons, and the navigation menu doesn't use icons at all).
…
For now, this is just about the ability for modules to define default icons for their menu items and for themes to use those icons, if they so choose.

+1 subscribe etc. Agree on the non-UI for customisation part as well :-)

Reviewing the patch, I'd have some remarks and questions:

- so with the icon key being with hook_menu(), modules would have the opportunity to customize menu item icons by hook_menu_alter()-ing, right?
- do I see right, that themers would need to hack a theme_menu_link_icon() override to switch on $path, if they would like to replace any of the icons (but this theme function does not have enough information to distinguish between inherited and specifically set icons, so does not allow for fine grained replacement)
- also, this would enforce icon display on all rendering instances of a menu; maybe it would be overkill to prepare for this, but it would be useful to be able to tell the parent theme function to not render icons here or render icons here
- how do you envision the management of the menu_icon_support variable? core would predefine it with the shortcut bar menu and let contrib to work with it if adding more icon support for menus?
- I did not follow image style development that much; is it a policy now that whatever image handling we do, we add optional image style support as well? what's the usefulness of this feature here?

Re: image handling: Any decent icon package provides the different sizes for each icon itself. Scaling icons is horrible, they always need manual corrections to keep clarity. It'd be better if a specific size could be specified.

theme_menu_link_icon:

+++ includes/menu.inc	5 Oct 2009 22:53:48 -0000
@@ -1123,6 +1125,7 @@ function menu_tree_page_data($menu_name,
@@ -1329,10 +1332,46 @@ function theme_menu_link(array $element)
@@ -1329,10 +1332,46 @@ function theme_menu_link(array $element)
+    $output .= theme('menu_link_icon', $element['#icon'], $element['#original_link']['menu_name'], $element['#title'], $element['#title']);
...
+function theme_menu_link_icon($path, $menu, $alt = '', $title = '') {

I think this is all the info a themer could hope for in terms of overriding icons no? I can't think of any more extensible way to do this. What more info could we give a themer?

also, this would enforce icon display on all rendering instances of a menu; maybe it would be overkill to prepare for this, but it would be useful to be able to tell the parent theme function to not render icons here or render icons here

I agree, this is totally going to come up when you've got a menu in a block vs a menu at the top of the page. I know this is throwing a spanner in the works, but this is an argument for CSS based (background image) icons. Then, even if they were supposed to show, they could be selectively hidden depending on what region they are in without causing them to be downloaded. Maybe that's not incompatible with this approach...

how do you envision the management of the menu_icon_support variable? core would predefine it with the shortcut bar menu and let contrib to work with it if adding more icon support for menus?

This is a tough one and related to the point above... I guess what we'll end up seeing more often is $show_icons is more associated w/ where the menu is being showed than with the data in the menu itself. How could be best support it being on for a block, and off for a header or the reverse?

Even if we don't resolve the above, it can be easily gagged and would be really useful, so I support continuing with it if others like it. I don't see any problems with the code itself.

Marking it RTBJ. ;)

Currently this patch is optimized for the module developer who doesn't know much about icons. They list an image and they are done :) Other modules can easily replace or delete it, and themes can totally ignore it.

But I agree we need to think about what the minimal implementation is that would give more flexibility to themers.

1. Image handling

The 'icons' parameter could easily become an array of different-sized icons rather than a single image (but that's more work for module developers). Having never designed icons, I defer to the experience of people who have.... But the reason for using image module is that it's more flexible - Do standard icon sizes really work when you know nothing about the theme that they will be used in? Suppose I resize the text in my theme a little; won't I want to resize all my icons a bit too?

Also keep in mind that the image module has some pretty advanced effects. I can see how it could get tricky when the icons get small and each pixel becomes very important, though.

2. CSS background images vs a theme function

As Jacob suggested, it would be great to do this more with classes and background images. If we want to simultaneously support different-sized icons, though, the fact that each icon has a non-constant filename seems like it might take us down the path of dynamically-generated CSS.... which is not really that hard, but I'm not sure if we want to go there or not.

3. Per-menu on-off switch

Regarding having the variable be per-menu vs per-block vs per-page-region: Given that you often only display a menu in one place at a time (for each theme), I'm not sure it's that bad to have the variable be per-menu? If you move the menu to a different region of the page and no longer want it to have icons, you can change the variable then.

However, we should perhaps change this from a regular variable into a theme setting.

.

Oh man, that was annoying. I spent way too long today trying to figure out how the hell this patch was causing the help test to fail.

Since the Help test is one of the "pretending to be a web browser" tests, it checks for <h1 class="page-title">.... This patch set the default theme to garland so we could see what was going on, which uses h2. Awesome. When the simpletest bot installs Drupal from scratch, it sees and h2 tag at admin/help/*, and that was causing it to fail.

So, here is a patch, with the number of lines changed (1) roughly equivalent to how long it took me to figure this out.

Sub.

#138489: named and themed icons is older but has no action so marked that a duplicate.

The Menu attributes module allows you to specify specific attributes (class, ID, etc) per menu item. This allows you to add a unique bullet or icon to any menu item.

Sure... and the Toolbar module in core does that too (for menu items displayed there). But as discussed above, that's not quite what this issue is about.

Nor should you have to install a separate module to have good classes and IDs for themers to work with :)

I dont think we should reconsider this for Drupal 8, its handled in contrib and unless we see a usecase for core - this should be fine in contrib.

How is this handled in contrib?

The closest I've seen to a successful generic implementation of icons in contrib is http://drupal.org/project/rubik - however the icons are limited to a hardcoded list (mostly or entirely just menu items provided by Drupal core). This can't scale to thousands of contrib modules unless there is an agreed-upon standard and way of defining them.

A standard could theoretically emerge in contrib but usually such things have to be in core.

And at an absolute minimum, core should be providing good classes to let people do this via CSS.

The proper way to do this for D8 is to use CSS selectors of

nav [href*=about]

I'd like to open this again. Looking at the ways it has been done so far ends up with VERY specific coding that is difficult to port between themes besides being difficult to support across multiple languages. The MENU_ICONS module provides one good solution but it requires icon images. It would be much more flexible and efficient to add a "data-" attribute to menu items and an icon font to create 'iconic' menus. This can be done in a contrib module but with the changes going on in drupal 8 it is hard to know exactly where to do it. There should be more flexibility in adding attributes to drupal menu items and this feature could greatly enhance menu styling.
If this isn't important feel free to close it again.

Since there are already modules for that and a lot of things have changed the way to handle icons regarding accessibility and mobile first we should close this one.