Skip to content

HtmlIconUtil

Jump to bottom
Mark Reeves edited this page Jan 4, 2018 · 9 revisions

HtmlIconUtil is a utility class which supplies helpers to set theme-based icons (in conjunctions with HtmlClassProperties) to components using setHtmlClass (see WComponents HTML class property).

These helpers use className strings derived from HtmlClassProperties.

Static Strings

The utility class exposes the icon positioning classNames as strings for use in setHtmlClass(String) or addHtmlClass(String) without having to manually call toString() on the HtmlClassProperties enum value. The available strings are:

These are provided for convenience but it may be easier to use an icon helper method as shown below.

Helper methods

The utility class provides helpers to convert a String icon class name (such as from Font Awesome to a className string which can be used to position an icon in a component. These methods make it easier to apply custom icons to components. The following snippet shows how to use these methods to attach a filter icon from Font Awesome to a WButton.

// ... It is probably a good idea to put references to
// HTML className strings somewhere central
private final String faFilterIcon = "fa-filter";
//...

WButton filterButton = new WButton("\u200b");
filterButton.setAccessibleText("Filter results");
// attach a filter icon to the button.
button.setHtmlClass(HtmlIconUtil.getIconClasses(faFilterIcon));

filterButton = new WButton("Filter results");
// put the icon before text content
button.setHtmlClass(HtmlIconUtil.getIconClasses(faFilterIcon,
    HtmlIconUtil.IconPosition.BEFORE));
// OR put the icon after text content
button.setHtmlClass(HtmlIconUtil.getIconClasses(faFilterIcon,
    HtmlIconUtil.IconPosition.AFTER));

Using HtmlIconUtil

setHtmlClass(String) is available on all WComponents but some components should not have icons applied to them.

The icons may not work with any component which outputs a simple form control (such as WTextField) or WProgressBar. They may also interfere with inbuilt iconography under some, fortunately unusual, circumstances.

It is recommended that icons be applied to:

It is not incorrect to apply an icon to a container component such as WPanel but it would be quite unusual to do so. Icons may have unexpected results if applied to compound form controls, WSubMenu, WTabSet or WMenu. Icons may interfere with, or more likely be overridden by, inbuilt iconography if applied to the WDecoratedLabel associated with a WSubMenu or WCollapsible.

Icon size and colour

The default colour and size for an icon is determined by the text style of the component into which the icon is applied. Additional styling may be possible using in-built Font Awesome styles and addHtmlClass(String). For example to change the size of an icon to be 2 times the normal size one can use the inbuilt class fa-2x.

The following classes are available to set the colour of an icon set on a component. Note that these class names act on the ::before pseudo-element only and will not also change the colour of text in a component.

  • wc-cerror will set the icon glyph to the theme's error colour (default to red);
  • wc-cwarning will set the icon glyph to the theme warning colour;
  • wc-cinfo will set the icon glyph to the theme information message colour;
  • wc-csuccess will set the icon glyph to the theme success message colour;

Application level (or sub-theme) CSS will be required to apply other colours or styles.

Related topics

Further information

Some start pages

Clone this wiki locally