Spinner

Mutates an a <input type='text'> tag into a field with a pair of buttons next to it that can be used to "spin" a numeric or date/time value up or down by a specified increment.

The composite component has the same size and shape as the <input> tag and the input field preserves any other settings (e.g., input assist) that was set on it.

The component can spin either numeric values or time values, that is, the component handles the same numbers as the NumberConverter or any "time" value specified by a JSFDateConverter.

The JSFSpinner component adds a pair of helper buttons to an <input> field which can be used to increment/decrement the value in the field.

The helper buttons are added to the right of the input field stacked one over the other. The input field retains (exactly) all of its original characteristics though now incorporating the buttons. For example, if the input field is defined to be 120px wide, when the helper buttons are added the combined component is now 120px wide. The buttons assume style properties that match the input field, e.g., their borders match the borders of the input field. Applicable attributes applied to the input field, such as disabled, are also reflected to the buttons.

The spinner can be applied to either a number field or to a datetime field that contains a "time" component (e.g., hh:mm:ss). When applied to a numeric field, the spin buttons increment/decrement the value by the specified increment until the maximum/minimum values specifeid in the validator (if supplied) are reached. If the spinner is applied to a time value, the spin buttons increment/decrement the value by the specified increment until the maximum/minimum values specifeid in the validator (if supplied) are reached. In addition, a "time spinner" can have additional increments specified such that each component of the value (hours, minutes, seconds) can be increment/decremented independently depending on where the cursor is in the field. For example, if multiple increments are specified, when the cursor is in the hour component of the field, the value can increment/decrement by an hour while when the cursor is in the minutes part of the field it can increment/decrement one minute at a time.

The "spin buttons" can be clicked or pressed. Clicking a button increments/decrements the value by one increment. Pressing the button continuously increments/decrements the value until the button is released.

The JSFSpinner requires a NumberConverter if the type is "number" or a DateTimeConverter if the type is "datetime". The converter is used to convert the value of the input field (a string) to/from a JavaScriptâ„¢ number or datetime object. The converter should be constructed before the spinner is constructed and the ID of the converter passed to the spinner. The input field may also have a NumberValidator and/or NumberAssist component associated with it (or DateTimeValidaator and/or DateTimeAssist. If a validator is associated with the input field, it must be passed to the JSFSpinner (as an attribute of the constructor). The validator is used to construct the minimum and maximum bounds of the spinner so it's strongly recommended that one be provided. If an Assist is associated with the input field, it does not need to be associated with the JSFSpinner.

JSF tags that emit the component

<hx:inputText>

Base HTML

<input type="text">

The value of the spinner is passed as the value of the input field. The value should be formatted in the style described by the converter associated with the component. If no value is initially passed to the page, the spinner has no initial value.

All attributes associated with an input of type text are supported.

All event handlers associated with an input of type text are supported.

JavaScript constructor

hX_5.addComponent("id", new hX_5.JSFSpinner(attributes)); where

id

The ID of the HTML tag to which the component is attached.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Attributes

Table 1. Spinner attributes

Attribute name

Description

type

The type of spinner (either a number spinner or a time spinner).

converter

The ID of a converter that has already been constructed. The converter describes the format of the value in the input field.

validator

The ID of a validator that has already been constructed. If the validator is supplied, the constraints described in the validator are used limit the values a user can pick.

increment

Increment between "ticks" in the slider. For example, if the minimum is 1 and the maximum is 10, an increment of 1 draws a tick at 1,2,3,4,5,6,7,8,9 and 10. Only values marked with a tick can be selected in the slider. Value may be fractional (for example, .01).

increment1

For time only, you may spin each time component (hour, minute, seconds) independently depending on where the cursor is in the value. If increment1 is specified, then increment is the increment when the cursor is in and "hour" time component and increment1 is the increment when the cursor is in a "minute" time component (or a "second" time component if no increment2 is specified). Value must be > .01. Note that if muliple increments are provided, increment2 must be provided even if there is no minute component in the pattern (same is true for increment).

increment2

For time only, you may spin each time component (hour, minute, seconds) independently depending on where the cursor is in the value. If increment1 is specified, then increment is the increment when the cursor is in an hour component and increment1 is the increment when the cursor is in a minutes component and increment2 is the increment when the cursor is in a seconds component. For example, specifying increment=3600, increment1=60, and increment2=1 and a format hh:mm:ss means when the cursor is in the hours part of the value, spinning increases/decreases the value by 1 hour, when the cursor is in the minutes part of the value, spinning increases/decreases the value by 1 minute and when the cursor is in the seconds part of the value, spinning increases/decreases the value by 1 second. Value must be > .001.

button-border

Controls how the popup button is drawn relative to the input field.

button-color

Specifies the background-color of the button. By default the background color matches the border color of the input field.

CSS classes

The class(es) applied to the input tag style the input field (e.g., set the border of the input field) and by extension, the spin buttons next to it (the buttons are styled to match the input field's border). There is no separate CSS for independently styling the spin buttons.

API calls

Table 2. API calls

API call

Description

redraw()

Redraw the component taking into account any changes made to the attributes/properties of the base tag.

uirelease()

Releases any active UI associated with the component.

setValue(string)

Sets the value of the component and ensures that the value provided is valid.

object = getValue(boolean)

Retrieves the value of the component. If the boolean is false, this is equivalent to getting the value of the base tag. If the boolean is true, the value is returned as a JavaScript date/time object instead of as a string.

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Accessibility

The spinner is fully keyboard accessible. The input field and both spin buttons are in the tab order. In the input field, the up and down arrow keys can be used to increment/decrement the value by an increment. Pressing the up/down arrow will "spin" the value by increments until the key is released. When a button has focus, tapping the button increments/decrements the value once. Pressing the spacebar continuously increments/decrements the value until the spacebar is released.

The spinner currently does not report XML roles/states (it is however XHTML compliant). This will be added as soon as possible.

Limitations

Example code

Add a spinner to a field where the format of the number is a percent. Limit the spinner to contain values between 0 and 100% and set the increment to 1%.

hX.addConverter("x1", new hX.NumberConverter("strict:1", "pattern:##0%", "locale:,.%‰-$"));
hX.addValidator("x1", new hX.NumberValidator( "min-bound:0.0",  "max-bound:1.0",  "required:true"));
hX.addComponent("form1:text1", new hX.JSFSpinner("increment:.01","converter:x1","validator:x1"));

Add a spinner to a field where the format specifies a time field. Specify three different increments such that the spinner is sensitive to where the cursor is in the value.

hX.addConverter("x16", new hX.DateTimeConverter("strict:1", "format:h:mm:ss a"));
hX.addComponent("form1:textTime3", new hX.JSFSpinner("type:datetime", "increment:3600", 
                  "increment1:60", "converter:x16"));

Feedback