Class OverwriteTable

Object
   |
   +--Table
         |
         +--VisualTable
               |
               +--OverwriteTable

class OverwriteTable

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 newer values for a field of an item overwrite older ones. 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 should be made of a matrix of HTML cells. Such cells can be defined at page loading, through PushPage.cellOverwrite(), or can be attached to the page DOM at any time, as DIV, SPAN or INPUT elements owning the "source='Lightstreamer'" special attribute, together with proper "item", "field" and "table" attributes; the latter 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. A ScreenTableHelper can also be used to this purpose also enabling the possibility to specify tags other than SPAN DIV and INPUT.
Each pushed value is displayed in a cell that is associated to the involved item and field. By default the new value will replace 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/item association depends on the value specified in the "item" attribute of each cell, which should be a valid item descriptor. Similarly, 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 item-field combination is supported.
The initial contents and stylesheets supplied to the cells will also be used when cell clearing has to be performed (the stylesheet used is the one supplied through the "class" attribute).
Note that the HTML cells form a "logical" matrix, determined by the "item" and "field" attribute values, but this is not a constraint on the placement of the cells in the page or even in the HTML structure. In particular, if the group consists of just one item, it may not represent a row of data, but rather an aggregate of independent values.
More visualization actions can be performed through the event handlers provided.
See:

- ItemDescriptor
- FieldDescriptor
- ScreenTableHelper

Constructor Detail

OverwriteTable

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

Creates an object to be used to describe a data table whose values should be displayed into existing HTML cells. 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 values for the data table rows. Each item in the group is associated to a data table row. An Array of item names or a String group identifier can also be used directly, instead of a group descriptor object.
In case a GroupListDescriptor or an item name array is specified, item names can be used in the cells as item descriptors; otherwise, only item positions can be used.
A null value is also allowed. In this case, the names for the items should be supplied by the associated screen tables; hence, item names should be used in the cells as item descriptors.
Note that, in case a GroupListDescriptor, 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.
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 MERGE mode, but can be used also with DISTINCT and RAW modes.

See:
- ItemDescriptor
- FieldDescriptor
- ScreenTableHelper

onChangingValues

void onChangingValues(<Number> itemPos, <VisualUpdateInfo> updateInfo, <String> itemName)

Event handler that is called by Lightstreamer each time an update pertaining to an item in the data table is being shown on the associated screen 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 item.
This event handler is also called in case of screen table clearing, in order to allow clearing actions related to custom display actions previously performed for the item. Note that the row about to be cleared 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:
• write cells values unformatted
• don't change the cell stylesheet
• don't perform temporary effects on the cell
• don't change the cell at all for fields whose value has not changed with the current update

Parameters:
itemPos - 1-based index of the item within the group.
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 initial contents and stylesheets supplied to the cells will be used to perform the clearing.
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.
itemName - name of the involved item. If a group identifier has been used as group descriptor for the data table, then a null value is supplied.