JavaScript

A5ViewBox Class

Arguments

containerIdstring

The ID of the element the view box should be rendered in.

dataobjectarray

Data to use in the view box. If the view box uses static HTML, and does not require data, "null" can be passed in, or the data argument can be omitted.

settingsobject

Settings for the view box. This will override the initial values of the properties of the A5.ViewBox class.

Description

View box control.

Discussion

The view box control can be used to accomplish a number of different control types. For example, light weight lists, keypads, progress indicators, rating controls, etc. This can be accomplished because the view box can contain any HTML - derived from static HTML or the expansion of a template (see A5.u.template).

To allow user interaction with the contents of the view box, special attributes are added to any element that should be interactive. These attributes are "a5-item" and "a5-value".

The "a5-item" attribute contains the name of the item which the element is bound to. The "a5-value" attribute is used in conjunction with the "a5-item" attribute to express the value to associate with the element. The definition for the behavior of the element is contained in either the view box or current view box layout "items" property, the "a5-item" being used to select the corresponding item. Item arguments - a way to send extra arguments to the item event handlers - can be used by adding arguments as a suffix in the "a5-item" attribute, separating them from the item name by a ":".

Any element with an "a5-item" must also have an ID. If no ID is specified, an ID for the element will be automatically generated. However, the ID will be regenerated every time the view box control is refreshed, meaning that between refreshes the automatic ID on any given element will change. It is best practice to specify IDs on element that have an "a5-item".

When using a template to generate the HTML for the view box, the "[scope]" template command will be the view box class, through which methods and properties can be accessed.

Name
Description
A5.ViewBox.Animation Object

Definition of a redraw animation in the view box.

A5.ViewBox.Item Object

Definition of an item in the view box.

A5.ViewBox.Layout Object

Definition of a layout in the view box.

Properties

themestring

The theme to use on the view box.

overridestring

The overrides to use on the view box.

inputIdstring

The ID of the INPUT into which the value of the view box should be set every time the view box value changes.

classNamestring

The class name to put on the view box container element.

focusClassNamestring

The class name to put on the view box container element when the view box has focus.

disabledClassNamestring

The class name to put on the view box container element when the view box has been disabled.

captureFocusboolean

Whether or not to allow the view box to capture focus. If set to true, then when the view box is clicked on it will receive focus, and keyboard navigation can be done. However, this will prevent INPUT controls inside the view box from getting focus.

multipleboolean

Whether or not the view box allows multiple values to be selected.

separatorstring

The separator string to use for combining multiple values when the value is being put into the INPUT specified by A5.ViewBox.inputId.

selectionModestring

The method by which multiple selection occurs. By default the CTRL or SHIFT key must be pressed to select additional values. Setting the value to "additive" will allow multiple values to be selected without the use of a keyboard.

loopNavigateboolean

Whether or not the view box should loop keyboard navigation through values in the view box. If set to false (the default) then pressing the down key when the view box has focus will not jump back to the top of the view box once the last item in the view box is hit. Setting the value to true will loop the navigation back to the beginning.

loopNavigateNullSelectionboolean

Whether or not the allow for a null value to be selected while loop navigating. If set to true (the default) then after navigating passed the end of the view box, a null value will be selected before the first value in the view box is.

allowNullSelectionboolean

Whether or not to allow the view box to have a null selection.

allowNullDeselectionboolean

Whether or not to allow the view box to deselect an item if there are no other values selected in the view box.

allowAnyValueboolean

Whether or not to allow the view box to be set to have any value, regardless of whether that value is in the view box. This is useful if the view box is being used to create a value, such as if the view box is a calculator.

allowTextSelectionboolean

Whether or not to allow text selection in the view box.

autoRefreshboolean

Whether or not to automatically refresh the view box when the user makes a selection in it.

animationobject

Animation settings.

allowboolean

Whether or not to allow animation. If the view box is going to be animated at any point, the value of this must be true. To support animation extra elements are added to the view box around the content. This may effect layout.

scrollobject

Scroll settings for the view box.

axisstring

The axis to allow scrolling on. Values can be "x", "y" or "both".

layoutstring

Name of the layout to use.

layoutsobject

The definition of named layouts to use in the A5.ViewBox. See A5.ViewBox Layout Object.

wrapperobject

An optional layout wrapper to allow for custom HTML to be placed inside the view box, an element of which will contain the view box layout.

allowboolean

Whether or not to allow the wrapper to be drawn on initialize.

htmlobject

The HTML to place inside the view box container. The HTML must have an element that has an attribute of "a5-layout-target" set to "true". The view box layout will be drawn inside that element.

initfunction

An optional initialization function to call once the wrapper HTML has been rendered.

itemsobject

The definition of named items to be used in layouts. See A5.ViewBox Item Object.

templatesobject

Global template setting.

partialsobject

The global partial templates to provide to every layout that uses templates. See A5.u.template.expand for information on partial templates.

selectionInfoobject

Information about the current selection.

idsarray

The IDs of the selected elements in the view box.

activeobject

The currently active selected item. This is usually the last element the user interacted with, and keyboard navigation will be relative to this element.

hasboolean

Whether there is an active item.

idstring

The ID of the active item.

valuestring

The value of the active item.

isLastboolean

Whether the item is the last selectable item in the view box.

isFirstboolean

Whether the item is the first selectable item in the view box.

prevobject

The previous item relative to the active item.

hasboolean

Whether there is an previous item.

idstring

The ID of the previous item.

valuestring

The value of the previous item.

nextobject

The next item relative to the active item.

hasboolean

Whether there is an next item.

idstring

The ID of the next item.

valuestring

The value of the next item.

stateobject

State information object. This can be read with A5.ViewBox.getState and written with A5.ViewBox.setState. And can be used to store state information that can be accessed in view box layout templates.

onBeforeDrawfunction()

Event fired before the contents of the view box are drawn.

onDrawfunction(element)

Event fired when the contents of the view box are drawn.

elementelement

The view box element.

onBeforePopulatefunction(data)

Event fired before the view box is populated with data. If a value of false is returned by the function the populate will not be done.

dataobject

The data the view box is being populated with.

onPopulatefunction(data)

Event fired when the view box is populated with data.

dataobject

The data the view box was populated with.

onBeforeSelectBeginfunction(value)

Event fired before the selection is begun. The onSelect/onBeforeSelect will fire for each item being selected. The onBeforeSelectBegin will fire only once. If a value of false is returned, then the selection is canceled.

valuestring

The value of the view box.

onBeforeSelectfunction(value,itemArguments,item,element,event)

Default event fired before an item in the view box is selected. If a value of false is returned by the function the selection will not be done.

valuestring

The value being selected.

itemArgumentsstring

Arguments from the specific item selected.

itemobject

The item definition object.

elementelement

The element being selected.

eventeventboolean

The event object. If the selection was programmatic, then the event will be false.

onSelectfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is selected.

valuestring

The value selected.

itemArgumentsstring

Arguments from the specific item selected.

itemobject

The item definition object.

elementelement

The element selected.

eventeventboolean

The event object. If the selection was programmatic, then the event will be false.

onSelectCompletefunction(value)

Event fired when the selection is complete. The onSelect/onBeforeSelect will fire for each item being selected. The onSelectionComplete will fire only once.

valuestring

The value of the view box.

onChangefunction(value)

Event fired when the value of the view box changes.

valuestring

The value of the view box.

onClickfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is clicked.

valuestring

The value clicked.

itemArgumentsstring

Arguments from the specific item clicked.

itemobject

The item definition object.

elementelement

The element clicked.

eventeventboolean

The event object.

onDblClickfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is double clicked.

valuestring

The value double clicked.

itemArgumentsstring

Arguments from the specific item double clicked.

itemobject

The item definition object.

elementelement

The element double clicked.

eventeventboolean

The event object.

onRightClickfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is context clicked.

valuestring

The value context clicked.

itemArgumentsstring

Arguments from the specific item context clicked.

itemobject

The item definition object.

elementelement

The element context clicked.

eventeventboolean

The event object.

onDownfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is pressed down.

valuestring

The value pressed down.

itemArgumentsstring

Arguments from the specific item pressed down.

itemobject

The item definition object.

elementelement

The element pressed down.

eventeventboolean

The event object.

onUpfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is release.

valuestring

The value release on.

itemArgumentsstring

Arguments from the specific item release on.

itemobject

The item definition object.

elementelement

The element release on.

eventeventboolean

The event object.

onSwipefunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is swiped.

valuestring

The value swiped on.

itemArgumentsstring

Arguments from the specific item swiped on.

itemobject

The item definition object.

elementelement

The element swiped on.

eventeventboolean

The event object.

onDownHoldfunction(value,itemArguments,item,element,event)

Default event fired when an item in the view box is pressed and held.

valuestring

The value pressed and held.

itemArgumentsstring

Arguments from the specific item pressed and held.

itemobject

The item definition object.

elementelement

The element pressed and held.

eventeventboolean

The event object.

onDragStartfunction(dragInfo,value,itemArguments,item,element,event)

Default event fired when a drag is started on this specific item type in the view box.

dragInfoobject

The drag data.

xnumber

The location on the X axis.

ynumber

The location on the Y axis.

startobject

The start values.

xnumber

The start value on the X axis.

ynumber

The start value on the Y axis.

minobject

The minimum values.

xnumber

The minimum value on the X axis.

ynumber

The minimum value on the Y axis.

maxobject

The maximum values.

xnumber

The maximum value on the X axis.

ynumber

The maximum value on the Y axis.

valuestring

The value being dragged.

itemArgumentsstring

Arguments from the specific item being dragged.

itemobject

The item definition object.

elementelement

The element being dragged.

eventeventboolean

The event object.

onDragMovefunction(dragInfo,value,itemArguments,item,element,event)

Default event fired when a drag is happening on this specific item type in the view box.

dragInfoobject

The drag data.

xnumber

The location on the X axis.

ynumber

The location on the Y axis.

startobject

The start values.

xnumber

The start value on the X axis.

ynumber

The start value on the Y axis.

minobject

The minimum values.

xnumber

The minimum value on the X axis.

ynumber

The minimum value on the Y axis.

maxobject

The maximum values.

xnumber

The maximum value on the X axis.

ynumber

The maximum value on the Y axis.

valuestring

The value being dragged.

itemArgumentsstring

Arguments from the specific item being dragged.

itemobject

The item definition object.

elementelement

The element being dragged.

eventeventboolean

The event object.

onDragEndfunction(dragInfo,value,itemArguments,item,element,event)

Default event fired when a drag is ended on this specific item type in the view box.

dragInfoobject

The drag data.

xnumber

The location on the X axis.

ynumber

The location on the Y axis.

startobject

The start values.

xnumber

The start value on the X axis.

ynumber

The start value on the Y axis.

minobject

The minimum values.

xnumber

The minimum value on the X axis.

ynumber

The minimum value on the Y axis.

maxobject

The maximum values.

xnumber

The maximum value on the X axis.

ynumber

The maximum value on the Y axis.

valuestring

The value being dragged.

itemArgumentsstring

Arguments from the specific item being dragged.

itemobject

The item definition object.

elementelement

The element being dragged.

eventeventboolean

The event object.

onFocusfunction()

Event fired when the view box receives focus.

onBlurfunction()

Event fired when the view box looses focus.

onBeforeDestroyfunction()

Event fired before the view box is destroyed.

onDestroyfunction()

Event fired when the view box is destroyed.

Methods

addElementClass Method

Add a class name to element(s) in the view box.

clearState Method

Clear all state information. This can be used to reset the state, since the A5.ViewBox.setState method will not delete items in the state information, only overwrite them,

destroy Method

Destroy the view box. This method should be called before the view box is removed from the DOM.

focus Method

Give focus to the A5.ViewBox.

getElement Method

Get the element(s) matching the current value of the view box.

getState Method

Returns the current state information object.

navigate Method

Navigate the view boxes selected value relative to the current active selection (see selectionInfo in A5.ViewBox).

populate Method

Populate the view box with new data.

refresh Method

Refresh the view box. If the layout being used is "static" then the HTML will be replaced with the original HTML (or the function to generate it will be called again). If the layout type is "template" then the template will be regenerated from the current data in the view box.

removeElementClass Method

Remove a class name from element(s) in the view box.

scrollToItem Method

Scroll to an item in the view box.

setDisabled Method

Disable or enable the entire view box.

setElementClass Method

Set the class name of element(s) in the view box.

setElementDisabled Method

Disable or enable individual elements in the view box. This works on both selectable (such as a list item) and non-selectable (such as a button) elements.

setLayout Method

Change the currently used layout.

setState Method

Merge passed in state information with the previously existing state information. This will not refresh the view box, so if the state information is used in the layout, then a A5.ViewBox.refresh must also be done.

setValue Method

Set the value in the view box.

updateLayout Method

Update a layout.

To get a pointer to the A5.ViewBox class in a UX see dialog.object.getControl Method Object.