Class MetapushTable

Object
   |
   +--Table
         |
         +--VisualTable
               |
               +--MetapushTable

class MetapushTable

extends VisualTable

A data table that can be fed with real-time data delivered by Lightstreamer Server and displayed into a screen table according to ADD, UPDATE and DELETE commands received as pushed values, which instruct the data table to add a row, just modify values on a row or delete a row. We call this a "COMMAND logic" behaviour. 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.cellMetapush(), 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 "row", "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.
For each pushed update, the involved row is determined and each value is displayed in a cell that is associated to the involved row and field. Scrolling operations on rows that are already displayed may be performed too. By default the new/scrolled 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/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 row-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 rows that are added or scrolled down to row numbers for which no cells have been configured will not be displayed; however, they may be displayed again, if they are scrolled up after deletion of preceding rows.
More visualization actions can be performed through the event handlers provided.
See:

- FieldDescriptor
- ScreenTableHelper

Constructor Detail

MetapushTable

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

Creates an object to be used to describe a data table to be managed with a "COMMAND logic" behaviour. The table rows are 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. Usually, the group consists of just one item, whose updates are commands that specify whether to ADD, UPDATE or DELETE data table rows. If the group consists of more than one item, then the updates for the different items are simply mixed and concur to the maintenance of the same data table. However, if the same key is used by different items, it refers to distinct rows on the data table.
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. If COMMAND subscription mode is specified, then the special "key" and "command" fields are automatically added.
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 suited for COMMAND mode.

See:
- FieldDescriptor
- ScreenTableHelper

getMetapushSortField

Number getMetapushSortField()

Inquiry method that gets the index of the field currently used as sort field, if available. Calling the getMetapushSortFieldName() method may also be needed in order to determine if a sort field is used.

Returns:
A 1-based field index, or null if sorting is not currently enabled. A null value is also returned if the sort field is an extra field defined by a field name.

See:
- setMetapushSort()

getMetapushSortFieldName

String getMetapushSortFieldName()

Inquiry method that gets the name of the field currently used as sort field, if available. Calling the getMetapushSortField() method may also be needed in order to determine if a sort field is used.

Returns:
A field name, or null if sorting is not currently enabled. A null value is also returned if a field name for the sort field is not available, either because a schema identifier has been used as group descriptor for the data table or because the field is an extra field defined by a field position.

See:
- setMetapushSort()

isCommaAsDecimalSeparator

boolean isCommaAsDecimalSeparator()

Inquiry method that gets the type of interpretation to be used to parse the sort field values in order to perform numeric sort.
Note that the parsing is not needed for values set as Number objects in an extra field.

Returns:
true if comma is the decimal separator, false if it is a dot; returns null if sorting is not currently enabled or numeric sorting is not currently configured.

See:
- setMetapushSort()

isDescendingSort

boolean isDescendingSort()

Inquiry method that gets the sort direction currently configured.

Returns:
true if descending sort is being performed, false if ascending sort is, or null if sorting is not currently enabled.

See:
- setMetapushSort()

isNumericSort

boolean isNumericSort()

Inquiry method that gets the type of sort currently configured.

Returns:
true if numeric sort is being performed, false if alphabetical sort is, or null if sorting is not currently enabled.

See:
- setMetapushSort()

onChangingValues

void onChangingValues(<VisualUpdateInfo> updateInfo)

Event handler that is called by Lightstreamer each time a row of the data table, containing the values of the fields for a key, has been added (because of an ADD command) or changed (because of an UPDATE command). 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.
Before displaying the row on the cells, the onRowUpdate() event handler is also called.

Default implementation: do nothing, i.e. leave the default display settings, which means:
• use the unformatted values for the fields
• 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 command (in case of an UPDATE command)

Parameters:
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.
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.

onRowUpdate

void onRowUpdate(<Number> rowNumber, <RowInfo> rowInfo)

Event handler that receives the notification that a row of the data table is being displayed on the corresponding cells. This may happen:
• in order to display new pushed values, because of an ADD command
• because of an UPDATE command for the row key
• because of a scroll operation, caused by an ADD or DELETE command that affects a preceding row
• because of a scroll operation, caused by the repositioning of some key; this can happen after an UPDATE command on that key, if a sort criterion is assigned to the data table
• in order to clear the last row displayed on the screen table, after a DELETE command has been received with a total number of rows in the data table that is not greater than the number of rows in the screen table.
• in order to clear the screen table. In this case, note that the row may have been displayed in the context of a different data table, if false was set by VisualTable.setClearOnRemove() for that data table
By setting a custom handler it is possible to perform custom display operations for the screen table rows in way consistent with scrolling and clearing operations on the screen table.
Note that rows may be added or scrolled down to assume row numbers for which no cells have been configured. These rows are not displayed, so this notification is not issued in these cases.

Default implementation: do nothing, i.e. don't perform custom display operations.

Parameters:
rowNumber - The number of the row which is being update. It always refers to a visible row, i.e. a row that exists in the screen table.
rowInfo - a value object containinig the formatted values to be displayed for the row fields.
rowInfo 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 RowInfo 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.

See:
- setLastVisibleRow()

setLastVisibleRow

void setLastVisibleRow(<Number> rowNumber)

Setter method that specifies the row number of the last row in the screen table. Usually, it corresponds to the highest row number assigned to at least one HTML cell defined in the screen table. However, this may not always be the case. For example, if custom display operations have to be performed on the data table values, it is possible that no HTML cells at all are defined for the screen table, but a nonzero number of visible rows is declared, so that the onChangingValues() and onRowUpdate() event handlers are called and custom display operations can be performed.

Invocation: optional.

Default value: the highest row number for which an HTML cell has been defined in the page

Lifecycle: The number of the last visible row 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 number is used.

Parameters:
rowNumber - the 1-based row number of the last visible row.

setMetapushFields

void setMetapushFields(<Number> commandPos, <Number> keyPos)

Setter method that configures the special metapush fields. Each update for a metapush data table should supply a "command" (whether to ADD a new row, UPDATE an existing row or DELETE an existing row) and a "key", that uniquely identifies the row involved. This is accomplished through two special fields, named "command" and "key" respectively, that are joined to the other row data fields and are always provided by an item subscribed in COMMAND mode.
If a field name array has been used as schema descriptor for the data table, then the "command" and "key" field should be included in the array (if null is supplied as schema descriptor, then the two fields are automatically included). If, however, a schema identifier has been used as schema descriptor, then the positions of these two fields have to be supplied through this method.
The "command" field (and the "key" field as well, if needed) may be left hidden, by not defining cells for them. On the other hand, extra fields cannot be used as "command" and "key" fields.

Invocation: required, but only if a schema identifier has been used as schema descriptor.

Default value: the fields named as "command" and "key", respectively, but only if a schema identifier has not been used as schema descriptor.

Lifecycle: The special metapush fields configuration should be done before bringing the data table to "running" state through PushPage.addTable() for the first time, but only if a schema identifier has been used as schema descriptor. Otherwise, the default values should be kept.

Parameters:
commandPos - 1-based index of the "command" field.
keyPos - 1-based index of the "key" field.

See:
- SchemaDescriptor

setMetapushSort

void setMetapushSort(<FieldDescriptor> sortField, <boolean> descendingSort, <boolean> numericSort, <boolean> commaAsDecimalSeparator)

Setter method that configures the sort policy of the data table. If no sorting policy is set, new rows are always added as the last rows in the data table. If, on the other hand, sorting is enabled, then new rows are positioned according to the sort criterion and updating row values also may cause the row to be repositioned.
The sort can only be performed on the unformatted values of a single field. If a different and more complex kind of sort is needed, it can be performed with the help of a further special field, that can be computed, based on the other fields and according to the sort criterion required, in the Table.onItemUpdate() event handler; such field can be left hidden, by not defining cells for it.

Invocation: optional.

Default value: no sort is performed

Lifecycle: The sort configuration 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 settings are applied.

Parameters:
sortField - a field descriptor object for the field to be used as sort field, or null to disable sorting. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
descendingSort - [Optional] true or false to perform descending or ascending sort. This parameter is optional; if missing or null, then ascending sort is performed.
numericSort - [Optional] true or false to perform numeric or alphabetical sort. This parameter is optional; if missing or null, then alphabetical sort is performed.
commaAsDecimalSeparator - [Optional] true to specify that sort field values are decimal numbers in which the decimal separator is a comma; false to specify it is a dot. This setting is used only if numericSort is true, in which case it is optional, with false as its default value.