-
Notifications
You must be signed in to change notification settings - Fork 17
WComponents HTML class property
- Setting a custom class value
- Setting multiple class values
- Getting the list of added classes
- Removing a custom class value
- Inbuilt classes
- Using custom class values
- Further information
The htmlClass property is an optional property which may be used to add extra value(s) to the class attribute of the outermost element in the components's rendered HTML. It may then be used to apply styling or functionality which is custom to a particular application rather than built into a WComponents theme. Any WComponent which outputs a UI artefact may have a custom class applied to it.
The method getHtmlClass() returns the String value of the property. It does not return a CSS selector. The possibility of adding a method to access CSS selectors for components is under consideration and your views are welcome.
To set a custom HTML class attribute value on a component use the method setHtmlClass(String) or setHtmlClass(HtmlClassProperties). If one is unsure whether a htmlClass has been set previously it is safer to use addHtmlClass(String) or addHtmlClass(HtmlClassProperties).
// Given a WComponent (let us assume a WTextField)
WTextField givenNameField = new WTextField();
// set a classname which I can use as a hook
givenNameField.setHtmlClass("mycustomclass");Given the sample above CSS could be applied to change the appearance of the WTextField's rendered input element.
.mycustomclass:focus {
outline: 3px solid red; /* makes the input _really_ stand out! */
}An overloaded setter is available to use the values of the HtmlClassProperties enum.
WButton button = new WButton("Search");
button.setHtmlClass(HtmlClassProperties.ICON_SEARCH_BEFORE);For more information about attaching CSS to an application and inbuilt HTML class names see Adding custom CSS.
To set more than one value use the method addHtmlClass(String) or addHtmlClass(HtmlClassProperties). These methods may be used if one is not certain if a component already has a custom htmlClassName set.
// Given a WComponent givenNameField
// set a class value
givenNameField.setHtmlClass("mycustomclass");
// add another value
givenNameField.addHtmlClass("anothercustomclass");
// To get the classes
givenNameField.getHtmlClass();
// returns "mycustomclass anothercustomclass"To get the class Collection use getHtmlClasses(). The Collection is returned as a HashSet.
// Given a WComponent givenNameField
// ... add class names as above.
// To get the classes as a Set
givenNameField.getHtmlClasses();
// returns a HashSet with items keyed on the added strings.Any custom class which has been added may be removed using removeHtmlClass(String) or removeHtmlClass(HtmlClassProperties).
// Given a WComponent givenNameField
// set a class value
givenNameField.setHtmlClass("mycustomclass");
// remove the value
givenNameField.removeHtmlClass("mycustomclass");
givenNameField.getHtmlClass(); // returns nullMost WComponents HTML output already contains a class attribute containing one or more values as outlined in Theme class name conventions. Commonly used (or requested) values are exposed using HtmlClassProperties.
In many cases it should not be necessary to attach custom HTML classes to a WComponent. They may be useful though for implementing custom style or functionality. One common scenario is to attach a custom class property to screen level layout components to allow for effective responsive design. Many applications have requested common iconography so helpers for applying icon classes are provided in HtmlIconUtil.
Wherever a custom class is used to change the design or functionality of a component it is the application designer's and developer's joint and several responsibility to ensure that the application remains accessible.