Class DynaScrollTable

Object
   |
   +--Table
         |
         +--VisualTable
               |
               +--DynaScrollTable

class DynaScrollTable

extends VisualTable

A data table that can be fed with real-time data delivered by Lightstreamer Server and displayed into a screen table in such a way that new updates add new rows to the page. The class contains the subscription details and the event handlers needed to allow Lightstreamer to display the real-time data.
A screen table suitable for the visualization of pushed 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 "source='Lightstreamer'" special attribute, while the element "ID" attribute defines the screen table id. The association is made when the data table is brought to the "running" state, through the identifier supplied to PushPage.addTable(), that must match the screen table id. The contained cells are defined as any DOM elements owning the "source='Lightstreamer'" special attribute, together with a "field" attribute.
For each pushed update, a new row is cloned from the hidden template and attached after it; then, each value is displayed in a cell inside the new row that is associated to the involved field. By default the new value will be set as the cell's content (or its value in case the cell is an INPUT or a TEXTAREA element). It is possible to override this behavior by specifying a special "update" attribute containing the name of the attribute of the cell to be updated. Any string can be specified; moreover a value of a stylesheet can be specified using the "style.attribute" form (note that the DOM attribute name should be used, not the CSS name; e.g. "style.backgroundColor" is correct, while "style.background-color" is not). WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code will be pushed by the Data Adapter (for example through the injection of undesired JavaScript code).
NOTE: the cell/field association depends on the value specified in the "field" attribute of each cell, which should be a valid field descriptor. Only one cell for each field is supported in the template.
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 ID 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 event handlers.
See:

- FieldDescriptor

Constructor Detail

DynaScrollTable

DynaScrollTable(<GroupDescriptor> tGroup, <SchemaDescriptor> tSchema, <String> tSubscriptionMode)

Creates an object to be used to describe a data table whose values should be displayed and cumulated into dynamically generated HTML rows. The object can be supplied to PushPage.addTable() and PushPage.removeTable(), in order to bring the data table to "running" or back to "inactive" state.

Parameters:
tGroup - A group descriptor object, which identifies the items that provide the data table rows. Usually, the group consists of just one item and the data table maintains the history of all updates for that item. If the group consists of more than one item, then the updates for the different items are simply mixed and displayed as a unique update sequence.
An Array of item names or a String group identifier can also be used directly, instead of a group descriptor object.
Note that, in case a GroupListDescriptor or an array is used, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSchema - A schema descriptor object, which identifies the fields that represent the data table columns. An Array of field names or a String schema identifier can also be used directly, instead of a schema descriptor object.
In case a SchemaListDescriptor or a field name array is specified, field names can be used in the cells as field descriptors; otherwise, only field positions can be used.
A null value is also allowed. In this case, the names for the fields should be supplied by the associated screen tables; hence, field names should be used in the cells as field descriptors. Names starting with a "#" character will be treated as extra fields and not included in the schema.
Note that, in case a SchemaListDescriptor, an array or a null value is supplied, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSubscriptionMode - the subscription mode for the items, required by Lightstreamer Server. This kind of data table is particularly suited for DISTINCT mode, but can be used also with MERGE and RAW modes.

See:
- FieldDescriptor

getMaxDynaRows

Number getMaxDynaRows()

Inquiry method that gets the maximum number of rows allowed in the data table. When this limit is reached, adding a new row will always cause the removal of the oldest row.

Returns:
The maximum number of rows allowed, or the String "unlimited", to notify that the data table is allowed to grow without limits.

onChangingValues

void onChangingValues(<DOMElement> domNode, <VisualUpdateInfo> updateInfo)

Event handler that is called by Lightstreamer each time a new update is received, so that a new row enters the data table. By setting a custom handler, it is possible to perform custom formatting on the field values, to set the cells stylesheets and to control the display policy. In addition, through a custom handler it is possible to perform custom display actions for the row.
This event handler is also called when the row exits the data table, to allow clearing actions related to custom display actions previously performed for the row. This may happen in case of screen table clearing or in case of destruction of the last row caused by exceeding the maximum allowed number of rows.
Note that a row that is about to exit the table may have been displayed in the context of a different data table, if false was set by VisualTable.setClearOnRemove() for that data table.

Default implementation: do nothing, i.e. leave the default display settings, which means:
• use the unformatted values for the fields
• use the cell default stylesheet
• don't perform temporary effects on the cell

Parameters:
domNode - The DOM pointer to the HTML row involved. The row element has been created by Lightstreamer, by cloning the template row supplied through PushPage.addTable(). Note that the HTML cells contained in the row element should not be accessed, as they are reserved to Lightstreamer.
updateInfo - a value object containinig the updated values for all the fields, together with the formatted values and the display settings for the fields. The desired settings can be set in the object, to substitute the default settings, before returning.
updateInfo can also be null, to notify a clearing action. In this case, the row is removed from the page.
Note that the VisualUpdateInfo instance supplied to the method may be reused by Lightstreamer across subsequent calls; so, it should not be stored and used after the method termination.

setAutoScroll

void setAutoScroll(<String> type, <String> elementId)

Setter method that enables or disables the automatic adjustment of the screen table scrollbars at each new update. At each new update, a new HTML row is added to the page; this may cause the page to grow significantly, unless a low maximum number of rows has been configured. If a growing screen table 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. In such a case, if upward scrolling is set, then the new rows added to the screen table may be placed in the nonvisible part of the including element.
This can be avoided by enabling the auto-scroll. In this case, if the scrollbar is positioned at the bottom of the the including element, then, each time a new row is added, Lightstreamer will reposition the scrollbar at the bottom.
Note that for Opera browser family, enabling auto-scroll will always cause Lightstreamer to reposition the scrollbar at the bottom, after new rows are added.

Invocation: optional

Default value: "OFF"

Lifecycle: The auto-scroll policy can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through PushPage.addTable(), the current policy is used.

Parameters:
type - 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 - The ID of the HTML element whose scrollbar should auto-scroll, if the type argument is "ELEMENT"; not used, otherwise.

See:
- setMaxDynaRows()
- setUpwardScroll()

setMaxDynaRows

void setMaxDynaRows(<Number> maxDynaRows)

Setter method that sets the maximum number of rows allowed in the data table. When this limit is reached, adding a new row will always cause the removal of the oldest row.

Invocation: optional.

Default value: "unlimited"

Lifecycle: the maximum number of rows in the data table can be set and changed at any time. If the data table is currently in "running" state, this causes the immediate adjustment of the screen table.
Note that reducing the data table size may cause some rows to be lost. These rows will not be resumed after a subsequent data table size increase.

Parameters:
maxDynaRows - The maximum number of rows allowed, or the string "unlimited", to mean that the data table is allowed to grow without limits (the check is case insensitive).

setUpwardScroll

void setUpwardScroll(<boolean> isUpwardScroll)

Setter method that enables or disables upward scroll. When upward scroll is not active, new updates are placed at the top of the data table, so that old updates scroll downward. On the other hand, when upward scroll is active, new updates are placed at the bottom of the data table.

Invocation: optional.

Default value: false

Lifecycle: The scroll policy can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through PushPage.addTable(), the current policy is used.

Parameters:
isUpwardScroll - true/false to enable/disable upward scroll on the data table rows.