Add icon support for widgets on the admin page and customize screens

[westonruter]

With the incorporation of live widget previews (widget customizer), an available widget browser is displayed which lists all widgets along with a dashicon for each. These icons should be incorporated into the widgets admin page now, as well.

[westonruter]

Work has started for this feature in the Widget Customizer plugin and the Better Widgets plugin.

[westonruter]

We'll be able to override the default wp_widget_control output to add support for the icons when #26661 is implemented.

[westonruter]

Actually, perhaps there will be no need for the icon to be indicated with PHP at all. If using Dashicons, then the font and icon can be purely defined in CSS. So this ticket would be primarily about providing a space for this icon to be displayed, to come up with default icons for core widgets, and to come up with a default icon which can then be overridden with a plugin's stylesheet. A plugin just need to enqueue a stylesheet to appear on the widgets admin page and in the customizer.

See conversation at ​https://twitter.com/joemcasta/status/414937640970878976

See also ​https://github.com/x-team/wp-widget-customizer/issues/69

[ocean90]

Moving to 3.9 for #27112.

I don't think a screenshot is neccesary for a widget. As westonruter points out, icons can be defined via CSS. Do we have the space for an icon?

[eherman24]

Hey Westonruter,

I had actually wrote about this a few months back on my blog, and towards the end proposed that a patch be added to core that would allow this feature (​http://www.evan-herman.com/add-an-icon-to-a-wordpress-widget/#.U-OuB_ldXT8).

I began development on a plugin, and wanted to customize the plugin and brand it a bit further than was possible. I had created a custom widget, but wanted to include the company logo into the widget on the admin side. The main reason behind this thought was that there are so many Widgets available to a user, that it quickly becomes visually overwhelming.

Adding an icon to the widget would make it a lot easier to locate the widget, without much time spent reading each widget title. WordPress has allowed for icons in menu items for sometime now, and allowed us to include dashicons into menu items. Going off that thought , I began to look around for a solution.

The route that I ended up taking was through CSS customizations, adding a background image to the widget title.

After mulling it over a bit, I decided I wanted to take charge and submit the first patch to adding icon support to widgets, much in the same way that add_menu_page() allows for.

I've come up with what I believe to be a solid solution to this need.

---

I've written the patch to allow an extra argument (icon_url) to be passed through to __construct() when initializing your custom widget.

public function __construct( $id_base, $name, $icon_url, $widget_options = array(), $control_options = array() )

Initializing your widget with a dashicon would look like this:

function __construct() {
	parent::__construct(
		'foo_widget', // Base ID
		__('Widget With Icon', 'text_domain'), // Name
		'dashicons-admin-collapse' ,  // New Icon Param (dashicon)
		array( 'description' => __( 'Testing a widget with an icon', 'text_domain' ), )
	);
}

Dashicon Widget Icon Screenshots:

Whereas initializing your widget with a custom image would be very similar, you would just pass in the path to the icon, much in the same way you do with add_menu_page() like this:

function __construct() {
	parent::__construct(
		'foo_widget', // Base ID
		__('Widget With Icon', 'text_domain'), // Name
		plugin_dir_url( __FILE__ ).'/image/yikes_logo_widget_icon.png' ,  // New Icon Param (image)
		array( 'description' => __( 'Testing a widget with an icon', 'text_domain' ), )
	);
}

Image Icons (.jpg,.png etc) Widget Icon Screenshots:

I took into consideration that some users ( or existing plugins/widgets ) may not want to use an icon or may not want to go back and add the new parameter. This is true for all of the default widgets (Archives, Tag Cloud etc.). So instead of going back and adding the new parameter to those already existing widgets, I've built in some backwards compatibility when parsing the code to prevent issues with existing widgets.

Adding icons to default widgets, or any widgets created by plugins would be as simple as going in and adding the new icon_url parameter just below the widget name.

Lets consider adding this feature into 4.0 or 4.1, as a way to unify the styles (and creation) between the admin and widget menus.

[eherman24]

simple plugin creating a widget to test out icons

[eherman24]

Updated padding between icon and widget title (if icon exists)

[eherman24]

decrease padding between icon and text in apperance > customizer screen

[ocean90]

eherman24, thanks for your patch so far. Some feedback:

• No need to patch minified files, these are auto-generated on build
• We don't use filter_var() in core, you can use esc_url() instead
• The constructor shouldn't get new arguments, as this breaks backward compatibility
• Some whitespace mistakes, see ​http://make.wordpress.org/core/handbook/coding-standards/php/#space-usage

[eherman24]

ocean90, thanks for the feedback.

I guess I wasn't sure about the minified files being re-compiled, but thanks for the clarification.

In regards to backwards compatibility, Pre-patch, the constructor passes in the $option->name (string) in that argument location. With the new patch, I'm passing in an array and checking if the returned argument is indeed an array. Is this not a viable way to go about doing things? I tested against previous versions of WordPress and things appeared to be backwards compatible with the new patch.

$this->icon_url = is_array($icon_url) || empty($icon_url) ? '' : $icon_url; // create the icon url parameter

And noted on the white space, I'll have a second go at this and fix the issues you have pointed out.

Thanks,
Evan

[eherman24]

fixed whitespace issues, removed filter_var for esc_url, removed minified css files

[eherman24]

I've attached a new patch which excludes the minified files, fixes white spacing issues and swaps out filter_var for esc_url.

I am still open to hearing suggestions about the best way to handle the $icon_url argument within the constructor.

Evan

[wonderboymusic]

$icon_url can be part of $widget_options

[FolioVision]

Tested the styling with dashicons, the spacing looks fine in narrow columns, on mobiles, with accessibility mode.

[joyously]

Design-wise, I am against the whole notion of putting icons on widgets. I have had several conversations with people recently that make me think that it's the younger folks that like them. The middle-aged and older set have a difficult time deciphering their meanings, and prefer text.
Icons add visual clutter with no real benefit, and can overwhelm.

Instead of icons, I would suggest to improve the widget UI by making the arrow that collapses and expands the Available Widgets column visible all the time, instead of just on hover. And by showing the Inactive Widgets in the Customizer.