-
Notifications
You must be signed in to change notification settings - Fork 17
HtmlClassProperties
HtmlClassProperties supplies a set of commonly used HTML class attribute values which can be used in conjunction with setHtmlClass or addHtmlClass (see WComponents HTML class property).
A common use of these classNames is to attach a theme-based icon to a component (such as WButton, WLink or WMenuItem). To this end a set of icon helper classNames are provided and methods to get a WComponents HTML className string which can be used to apply a custom icon (one not in the icon set) to a component.
- Contents
- Available class values
- Using these classNames
- Changing the icon appearance
- Related topics
- Further information
| Purpose | enum value | HTML class value |
|---|---|---|
| Centre align content | ALIGN_CENTER | wc-align-center |
| Left align content | ALIGN_LEFT | wc-align-left |
| Right align content | ALIGN_RIGHT | wc-align-right |
| Allow text content to break at non-word boundaries | BREAK_WORDS | wc-brkall |
| Apply a theme-standard border to a component | BORDER | wc-border |
| Horizontal scrolling | HORIZONTAL_SCROLL | wc-hscroll |
| Move out of viewport | OFF_SCREEN | wc-off |
| Use inbuilt responsive design for a component (where this is opt-in) | RESPOND | wc-respond |
Three enum values are supplied to help attach an icon to a component. These will not have any effect on components which output simple form controls. They are best used with WButton, WLink, WMenuItem, WStyledText or WDecoratedLabel.
| Purpose | enum value | HTML class value |
|---|---|---|
| Use a theme icon as the component's content | ICON | wc-icon |
| Use a theme icon before the component's content | ICON_BEFORE | wc-icon wc-icon-before |
| Use a theme icon after the component's content | ICON_AFTER | wc-icon wc-icon-after |
These three classes must be used in conjunction with a means to attach the actual icon. This is most easily undertaken by using a value from Font Awesome which ships with WComponents.
HtmlClassProperties provides short-cuts to include the following icons in any of:
- as component content (or before any other content but without a space between the icon and other content);
- before the content with a small space between the icon and the content; or
- after the content with a small space between the content and the icon.
| Icon type | enum value | "after" value | "before" value | Example |
|---|---|---|---|---|
| add | ICON_ADD | ICON_ADD_AFTER | ICON_ADD_BEFORE | plus-square |
| cancel | ICON_CANCEL | ICON_CANCEL_AFTER | ICON_CANCEL_BEFORE | ban |
| delete | ICON_DELETE | ICON_DELETE_AFTER | ICON_DELETE_BEFORE | minus-square |
| edit | ICON_EDIT | ICON_EDIT_AFTER | ICON_EDIT_BEFORE | pencil |
| error | ICON_ERROR | ICON_ERROR_AFTER | ICON_ERROR_BEFORE | minus-circle |
| help | ICON_HELP | ICON_HELP_AFTER | ICON_HELP_BEFORE | question-circle |
| information | ICON_INFO | ICON_INFO_AFTER | ICON_INFO_BEFORE | info-circle |
| menu | ICON_MENU | ICON_MENU_AFTER | ICON_MENU_BEFORE | bars |
| ICON_PRINT | ICON_PRINT_AFTER | ICON_PRINT_BEFORE | ||
| save | ICON_SAVE | ICON_SAVE_AFTER | ICON_SAVE_BEFORE | floppy-o |
| search | ICON_SEARCH | ICON_SEARCH_AFTER | ICON_SEARCH_BEFORE | search |
| success | ICON_SUCCESS | ICON_SUCCESS_AFTER | ICON_SUCCESS_BEFORE | check-circle |
| warning | ICON_WARN | ICON_WARN_AFTER | ICON_WARN_BEFORE | exclamation-triangle |
The enum provided by HtmlClassProperties are used in setHtmlClass or addHtmlClass which is available on most WComponents but some of these classNames are better suited to some components than others. Use is quite straightforwards for a single value but gets a little more cumbersome for combinations, which is why the ICON values have several variations. HtmlIconUtil is a utility class available for attaching custom icons.
// Set a value from the enum on a WButton button
// using the help icon as an example.
button.setHtmlClass(HtmlClassProperties.ICON_HELP);
// OR
button.addHtmlClass(HtmlClassProperties.ICON_HELP);
// ...
// To remove a previously added value
button.removeHtmlClass(HtmlClassProperties.ICON_HELP);Setting an enum value along with a custom string, or two or more enum values, requires the individual values be added using addHtmlClass.
// Assume WPanel customPanel which needs:
// 1. a custom class,
// 2. center alignment and
// 3. horizontal scroll.
// It could be built something like this:
customPanel.setHtmlClass("myCustomClass"); // or .addHtmlClass
customPanel.addHtmlClass(HtmlClassProperties.ALIGN_CENTER);
customPanel.addHtmlClass(HtmlClassProperties.HORIZONTAL_SCROLL);
// ...
// to remove a previously added value
customPanel.removeHtmlClass("myCustomClass");
customPanel.removeHtmlClass(HtmlClassProperties.ALIGN_CENTER);The alignment classNames can be used where a layout component does not have an Alignment available or where a change of alignment is required temporarily. It may be better, for example, to apply ALIGN_CENTER than to use a FlowLayout with Alignment.CENTER if the container holds only a single component with a UI artefact (see WComponents without UI artefacts).
It is recommended the alignment classNames not be applied to WComponent form controls, especially compound form controls.
This className should be used with care as it may introduce accessibility or usability problems. It is best applied to container components such as WPanel, WSection or, at a pinch, WTable. It can be used with other containers such as WDecoratedLabel and even with WStyledText but may produce little or no effect depending on the rendering of the component.
It should be noted that this className will limit the width of a component and not the height.
If used on a component which is then placed into a horizontal FlowLayout or the EAST or WEST segments of a BorderLayout the component may shrink to near-zero width.
This className will move the affected component out of the viewport: this means it will be invisible to many users but available to users of assistive technologies. It is most useful for applying landmark headings which can be used to navigate a complex UI. For this reason it is best applied to WHeading. This className should not be applied to WLabel which is moved out of viewport if its hidden property is set true.
This className currently has an affect only on WMenu of MenuType BAR or FLYOUT and some layout components (Notably WRow and WPanel with either ColumnLayout or GridLayout) and WTable. It can be used in conjunction with a theme implementation or custom CSS to apply granular responsive design.
It should probably not be used on simple form control and many compound form controls have in-built responsive design aspects.
The icons will 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:
Icons may have unexpected results if applied to compound form controls, WSubMenu, WTabSet WPanel 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.
Each Icon supplied by this utility class has a default glyph from the Font Awesome set. The actual className set for a particular icon may be updated by setting a WComponents property as listed below. The property value must be a className which is recognized by the application's theme. It is, therefore, easiest to replace them with an icon from the Font Awesome set.
- Add icon:
com.github.bordertech.wcomponents.HtmlClass.icon.add - Cancel icon:
com.github.bordertech.wcomponents.HtmlClass.icon.cancel - Delete icon:
com.github.bordertech.wcomponents.HtmlClass.icon.delete - Edit icon:
com.github.bordertech.wcomponents.HtmlClass.icon.edit - Error icon:
com.github.bordertech.wcomponents.HtmlClass.icon.error - Help icon:
com.github.bordertech.wcomponents.HtmlClass.icon.help - Info icon:
com.github.bordertech.wcomponents.HtmlClass.icon.info - Menu icon:
com.github.bordertech.wcomponents.HtmlClass.icon.menu - Print icon:
com.github.bordertech.wcomponents.HtmlClass.icon.print - Save icon:
com.github.bordertech.wcomponents.HtmlClass.icon.save - Search icon:
com.github.bordertech.wcomponents.HtmlClass.icon.search - Success icon:
com.github.bordertech.wcomponents.HtmlClass.icon.success - Warning icon:
com.github.bordertech.wcomponents.HtmlClass.icon.warn
For example, if the application uses a cog wheel instead of bars for a menu icon but still uses Font Awesome then the change could be made for all uses of HtmlClassProperties.ICON_MENU[_BEFORE|_AFTER] by setting the following:
com.github.bordertech.wcomponents.HtmlClass.icon.menu=fa-cog