Relib UI - TroyHisted/relib GitHub Wiki

The UI module provides a tag library and several supporting classes.

• Tag Library
• Field
• Option
• Message

A flexible input tag capable of rendering multiple types of form input fields.

<%@ taglib uri="http://relib.org/relib" prefix="r" %>

<r:input type="text" value="${person.name}" />
<r:input type="select" value="${person.age}" options="${ageOptions}"/>
<r:input type="radio" value="${person.gender}" options="${genderOptions}"/>
<r:input type="textarea" value="${person.bio}" />

<r:html />

• Writes out the standard html5 tag.
• Defaults the lang attribute to "en".
• Supports dynamic attributes.

<r:js src="/foo.js" />

• Writes out a script tag.
• The base of the url is generated using c:url, allowing you to specify just the path within your web root. This works well for allowing linking within an IDE (e.g. Eclipse).
• If the tag contains a body it will be wrapped in CDATA.

src: Specifies the path to the js file. (Required)

context: Specifies the root context to prefix the src path with. Defaults to the application context of this application.

<r:css src="/foo.css" />

• Writes out a link tag for a stylesheet.
• The base of the url is generated using c:url, allowing you to specify just the path within your web root. This works well for allowing linking within an IDE (e.g. Eclipse).
• If the tag contains a body it will be wrapped in CDATA.

src: Specifies the path to the js file. (Required)

context: Specifies the root context to prefix the src path with. Defaults to the application context of this application.

<r:input type="text" value="${value}" />

• All attributes are optional.
• Supports dynamic attributes. Even if the attribute you write is not listed below, it will still be written out to the tag.

type: The type of input (defaults to "text"). The type specifies which type of form control to render. Support for "text", "select", "radio", "checkbox", and "textarea".

value: The current value of the input field. Depending on the type of input, this can range from the text of a textarea to the value of a select option.

submitValue: For radio and check-box inputs, this is the value that will be submitted if the radio or check-box is selected.

options: The options are an array or list of potential values that the user can choose from. Depending on the type of input, they are presented as anything from select options to a list of check-boxes. For convenience, integrated support for {@link Option} objects is included, however any list or collection of objects may be used.

valueProperty: Specifies which property of an option to use as the value. If unspecified, the toString of the option will be used.

labelProperty: Specifies which property of an option to use as the label. If unspecified, the toString of the option will be used.

enabledProperty: Specifies which property of an option to use as the indicator for enable. If unspecified, all options will be enabled.

<r:field type="radio" value="${name.genderField}" />

• A form input designed to wrap a Field class.
• Supports dynamic attributes. Even if the attribute you write is not listed below, it will still be written out to the tag.

type: The type of input (defaults to "text"). The type specifies which type of form control to render. Support for "text", "select", "radio", "checkbox", and "textarea".

field: The input field(org.relib.ui.field.Field) to use. (Required)

type: The type of input (defaults to "text"). The type specifies which type of form control to render.

submitValue: For radio and check-box inputs, this is the value that will be submitted if the radio or check-box is selected.

options: The options are an array or list of potential values that the user can choose from. Depending on the type of input, they are presented as anything from select options to a list of check-boxes. For convenience, integrated support for {@link Option} objects is included, however any list or collection of objects may be used.

valueProperty: Specifies which property of an option to use as the value. If unspecified, the toString of the option will be used.

labelProperty: Specifies which property of an option to use as the label. If unspecified, the toString of the option will be used.

enabledProperty: Specifies which property of an option to use as the indicator for enable. If unspecified, all options will be enabled.

Represents a value that could be selected as the desired value for a field.

Option[] genderOptions = new Option[] { 
    new InputOption("M", "Male"), 
    new InputOption("F", "Female") 
}; 

The value property is the value that is submitted when the particular option is selected by the user. Depending on the input control used, this may also be the value that is displayed to the user. Certain controls like a text input with a datalist do not allow the value and label to differ. As such, the label will be ignored and the value will be used both as the displayed text and as the submitted value.

The label is the description of the option that is presented to the user. It is from this value that the user must determine if the option is their desired option. Some controls do not allow the label to differ from the value, in those cases, the value will be used instead of the label.

Option option = new InputOption("foo", "bar");
option.getValue(); // foo
option.getLabel(); // bar

The group is a seldom used aspect of an option. Most notably associated with a select control where the group is interpreted as an optGroup value, the group provides a label for distinguishing a group of options. When used, each option in the group must have the same group value. Additionally, multiple options of the same group must be ordered consecutively if they are to be displayed in a single group. Any time a new group is encountered a new group label is displayed.

Option option = new Option("value", "label", "group");

Some controls provide the ability to prevent a particular option from being chosen. When an option is used for one of those controls the enabled property can be used to specify whether a user is allowed or disallowed from selecting the option.

Option disabled_a = new Disabled(new InputOption("foo", "bar")); // Disabled via wrapper
Option disabled_b = new OptionBuilder().enabled(false).label("foo").value("bar").build(); 

Represents a message that can be presented to a user.

A message has a level which indicates the significance of the message. There are several default levels which range from debug to error. The implementor may use or expand upon these default levels, or may choose to use their own scheme.

The message levels are:

• 10 - Message.DEBUG_LEVEL
• 20 - Message.INFO_LEVEL
• 25 - Message.SUCCESS_LEVEL
• 30 - Message.WARNING_LEVEL
• 40 - Message.ERROR_LEVEL

There are pre-defined classes for each of the default levels: DebugMessage, InfoMessage, SuccessMessage, WarningMessage, and ErrorMessage.

Message foo = new WarningMessage("Bar is required");
foo.getLevel(); // 30
foo.getText(); // Bar is required

Represents a field that a user can interact with to provide information to the application.

A field is the smallest validatable piece of input. Typically a Field will simply wrap a String, however there are circumstances where wrapping a more complex object may be appropriate. An example might be a ZipCode object that contains both the zip and additional 4.

A field provides both bean properties and fluent setters for the following:

• value: The wrapped value of the field.
• label: The label for the input field on the form.
• message: A message describing the state of the field, generally used for presenting an error message.
• options: A list of values that the user can choose from.

A field may be erred through the Message it contains. If the message is of an error type, then the field is considered to be erred. Likewise, if the field has no message, it is not erred. A Message may represent many other states of validation as well.

Each property is also exposed with a fluent setter. These setters both set the property value and return the Field. This allows for convenient chaining of properties when constructing a Field.