A5ListBox Class
Arguments
- containerIdstring
The ID of the element the list should be rendered in.
- dataarray
Data to display in the list.
- settingsobject
Settings for the list. This will override the initial values of the properties of the A5.ListBox class.
Description
List control.
Discussion
The list control is built for handling tabular data. The data passed into the list can be javascript object or strings. There are a few custom list data items that can be used to add items such as titles, static HTML and separators.
In order to inject a title, and object with a property named "*title" can be used. The value of the "*title" property will be injected into the HTML for the title. A property of "className" can be used to set a custom class name on the title. A property of "navigate" set to a value of "false" can be used to make the title not appear in the list group navigator (if one is defined for the list).
In order to inject static HTML, and object with a property named "*static" can be used. The value of the "*static" property can be either a string of HTML to inject, or a function that will return that HTML. A property of "className" can be used to set a custom class name on the container for the static HTML.
To insert a separator, a string of "-" can be used.
In list item templates the "[scope]" template command will be the list class, through which methods and properties can be accessed. The "[temp]" template command contains an automatically created object named "info". This object has several useful properties. These are "renderIndex", "index", "isFirst" and "isLast". The "renderIndex" is the index of the list as viewed, whereas the "index" is the original index of the data for the list item in the array passed in to the list. The "isFirst" and "isLast" properties are booleans that indicate whether or not the list item is the first or last item in the list.
- Name
- Description
- A5.ListBox.Column Object
Definition of a column in a layout in the list.
- A5.ListBox.Group Object
Definition of an automatic group.
- A5.ListBox.Item Object
Definition of a custom item.
- A5.ListBox.Layout Object
Definition of a column in a layout in the list.
Properties
- themestring
The theme to use on the list.
- overridestring
The overrides to use on the list.
- inputIdstring
The ID of the INPUT into which the value of the list should be set every time the list value changes.
- classNamestring
The class name to put on the list container element.
- focusClassNamestring
The class name to put on the list container element when the list has focus.
- disabledClassNamestring
The class name to put on the list container element when the list has been disabled.
- captureFocusboolean
Whether or not to allow the list to capture focus. If set to true, then when the list is clicked on it will receive focus, and keyboard navigation can be done.
- multipleboolean
Whether or not the list 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.ListBox.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 list should loop keyboard navigation through values in the list. If set to false (the default) then pressing the down key when the list has focus will not jump back to the top of the list once the last item in the list 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 list, a null value will be selected before the first value in the list is.
- allowNullSelectionboolean
Whether or not to allow the list to have a null selection.
- allowNullDeselectionboolean
Whether or not to allow the list to deselect an item if there are no other values selected in the list.
- allowAnyValueboolean
Whether or not to allow the list to be set to have any value, regardless of whether that value is in the list. This is useful if the list needs to allow values that have been filtered out of the list to remain selected.
- allowTextSelectionboolean
Whether or not to allow text selection in the list.
- calculateValuefunction(data)
A function that receives the data for a row, and returns the value that the row should have based on the data. For example, if the list row data had an ORDERID field, the function could return that value, and then when the user clicked on a row, the value of the list would be the ORDERID of the row clicked on.
- dataobject
The data for the row.
- scrollobject
Scroll settings for the list.
- 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.ListBox. See A5.ListBox Layout Object.
- dataobject
Settings for data.
- defaultsobject
An optional object that contains the default values to place in a row in the list if the row is missing those values.
- nullHTMLstring
The HTML to use when a column of data in a row is null or undefined.
- columnLayoutobject
Settings for columnar layouts.
- headerobject
Settings for headers in column layouts.
- showboolean
Whether or not to show column headers in the list when the list uses a columnar layout.
- classNamestring
The class name to put on the column header element.
- itemobject
Settings for individual column headers.
- classNamestring
The class name to put on a column header element.
- hoverClassNamestring
The class name to put on a column header element when the user hovers over it.
- orderobject
Settings for the order indicator in column headers.
- ascendingImagestring
The image to use for the column when it is sorted in ascending order.
- descendingImagestring
The image to use for the column when it is sorted in descending order.
- classNamestring
The class name to put on the order image.
- stylestring
The CSS to put on the order image.
- resizeobject
Settings for column resizing.
- locationstring
Location for the resize handle. Value can be "before" or "after".
- classNamestring
The class name of the indicator element shown over the column while it is being resized.
- handleobject
Settings for column resizing handle.
- classNamestring
The class name to put on the column resize handle.
- sizestring
The size in CSS units of the column resize handle.
- dataobject
Settings for columns in each row in the list.
- itemobject
Settings for individual columns in each row in the list.
- classNamestring
The class name to put on a column in a row in the list.
- stylestring
The CSS to put on a column in a row in the list.
- viewobject
Settings to control list virtualization.
- typestring
The type of virtualization to use. The default value of "default" will result in all rows of the list being render. A value of "page" will dynamically page the rows of the list. A value of "dynamic" will append rows as the user scrolls.
- sizenumber
The number of rows to draw in the view. The default value is 50.
- maxSizenumber
The maximum number of rows that can be drawn in a "dynamic" view, before the view is cleared to reduce the DOM footprint of the list. The default value of "0" allows there to be no maximum size.
- offsetnumber
In a "page" view, the "offset" is the number of rows to include from the previous page when when drawing a new page. For example, if the user was on a page that ended on row 100, and they navigated to the next page, the first visible row in the new page would be 90 if the offset was 10. In general the offset want to at least be the number of rows visible in the list, so that when the new page is drawn the scroll position of the list can appear not to change.
- navigationobject
Settings for the navigation of views.
- eventstring
When the onNavigate event should be fired. The default value of "navigate" will fire the onNavigate event only when the page changes. A value of "scroll" will fire the event when the user scrolls, and the start and end will be the first and last visible indexes instead of the first and last indexes of the page. A value of "both" will fire the onNavigate event when the page is changed and when the list is scrolled.
- pullobject
Settings for automatic pull navigation of views.
- allowboolean
Whether or not to allow automatic navigation when the user pulls past either end of the list. The default value is true.
- sizenumber
The number of pixels that the user must pull past either end of the list before the release will result in an automatic page navigation. The default is 40.
- prevobject
Settings for the previous page button.
- htmlstring
The HTML to display in the previous button that will be drawn at the top of the page. The default value is "Prev".
- classNamestring
The class name to put on the button.
- pressedClassNamestring
The class name to put on the button when it is pressed, or the automatic pull size is reached.
- nextobject
Settings for the next page button.
- htmlstring
The HTML to display in the next button that will be drawn at the bottom of the page. The default value is "Next".
- classNamestring
The class name to put on the button.
- pressedClassNamestring
The class name to put on the button when it is pressed, or the automatic pull size is reached.
- groupobject
Settings for the list group generation and navigation.
- autoarray
An array of A5.ListBox Group Object definitions to use for grouping. The groups are processed in order, so if the array has more then one group object, each group object will be evaluated on each of the previously generated groups.
- collapseobject
Group collapse settings.
- allowstring
Specify when groups should be collapsible. Values can be "never" (the default), "programmatic" to only allow programmatic collapsing of groups using the A5.ListBox.setGroupCollapse method, "title" to allow toggling of a group by clicking on the title of the group, or "icon" to only allow an icon in the group title to control toggling of the group.
- autoboolean
If "true" groups will be automatically collapsed by default. The default is "false".
- indicatorobject
Settings for the collapse/expand indicator.
- collapsestring
The HTML to inject in the indicator placeholder when the group is expanded. By default a value of "-" is used.
- expandstring
The HTML to inject in the indicator placeholder when the group is collapsed. By default a value of "+" is used.
- object
Settings for the list group navigator. For example the alphabetic bar on the side of a contacts list.
- showboolean
Whether or not to show the navigator. The default value is false.
- locationstring
The location of the navigation. The default value is "right". Other values include "left", "top", and "bottom".
- offsetnumber
The distance in pixels from the edge of the list the navigator will be positioned. The default value is 4.
- sizenumber
The collapsed size of the navigator in pixels. When the user is interacting with the navigator it will grow so that all text in the navigator is visible. The default value is 28.
- processfunction(title)
A function that receives the title for a group, and can process the HTML to display in the group navigator.
- titlestring
The title of the group.
- classNamestring
The class name to put on the navigator.
- focusClassNamestring
The class name to put on the navigator when the user is interacting with it.
- stylestring
The CSS to put on the navigator.
- scrollerobject
Settings for the list scroller.
- showboolean
Whether or not to show the scroller. The default value is false.
- headerobject
Settings for the list fixed header.
- showboolean
Whether or not to show the header.
- htmlstring
The HTML to put in the list header.
- classNamestring
The class name to put on the list header.
- stylestring
The CSS to put on the list header.
- object
Settings for the list fixed footer.
- showboolean
Whether or not to show the footer.
- htmlstring
The HTML to put in the list footer.
- classNamestring
The class name to put on the list footer.
- stylestring
The CSS to put on the list footer.
- lockobject
Settings for the list lock. See A5.ListBox.setLock.
- classNamestring
The class name to put on the list lock element.
- htmlstring
The default HTML to put in the list lock element.
- contentobject
Settings for the list scrolling content area.
- classNamestring
The class name to put on the list content.
- headerobject
Settings for the list content header. The content header will scroll of the top of the list but will not be re-drawn when the list is refreshed.
- showboolean
Whether or not to show the header.
- htmlstring
The HTML to put in the list header.
- classNamestring
The class name to put on the list header.
- stylestring
The CSS to put on the list header.
- footerstring
Settings for the list content footer. The content footer will scroll of the top of the list but will not be re-drawn when the list is refreshed.
- showboolean
Whether or not to show the footer.
- htmlstring
The HTML to put in the list footer.
- classNamestring
The class name to put on the list footer.
- stylestring
The CSS to put on the list footer.
- itemobject
Settings for the list items.
- classNamestring
The class name to put on a list item.
- hoverClassNamestring
The class name to put on a list item when the user mouses over it.
- selectedClassNamestring
The class name to put on a list item when it is selected.
- stylestring
The CSS to put on a list item.
- titleClassNamestring
The class name to put on a list group title item.
- separatorClassNamestring
The class name to put on a list item separator.
- itemsobject
The definition of named items to be used in layouts. See A5.ListBox Item Object.
- animationobject
Settings for list animations.
- swapobject
Settings for the list swap animation, which can be optionally played on the population of the list. See A5.ListBox.populate.
- flowstring
The direction the list will animate based on whether it is going to the next or previous set of data. The default value is "ltr", "rtl" may also be used.
- durationnumber
The length of time (in milliseconds) that the animation should take. The default value is 600.
- lockobject
Settings for the list lock animation, which which controls the fade of the list lock element. See A5.ListBox.setLock.
- durationnumber
The length of time (in milliseconds) that the animation should take. The default value is 200.
- disabledboolean
Whether or not the list is disabled.
- readOnlyboolean
Whether or not the list is read-only.
- filterany
The filter to apply to the list data. See A5.ListBox.setFilter.
- filterLogicalstring
For a multiple column filter the logical operation to use. Values can be "or" (the default) or "and". See A5.ListBox.setFilter.
- orderany
The order to sort the list data in. See A5.ListBox.setOrder.
- selectionarray
The indexes of the selected list rows.
- selectionDataarray
The data of the selected list rows.
- selectionKeyarray
The indexes of the selected list rows before ordering and filtering.
- valuearray
The values of the selected list rows.
- stateobject
State information object.
- groupobject
The state of the lists grouping.
- activeboolean
True if the list is currently has grouping.
- viewobject
The state of the view page if the view type is "page" or "dynamic".
- startnumber
The start index of the current view page.
- endnumber
The end index of the current view page.
- hasPrevboolean
Whether or not there is a previous page.
- hasNextboolean
Whether or not there is a next page.
- onBeforePopulatefunction(data)
Event fired before the list is populated with data. If a value of false is returned by the function the populate will not be done.
- dataobject
The data the list is being populated with.
- onPopulatefunction(data)
Event fired when the list is populated with data.
- dataobject
The data the list was populated with.
- onBeforeListClearfunction()
Event fired before the contents of the list are cleared. This is useful if there are elements in the list content that need to be move for later use.
- onBeforeListDrawfunction(data,index,source)
Event fired before the contents of the list are drawn. At this point the data to be drawn can be manipulated before display.
- dataarray
The data to draw.
- indexnumber
The index in the data at which drawing is starting.
- sourcestring
The source of the draw command. Values can be "populate", "append-rows", "view-nav" and "view-add".
- onListDrawfunction(data,index)
Event fired when the contents of the list are drawn.
- dataarray
The data drawn.
- indexnumber
The index in the data at which drawing started.
- onBeforeItemDrawfunction(data,index)
Event fired before a list item is drawn. At this point the data to be drawn can be manipulated before display.
- dataobject
The data for the list item.
- indexnumber
The index of the list item.
- onGroupDrawfunction(group,element,titleElement,contentElement)
Event fired when a group of list items is drawn.
- groupstring
The name of the group.
- elementelement
The element that surrounds the group.
- titleElementelement
The group title element.
- contentElementelement
The element that surrounds the items in the group.
- onItemDrawfunction(data,index)
Event fired when a list item is drawn.
- dataobject
The data for the list item.
- indexnumber
The index of the list item.
- onBeforeSelectfunction(index)
Event fired before an item in the list is selected. If a value of false is returned by the function the selection will not be done.
- indexnumber
The index of the item being selected. If the index is equal to "-1" then no value is being selected.
- onSelectfunction(index)
Event fired when an item in the list is selected.
- indexnumber
The index of the item being selected. If the index is equal to "-1" then no value is being selected.
- onChangefunction(value)
Event fired when the value of the list changes.
- valuestring
The value of the value.
- onClickfunction(value)
Event fired when an item in the list is clicked.
- valuestring
The value clicked.
- onDblClickfunction(value)
Event fired when an item in the list is double clicked.
- valuestring
The value double clicked.
- onRightClickfunction(value)
Event fired when an item in the list is context clicked.
- valuestring
The value context clicked.
- function(start,end)
Event fired when the view in the list is navigated.
- startnumber
The start index of the view.
- endnumber
The end index of the view.
- typestring
The type of navigation. The value will be "scroll" if the event was fired by a scroll, and "page" if it is fired by page navigate.
- onBeforeAddRowsfunction(data,source)
Event fired before rows are added to the list. If a value of false is returned by the function the addition will not be done.
- dataarray
The data for the list items being added.
- sourceobject
The source of the row addition.
- typestring
The source type. Value you will "append" or "insert".
- indexnumber
If the type is "insert" then the index at which the new rows will be added.
- onAddRowsfunction(data,source)
Event fired when rows are added to the list.
- dataarray
The data for the list items added.
- sourceobject
The source of the row addition.
- typestring
The source type. Value you will "append" or "insert".
- indexnumber
If the type is "insert" then the index at which the new rows were be added.
- onBeforeRemoveRowsfunction(rows)
Event fired before rows are removed from the list. If a value of false is returned by the function the remove will not be done.
- rowsarray
The indexes of the rows being removed.
- onRemoveRowsfunction(rows)
Event fired when rows are removed from the list.
- rowsarray
The indexes of the rows removed.
- onBeforeUpdateRowfunction(index,data)
Event fired before a row is updated. If a value of false is returned by the function the update will not be done.
- indexnumber
The index of the item being updated.
- dataobject
The updated data for the row.
- onUpdateRowfunction(index,data)
Event fired when a row is updated.
- indexnumber
The index of the item updated.
- dataobject
The updated data for the row.
- onLayoutUpdatefunction(type,layout)
Event fired when the current layout is updated.
- typestring
The type of the updated.
- argumentsany
Any contextual arguments for the update (such as the column being resized).
- layoutobject
The current layout.
- onBeforeFilterfunction(filter)
Event fired before the list is filtered. If a value of false is returned by the function the filter will not be done.
- filterany
The new filter for the list.
- onFilterfunction()
Event fired when the list is filtered.
- onBeforeOrderfunction(order)
Event fired before the list is ordered. If a value of false is returned by the function the order will not be done.
- orderany
The new order for the list.
- onOrderfunction()
Event fired when the list is ordered.
- onBeforeResizefunction(width,height)
Event fired before the list is resized. If the layout of the list is changed by this event, then the list will preform a refresh to update to the new layout.
- widthnumber
The new width of the list in pixels.
- heightnumber
The new height of the list in pixels.
- onResizefunction()
Event fired when the list is resized.
- onFocusfunction()
Event fired when the list receives focus.
- onBlurfunction()
Event fired when the list looses focus.
- onBeforeDestroyfunction()
Event fired before the list is destroyed.
- onDestroyfunction()
Event fired when the list is destroyed.
Methods
- appendRows Method
Append new data to the end of the list.
- destroy Method
Destroy the list. This method should be called before the list is removed from the DOM.
- focus Method
Give focus to the A5.ListBox.
- getColumnarHTML Method
Generate columnar HTML base off the current layout of the list.
- getData Method
Get the data for a given row in the list.
- getIndex Method
Get the indexes of row(s) in the list.
- indexFromElement Method
Get the index of the list row that contains the passed in element.
- indexFromEvent Method
Get the index of the list row an event occurred on.
- indexFromPoint Method
Get the index of the list row matching the passed in coordinates.
- indexVisible Method
Get the first and last indexes currently visible in the list.
- insertRows Method
Insert new data into the list.
- navigate Method
Navigate the list selection.
- populate Method
Populate the list with new data.
- refresh Method
Refresh the list.
- removeRows Method
Remove rows from the list.
- resize Method
Resize the list.
- scrollToItem Method
Scroll to a target row in the list.
- setColumnOrderImage Method
Set the sort icon on a given column.
- setDisabled Method
Disable or enable the list.
- setDisplay Method
Show or hide parts of the list. The list will automatically be resized if needed.
- setFilter Method
Filter the list data.
- setGroupCollapse Method
Set the collapse state of a group.
- setLayout Method
Change the currently used layout.
- setLock Method
Lock the list to prevent user interaction.
- setOrder Method
Order the rows in the list.
- setValue Method
Set the value in the list.
- updateLayout Method
Change the currently used layout.
- updateRow Method
Update a row in the list.
- valueInList Method
Check whether a value is rendered in the list.
See Also