Class: AbstractGrid

AbstractGrid

The base class for the hierarchy of the *Grid classes. Extends AbstractWidget to abstract a representation of the internal tabular model as a visible grid made of HTML elements. A specialized (derived) object, rather than an AbstractGrid instance, should be created and used. Two of such classes are available with the library: StaticGrid and DynaGrid. This class is used by the mentioned specialized grid objects to inherit the support for their basic configurations and common utilities.
The class is not meant as a base class for the creation of custom grids. The class constructor and its prototype should never be used directly.

new AbstractGrid()

This is an abstract class; no instances of this class should be created.

Extends

Method Summary

extractCommandSecondLevelFieldList
Creates an array containing all the unique values, of the "data-field" properties in all of the HTML elements, having the "data-fieldtype" property set to "second-level", associated to this grid during the AbstractGrid#parseHtml execution.
extractFieldList
Creates an array containing all the unique values of the "data-field" properties in all of the HTML elements associated to this grid during the AbstractGrid#parseHtml execution.
forceSubscriptionInterpretation
Operation method that is used to force the choice of what to use as key for the integration in the internal model, when receiving an update from a Subscription this grid is listening to.
getNodeTypes
Inquiry method that gets the list of node of types that would be searched in case of a call to AbstractGrid#parseHtml.
getSortField
Inquiry method that gets the name of the field currently used as sort field, if available.
isAddOnTop
Inquiry method that gets true/false depending on how new rows entering the grid are treated.
isCommaAsDecimalSeparator
Inquiry method that gets the type of interpretation to be used to parse the sort field values in order to perform numeric sort.
isDescendingSort
Inquiry method that gets the sort direction currently configured.
isHtmlInterpretationEnabled
Inquiry method that gets the type of interpretation to be applied for the pushed values for this grid.
isNumericSort
Inquiry method that gets the type of sort currently configured.
parseHtml
Operation method that is used to authorize and execute the binding of the widget with the HTML of the page.
setAddOnTop
Setter method that decides whenever new rows entering the model will be placed at the top of the grid or at the bottom.
setHtmlInterpretationEnabled
Setter method that enables or disables the interpretation of the values in the model as HTML code.
setNodeTypes
Setter method that specifies a list of HTML element types to be searched for during the mapping of the grid to the HTML made by AbstractGrid#parseHtml.
setSort
Setter method that configures the sort policy of the grid.

Inherited Methods

| clean | getValue | onClearSnapshot | onCommandSecondLevelItemLostUpdates | onCommandSecondLevelSubscriptionError | onEndOfSnapshot | onItemLostUpdates | onItemUpdate | onListenEnd | onListenStart | onSubscription | onSubscriptionError | onUnsubscription | removeRow | setAutoCleanBehavior | updateRow |

Method Detail

extractCommandSecondLevelFieldList() → {Array}

Creates an array containing all the unique values, of the "data-field" properties in all of the HTML elements, having the "data-fieldtype" property set to "second-level", associated to this grid during the AbstractGrid#parseHtml execution.
The result of this method is supposed to be used as "Field List" of a second-level Subscription.
Execution of this method is pointless if HTML elements associated to this grid specify a field position instead of a field name in their "data-field" property.
See:
Returns:
The list of unique values found in the "data-field" properties of HTML element of this grid.
Type
Array

extractFieldList() → {Array}

Creates an array containing all the unique values of the "data-field" properties in all of the HTML elements associated to this grid during the AbstractGrid#parseHtml execution. The result of this method is supposed to be used as "Field List" of a Subscription.
Execution of this method is pointless if HTML elements associated to this grid specify a field position instead of a field name in their "data-field" property.
Note that elements specifying the "data-fieldtype" property set to "extra" or "second-level", will be ignored by this method. This permits to distinguish fields that are part of the main subscription (not specifying any "data-fieldtype" or specifying "first-level"), part of a second-level Subscription (specifying "second-level") and not part of a Subscription at all, but still manageable in a direct way (specifying "extra").
See:
Returns:
The list of unique values found in the "data-field" properties of HTML element of this grid.
Type
Array

forceSubscriptionInterpretation(interpretation)

Operation method that is used to force the choice of what to use as key for the integration in the internal model, when receiving an update from a Subscription this grid is listening to.
Specifying "ITEM_IS_KEY" tells the widget to use the item as key; this is the behavior that is already the default one when the Subscription is in "MERGE" or "RAW" mode (see AbstractWidget for details).
Specifying "UPDATE_IS_KEY" tells the widget to use a progressive number as key; this is the behavior that is already the default one when the Subscription is in "DISTINCT" mode (see AbstractWidget for details).
Note that when listening to different Subscriptions the default behavior is set when the grid is added as listener for the first one and then applied to all the others regardless of their mode.

Lifecycle:this method can only be called while the internal model is empty.

Parameters:
Name Type Description
interpretation String either "ITEM_IS_KEY" or "UPDATE_IS_KEY", or null to restore the default behavior.
Throws:

getNodeTypes() → {Array}

Inquiry method that gets the list of node of types that would be searched in case of a call to AbstractGrid#parseHtml.
See:
Returns:
a list of node type names.
Type
Array

getSortField() → {Number}

Inquiry method that gets the name of the field currently used as sort field, if available.
See:
Returns:
The name of a field, or null if sorting is not currently enabled.
Type
Number

isAddOnTop() → {boolean}

Inquiry method that gets true/false depending on how new rows entering the grid are treated. If true is returned, new rows will be placed on top of the grid. Viceversa, if false is returned, new rows are placed at the bottom.
See:
Returns:
true if new rows are added on top, false otherwise.
Type
boolean

isCommaAsDecimalSeparator() → {boolean}

Inquiry method that gets the type of interpretation to be used to parse the sort field values in order to perform numeric sort.
See:
Returns:
true if comma is the decimal separator, false if it is a dot; returns null if sorting is not currently enabled or numeric sorting is not currently configured.
Type
boolean

isDescendingSort() → {boolean}

Inquiry method that gets the sort direction currently configured.
See:
Returns:
true if descending sort is being performed, false if ascending sort is, or null if sorting is not currently enabled.
Type
boolean

isHtmlInterpretationEnabled() → {boolean}

Inquiry method that gets the type of interpretation to be applied for the pushed values for this grid. In fact, the values can be put in the target cells as HTML code or as text.
See:
Returns:
true if pushed values are interpreted as HTML code, false otherwise.
Type
boolean

isNumericSort() → {boolean}

Inquiry method that gets the type of sort currently configured.
See:
Returns:
true if numeric sort is being performed, false if alphabetical sort is, or null if sorting is not currently enabled.
Type
boolean

parseHtml()

Operation method that is used to authorize and execute the binding of the widget with the HTML of the page.

Lifecycle: This method can only be called once the HTML structure the instance is expecting to find are ready in the DOM. That said, it can be invoked at any time and subsequent invocations will update the binding to the current state of the page DOM. Anyway, newly found cells will be left empty until the next update involving them.

Overrides:
See:

setAddOnTop(isAddOnTop)

Setter method that decides whenever new rows entering the model will be placed at the top of the grid or at the bottom.
Note that if the sort is enabled on the Grid through AbstractGrid#setSort then this setting is ignored as new rows will be placed on their right position based on the sort configuration.
Also note that the sort/add policy may be ignored depending on the grid configuration; see the use of the "data-item" cell attribute in StaticGrid.

Default value: false.

Lifecycle: this setting can be changed at any time.
Note anyway that changing this setting while the internal model is not empty may result in a incosistent view.

Parameters:
Name Type Description
isAddOnTop boolean true/false to place new rows entering the model as the first/last row of the grid.
Throws:
if the given value is not a valid boolean value.
Type
IllegalArgumentException

setHtmlInterpretationEnabled(enable)

Setter method that enables or disables the interpretation of the values in the model as HTML code. For instance, if the value "<a href='news03.htm'>Click here</a>" is placed in the internal model (either by manual call of the AbstractWidget#updateRow method or by listening on a SubscriptionListener#onItemUpdate event) and HTML interpretation is enabled, then the target cell will contain a link; otherwise it will contain that bare text. Note that the setting applies to all the cells in the associated grid. Anyway if it's not the content of a cell that is going to be updated, but one of its properties, then this setting is irrelevant for such cell.
WARNING: When turning HTML interpretation on, make sure that no malicious code may reach the internal model (for example through the injection of undesired JavaScript code from the Data Adapter).

Default value: false.

Lifecycle: this setting can be changed at any time.
Note that values that have already been placed in the grid cells will not be updated to reflect the new setting.

Parameters:
Name Type Description
enable boolean true/false to enable/disable HTML interpretation for the pushed values.
Throws:

setNodeTypes(nodeTypes)

Setter method that specifies a list of HTML element types to be searched for during the mapping of the grid to the HTML made by AbstractGrid#parseHtml.

Default value: an array containing DIV SPAN and INPUT.

Lifecycle: Node types can be specified at any time. However, if the list is changed after the execution of the AbstractGrid#parseHtml method then it will not be used until a new call to such method is performed.

Parameters:
Name Type Description
nodeTypes Array an array of Strings representing the names of the node types to be searched for. If the array contains an asterisk (*) then all the node types will be checked.
See:

setSort(sortField, descendingSortopt, numericSortopt, commaAsDecimalSeparatoropt)

Setter method that configures the sort policy of the grid. If no sorting policy is set, new rows are always added according with the AbstractGrid#setAddOnTop setting. If, on the other hand, sorting is enabled, then new rows are positioned according to the sort criteria. Sorting is also maintained upon update of an existing row; this may cause the row to be repositioned.
If asynchronous row repositioning is undesired, it is possible to set the sort and immediately disable it with two consecutive calls to just enforce grid sorting based on the current contents.
The sort can also be performed on fields that are part of the model but not part of the grid view.
Note that the sort/add policy may be ignored depending on the grid configuration; see the use of the "data-item" cell attribute in StaticGrid.

Default value: no sort is performed.

Lifecycle: The sort configuration can be set and changed at any time.

Parameters:
Name Type Argument Default Description
sortField String The name of the field to be used as sort field, or null to disable sorting.
descendingSort boolean <optional>
 false true or false to perform descending or ascending sort. This parameter is optional; if missing or null, then ascending sort is performed.
numericSort boolean <optional>
 false true or false to perform numeric or alphabetical sort. This parameter is optional; if missing or null, then alphabetical sort is performed.
commaAsDecimalSeparator boolean <optional>
 false true to specify that sort field values are decimal numbers in which the decimal separator is a comma; false to specify it is a dot. This setting is used only if numericSort is true, in which case it is optional, with false as its default value.
Throws:
if one of the boolean parameters is neither missing, null, nor a valid boolean value.
Type
IllegalArgumentException