Class: DynaGrid

DynaGrid

An AbstractGrid implementation that can be used to display the values from the internal model in a dynamically created grid. The HTML structure suitable for the visualization of the tabular model values is dynamically maintained by Lightstreamer, starting from an HTML hidden template row, containing cells. The template row can be provided as any HTML element owning the "data-source='Lightstreamer'" special attribute.
The association between the DynaGrid and the HTML template is made during the execution of the AbstractGrid#parseHtml method: it is expected that the element representing the template row, in addition to the special "data-source" custom attribute, has an HTML "ID" attribute containing a unique value that has to be passed to the constructor of this class. The template will be then searched for by "id" on the page DOM.
Once the association is made with the row template, the cells within it have to be recognized: all the elements of the types specified in the AbstractGrid#setNodeTypes are scanned for the "data-source='Lightstreamer'" attribute that authorizes the library to track the HTML element as a cell for the row.

The "data-field" attribute will then instruct the library about what field of the internal model has to be associated with the cell.
It is possible to associate more cells with the same field. An optional "data-replica" attribute can be specified in this case. If used it will permit to access the single cells during DynaGridListener#onVisualUpdate executions.

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).
For each update to the internal model, the involved row is determined and each value is displayed in the proper cell(s). If necessary, new rows are cloned from the hidden template and attached to the DOM, or existing rows are dropped. The position of new rows is determined by the AbstractGrid#setAddOnTop or AbstractGrid#setSort settings.
In fact, there is a 1:1 correspondence between rows in the underlying model and rows in the grid; however, pagination is also supported, so that only a subset of the grid can be made visible.

Note that the template element can contain an arbitrary HTML structure and should contain HTML cells to be used to display the row field values. However, it should not contain elements to which an HTML "id" attribute has been assigned, because the elements will be cloned and the HTML specification prescribes that an id must be unique in the document. (The id of the template element, required by Lightstreamer, is not cloned).
More visualization actions can be performed through the provided VisualUpdate event objects received on the DynaGridListener.

new DynaGrid(id, autoParse)

Creates an object that extends AbstractGrid displaying its values in a grid made of HTML elements. The grid rows are displayed into dynamically generated 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 The HTML "id" attribute of the HTML element that represents the template from which rows of the grid will be cloned. The template can be either a visible or a hidden part of the page; anyway, it will become invisible as soon as the AbstractGrid#parseHtml method is executed.
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 DynaGrid instance creation, the HTML element designated as template is not yet ready on the page.

Extends

Method Summary

addListener
Adds a listener that will receive events from the DynaGrid instance.
getCurrentPages
Inquiry method that gets the current number of nonempty logical pages needed to show the rows in the internal model.
getListeners
Returns an array containing the DynaGridListener instances that were added to this client.
getMaxDynaRows
Inquiry method that gets the maximum number of visible rows allowed in the grid.
goToPage
Operation method that shows a particular logical page in the internal model.
removeListener
Removes a listener from the DynaGrid instance so that it will not receive events anymore.
setAutoScroll
Setter method that enables or disables the automatic adjustment of the page or element scrollbars at each new update to focus on the most recently updated row.
setMaxDynaRows
Setter method that sets the maximum number of visible rows allowed in the grid.

Inherited Methods

| extractCommandSecondLevelFieldList | extractFieldList | forceSubscriptionInterpretation | getNodeTypes | getSortField | getValue | isAddOnTop | isCommaAsDecimalSeparator | isDescendingSort | isHtmlInterpretationEnabled | isNumericSort | onClearSnapshot | onCommandSecondLevelItemLostUpdates | onCommandSecondLevelSubscriptionError | onEndOfSnapshot | onItemLostUpdates | onItemUpdate | onListenEnd | onListenStart | onSubscription | onSubscriptionError | onUnsubscription | removeRow | setAddOnTop | setAutoCleanBehavior | setHtmlInterpretationEnabled | setNodeTypes | setSort | updateRow |

Method Detail

addListener(listener)

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

Lifecycle: a listener can be added at any time.

Parameters:
Name Type Description
listener DynaGridListener An object that will receive the events as shown in the DynaGridListener interface.
Note that the given instance does not have to implement all of the methods of the DynaGridListener 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.

getCurrentPages() → {Number}

Inquiry method that gets the current number of nonempty logical pages needed to show the rows in the internal model.
Returns:
The current number of logical pages. If pagination is not active 1 is returned.
Type
Number

getListeners() → {Array}

Returns an array containing the DynaGridListener 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

getMaxDynaRows() → {Number}

Inquiry method that gets the maximum number of visible rows allowed in the grid.
See:
Returns:
The maximum number of visible rows allowed, or the String "unlimited", to notify that the grid is allowed to grow without limits.
Type
Number

goToPage(pageNumber)

Operation method that shows a particular logical page in the internal model.

Lifecycle: once the AbstractGrid#parseHtml method has been called, this method can be used at any time.

Parameters:
Name Type Description
pageNumber Number The number of the logical page to be displayed. The request is accepted even if the supplied number is higher than the number of currently available logical pages, by displaying an empty logical page, that may become nonempty as soon as enough rows are added to the internal model.
See:
Throws:

removeListener(listener)

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

Lifecycle: a listener can be removed at any time.

Parameters:
Name Type Description
listener DynaGridListener The listener to be removed.

setAutoScroll(type, elementId)

Setter method that enables or disables the automatic adjustment of the page or element scrollbars at each new update to focus on the most recently updated row. If a growing grid is included in an HTML element that declares (and supports) the "overflow" attribute then this element may develop a vertical scrollbar in order to contain all the rows. Also if the container elements do not declare any "overflow" CSS property, then the same may happen to the entire HTML page. In such a cases new rows added to the grid (or moved due to the sort settings) may be placed in the nonvisible part of the including element/page.
This can be avoided by enabling the auto-scroll. In this case, each time a row is added or updated, the scrollbar is repositioned to show the row involved. This feature, however, should be used only if the update rate is low or if this grid is listening to a DISTINCT Subscription; otherwise, the automatic scrolling activity may be excessive.
Note that in case the grid is configured in UPDATE_IS_KEY mode (that is the default mode used when the grid is listening to a DISTINCT subscription) and the scrollbar is moved from its automatic position, then the auto-scroll is disabled until the scrollbar is repositioned to its former position. This automatic interruption of the auto scrolling is not supported on pre-webkit Opera browsers.
The auto-scroll is performed only if single page mode is currently used (i.e. the maximum number of visible rows is set to unlimited).

Default value: "OFF".

Lifecycle: The auto-scroll policy can be set and changed at any time.

Parameters:
Name Type Description
type String The auto-scroll policy. Permitted values are:
  • "OFF": No auto-scrolling is required;
  • "ELEMENT": An element's scrollbar should auto-scroll;
  • "PAGE": The browser page's scrollbar should auto-scroll.
elementId String The HTML "id" attribute of the HTML element whose scrollbar should auto-scroll, if the type argument is "ELEMENT"; not used, otherwise.
See:

setMaxDynaRows(maxDynaRows)

Setter method that sets the maximum number of visible rows allowed in the grid. If a value for this property is set, then Lightstreamer maintains a paging mechanism, such that only one logical page is displayed at a time. Logical page 1 is shown by default, but each logical page can be shown by calling the DynaGrid#goToPage method.
Note that, due to the dynamical nature of the grid, logical pages other than page 1 may underlie to scrolling caused by operations on rows belonging to lower logical pages; this effect is emphasized if sorting is active.
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 limit posed by this setting is reached, adding a new row will always cause the removal of the oldest row from the model, with a consequent repositioning of the remaining rows.

Default value: "unlimited".

Lifecycle: this setting can be set and changed at any time. If the internal model is not empty when this method is called, it will cause the immediate adjustment of the rows to reflect the change. Moreover, if applicable, the current logical page is automatically switched to page 1.

Parameters:
Name Type Description
maxDynaRows Number The maximum number of visible rows allowed, or the string "unlimited", to mean that the grid is allowed to grow without limits, without the need for paging (the check is case insensitive).