DynaGrid

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.

Removes all the rows from the model and reflects the change on the view.

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

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.

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").

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.

Inquiry method that gets the current number of nonempty logical pages needed to show the rows in the internal model.

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

Inquiry method that gets the maximum number of visible rows allowed in the grid.

Inquiry method that gets the list of node of types that would be searched in case of a call to AbstractGrid#parseHtml.

Inquiry method that gets the name of the field currently used as sort field, if available.

Returns the value from the model for the specified key/field pair. If the row for the specified key does not exist or if the specified field is not available in the row then null is returned.

Lifecycle: This method can be called at any time.

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.

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.

Inquiry method that gets the type of interpretation to be used to parse the sort field values in order to perform numeric sort.

Inquiry method that gets the sort direction currently configured.

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.

Inquiry method that gets the type of sort currently configured.

Event handler that is called by Lightstreamer each time a request to clear the snapshot pertaining to an item in the Subscription has been received from the Server. More precisely, this kind of request can occur in two cases:

• For an item delivered in COMMAND mode, to notify that the state of the item becomes empty; this is equivalent to receiving an update carrying a DELETE command once for each key that is currently active.
• For an item delivered in DISTINCT mode, to notify that all the previous updates received for the item should be considered as obsolete; hence, if the listener were showing a list of recent updates for the item, it should clear the list in order to keep a coherent view.

Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). This kind of notification is not possible for second-level items (which are in MERGE mode).
This event can be sent by the Lightstreamer Server since version 6.0

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item that was subscribed to as a second-level subscription. Such notifications are sent only if the Subscription was configured in unfiltered mode (second-level items are always in "MERGE" mode and inherit the frequency configuration from the first-level Subscription).
By implementing this method it is possible to perform recovery actions.

Event handler that is called when the Server notifies an error on a second-level subscription.
By implementing this method it is possible to perform recovery actions.

Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the Subscription have been received, so that real time events are now going to be received. The received snapshot could be empty. Such notifications are sent only if the items are delivered in DISTINCT or COMMAND subscription mode and snapshot information was indeed requested for the items. By implementing this method it is possible to perform actions which require that all the initial values have been received.
Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). Snapshot-related updates for the second-level items (which are in MERGE mode) can be received both before and after this notification.

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription. Such notifications are sent only if the items are delivered in an unfiltered mode; this occurs if the subscription mode is:

• RAW
• MERGE or DISTINCT, with unfiltered dispatching specified
• COMMAND, with unfiltered dispatching specified
• COMMAND, without unfiltered dispatching specified (in this case, notifications apply to ADD and DELETE events only)

By implementing this method it is possible to perform recovery actions.

Event handler that is called by Lightstreamer each time an update pertaining to an item in the Subscription has been received from the Server.

Event handler that receives a notification when the SubscriptionListener instance is removed from a Subscription through Subscription#removeListener. This is the last event to be fired on the listener.

Event handler that receives a notification when the SubscriptionListener instance is added to a Subscription through Subscription#addListener. This is the first event to be fired on the listener.

Event handler that is called by Lightstreamer to notify the client with the real maximum update frequency of the Subscription. It is called immediately after the Subscription is established and in response to a requested change (see Subscription#setRequestedMaxFrequency). Since the frequency limit is applied on an item basis and a Subscription can involve multiple items, this is actually the maximum frequency among all items. For Subscriptions with two-level behavior (see Subscription#setCommandSecondLevelFields and Subscription#setCommandSecondLevelFieldSchema) , the reported frequency limit applies to both first-level and second-level items.
The value may differ from the requested one because of restrictions operated on the server side, but also because of number rounding.
Note that a maximum update frequency (that is, a non-unlimited one) may be applied by the Server even when the subscription mode is RAW or the Subscription was done with unfiltered dispatching.

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully subscribed to through the Server. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.
This notification is always issued before the other ones related to the same subscription. It invalidates all data that has been received previously.
Note that two consecutive calls to this method are not possible, as before a second onSubscription event is fired an onUnsubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level subscriptions are not notified.

Event handler that is called when the Server notifies an error on a Subscription. By implementing this method it is possible to perform recovery actions.
Note that, in order to perform a new subscription attempt, LightstreamerClient#unsubscribe and LightstreamerClient#subscribe should be issued again, even if no change to the Subscription attributes has been applied.

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully unsubscribed from. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.

After this notification no more events can be recieved until a new SubscriptionListener#onSubscription event.
Note that two consecutive calls to this method are not possible, as before a second onUnsubscription event is fired an onSubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level unsubscriptions are not notified.

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.

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

Lifecycle: a listener can be removed at any time.

Removes a row from the internal model and reflects the change on the view. If no row associated with the given key is found nothing is done.

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

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.

Utility method that can be used to control part of the behavior of the widget in case it is used as a listener for one or more Subscription instances.
Specifying the two flags it is possible to decide to clean the model and view based on the status (subscribed or not) of the Subscriptions this instance is listening to.

Lifecycle: This method can be called at any time.

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.

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.

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.

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.

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.

Updates a row in the internal model and reflects the change on the view. If no row associated with the given key is found then a new row is created.
Example usage:
myWidget.updateRow("key1", {field1:"val1",field2:"val2"});

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time. If called while an updateRow on the same internal model is still executing (e.g. if called while handling an onVisualUpdate callback), then the new update:

• if pertaining to a different key and/or if called on a Chart instance, will be postponed until the first updateRow execution terminates;
• if pertaining to the same key and if called on a StaticGrid / DynaGrid instance, will be merged with the current one.