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.
- boolean
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.
- boolean
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.