Class: StaticGrid

StaticGrid

An AbstractGrid implementation that can be used to display the values from the internal model in a statically prepared grid. The HTML structure suitable for the visualization of the tabular model values must be prepared up-front in the DOM of the page as a matrix of HTML cells. The cells making up the grid can be any HTML element owning the "data-source='Lightstreamer'" special attribute. Such cells, to be properly bound to the StatiGrid instance must also define the following custom attributes:

"data-grid": an identification string that has to be equal to the id that is specified in the constructor of this class. This id is used to properly bind a cell to its StaticGrid instance.
"data-field": the name of a field in the internal model whose value will be displayed in this cell.
"data-fieldtype" (optional): "extra", "first-level" or "second-level" to specify the type of field. If not specified "first-level" is assumed. The "data-fieldtype" property is only exploited in the AbstractGrid#extractFieldList and AbstractGrid#extractCommandSecondLevelFieldList methods.
"data-row" (only if "data-item" is not specified): a progressive number representing the number of the row associated with the cell. When a new row enters the grid its position will be decided by the AbstractGrid#setAddOnTop and AbstractGrid#setSort settings. The "data-row" attribute will define to which row a cell pertains.
Note that the maximum value available for a data-row attribute in all the cells pertaining to this StaticGrid will define the size of the view. If the number of rows in the model exceeds the number of rows defined in the HTML grid, rows that would have been displayed in the extra rows are not shown in the view but are maintained in the model.
Note that if this instance is used to listen to events from Subscription instance(s), and the first Subscription it listens to is a DISTINCT Subscription, then the behavior is different: when the number of rows in the model exceeds the number of rows defined in the HTML grid, adding a new row will always cause the removal of the oldest row from the model, with a consequent repositioning of the remaining rows.
"data-item" (only if "data-row" is not specified): the name of a row in the internal model, whose value (for the chosen field) will be displayed in this cell; this attribute should only be used if this instance is used to listen to events from Subscription instance using the MERGE mode; so, this attribute should identify the name or the 1-based position of an item in the MERGE Subscription. This way it is possible to define a static positioning for each item in the MERGE Subscription. On the contrary, by using "data-row" attributes, each item will be placed based only on the AbstractGrid#setAddOnTop and AbstractGrid#setSort settings and the positioning may depend on the arrival order of the updates.
"data-replica" (optional): this attribute can be specified in case there are more cells associated to the same field. If used, it will permit to access the single cells during StaticGridListener#onVisualUpdate executions.

The association between the StaticGrid and the HTML cells is made during the execution of the AbstractGrid#parseHtml method. Note that only the elements specified in the AbstractGrid#setNodeTypes and that are descendants of the node specified in the StaticGrid#setRootNode are taken into account, unless a list of cells has been manually specified in the constructor or through the StaticGrid#addCell method, in which case no elements other than the given ones are taken into account.
Cells already associated to the grid can be removed from the page DOM, hence from the grid, at any time. Cells already associated can also be moved or altered so that they become no longer suitable for association or other HTML elements may be made suitable, but, in this case, all changes will affect the grid only after the next invocation of AbstractGrid#parseHtml.
Make sure that all the associated cells specify the same attribute among "data-row" and "data-item"; the behavior of the grid is left unspecified when this condition is not met.

By default, the content of the HTML element designated as cell will be updated with the value from the internal model; in case the cell is an INPUT or a TEXTAREA element, the "value" property will be updated instead. It is possible to update any attribute of the HTML element or its CSS styles by specifying the "data-update" custom attribute. To target an attribute the attribute name has to be specified; it can be a standard property (e.g. "data-update='href'"), a custom "data-" attribute (e.g. "data-update='data-foo'") or even a custom attribute not respecting the "data-" standard (e.g. "data-update='foo'"). To target CSS attributes the "data-update='style.attributeName'" form has to be used (e.g. "data-update='style.backgroundColor'"); note that the form "data-update='style.background-color'" will not be recognized by some browsers.
WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code may reach the internal model (for example through the injection of undesired JavaScript code from the Data Adapter).
More visualization actions can be performed through the provided VisualUpdate event objects received on the StaticGridListener.

new StaticGrid(id, autoParse, rootEl, cells)

Creates an object that extends AbstractGrid displaying its values in a grid made of HTML elements. The grid rows are displayed into statically prepared HTML rows. The object can be supplied to Subscription#addListener and Subscription#removeListener in order to display data from one or more Subscriptions.

Parameters:

Name	Type	Description
`id`	String	An identification string to be specified in the HTML element as the data "data-grid" property value to make it possible for this StaticGrid instance to recognize its cells. The binding between the cells and the StaticGrid is performed during the AbstractGrid#parseHtml execution.
`autoParse`	boolean	If true the AbstractGrid#parseHtml method is executed before the constructor execution is completed. If false the parseHtml method has to be called later by custom code. It can be useful to set this flag to false if, at the time of the StaticGrid instance creation, the HTML elements designated as cells are not yet ready on the page.
`rootEl`	DOMElement	if specified, the cells to make up the HTML grid will only be searched in the list of descendants of this node. Equivalent to a StaticGrid#setRootNode call, but useful if autoParse is true.
`cells`	Array	an array of DOMElement instances that will make up the HTML grid for this StaticGrid instance. If specified and not empty, the parseHtml method will avoid searching cells in the DOM of the page. Equivalent to multiple StaticGrid#addCell calls, but also useful if autoParse is true.

Extends

AbstractGrid

Method Summary

addCell: Operation method that adds an HTML cell pointer to the StaticGrid.
addListener: Adds a listener that will receive events from the StaticGrid instance.
extractItemList: Creates an array containing all of the unique values of the "data-item" properties in all of the HTML elements associated to this grid during the AbstractGrid#parseHtml execution.
getListeners: Returns an array containing the StaticGridListener instances that were added to this client.
removeListener: Removes a listener from the StaticGrid instance so that it will not receive events anymore.
setRootNode: Setter method that specifies the root node to be used when searching for grid cells.

Inherited Methods

Method Detail

addCell(cellElement)

Operation method that adds an HTML cell pointer to the StaticGrid.
Note that if at least one cell is manually specified then the AbstractGrid#parseHtml will not perform any search in the DOM of the page and will only use the given cells.

Lifecycle: Cell pointers can be added to a StaticGrid at any time. However, before an HTML element is actually used as a cell by the StaticGrid a call to AbstractGrid#parseHtml is necessary.

Parameters:

Name	Type	Description
`cellElement`	DOMElement	A DOM pointer to an HTML node. The specified HTML node should be a "legal" cell for the StaticGrid (i.e. should be defined according with the requirements for the StaticGrid as described in the overview of this class). Moreover, nodes of any types are allowed.

addListener(listener)

Adds a listener that will receive events from the StaticGrid instance.
The same listener can be added to several different StaticGrid instances.

Lifecycle: a listener can be added at any time.

Parameters:

Name	Type	Description
`listener`	StaticGridListener	An object that will receive the events as shown in the StaticGridListener interface. Note that the given instance does not have to implement all of the methods of the StaticGridListener interface. In fact it may also implement none of the interface methods and still be considered a valid listener. In the latter case it will obviously receive no events.

extractItemList() → {Array}

Creates an array containing all of the unique values of the "data-item" 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 "Item List" of a Subscription.
Execution of this method is pointless if HTML elements associated to this grid through "data-item" specify an item position instead of an item name.

Returns:

The list of unique values found in the "data-item" properties of HTML element of this grid.

Type: Array

getListeners() → {Array}

Returns an array containing the StaticGridListener instances that were added to this client.

Returns:

an array containing the listeners that were added to this instance. Listeners added multiple times are included multiple times in the array.

Type: Array

removeListener(listener)

Removes a listener from the StaticGrid instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Parameters:

Name	Type	Description
`listener`	StaticGridListener	The listener to be removed.

setRootNode(rootNode)

Setter method that specifies the root node to be used when searching for grid cells. If specified, only descendants of the supplied node will be checked.
Anyway note that if nodes are explicitly set through the constructor or through the StaticGrid#addCell method, then the search will not be performed at all.

Default value: the entire document.

Lifecycle: a root node can be specified at any time. However, before a new search is performed for the StaticGrid a call to AbstractGrid#parseHtml is necessary.

Parameters:

Name	Type	Description
`rootNode`	DOMElement	a DOM node to be used as starting point when searching for grid cells.