Class DynaMetapushTable

Object
   |
   +--Table
         |
         +--VisualTable
               |
               +--DynaMetapushTable

Direct Known Subclasses:

MultiDynaMetapushTable

class DynaMetapushTable

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 either 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 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, the involved row is determined and each value is displayed in a cell that is associated to the involved row and field. If necessary, new rows are cloned from the hidden template and attached after it, or existing rows are dropped. By default the new/updated 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

DynaMetapushTable

DynaMetapushTable(<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 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, 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

getCurrentPages

Number getCurrentPages()

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

Lifecycle: This request can be issued only while the data table is in "running" state.

Returns:
The current number of logical pages.

getDisplayedPage

Number getDisplayedPage()

Inquiry method that gets the number of the logical page currently displayed.

Lifecycle: This request can be issued only while the data table is in "running" state.

Returns:
The the number of the logical page currently displayed. If single page mode is currently used, the return value is always 1.

See:
- goToPage()

getMaxDynaRows

Number getMaxDynaRows()

Inquiry method that gets the maximum number of visible rows allowed in the screen table. 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.

Returns:
The maximum number of visible rows allowed, or the String "unlimited", to notify that the screen table is allowed to grow without limits, without the need for paging.

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()

goToPage

void goToPage(<Number> pageNumber)

Operation method that shows a particular logical page in the data table.
The request is ignored if single page mode is currently used (i.e. the maximum number of visible rows is set to unlimited).

Lifecycle: This operation can be requested only while the data table is in "running" state.

Parameters:
pageNumber - 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 data table.

See:
- setMaxDynaRows()
- getCurrentPages()

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(<DOMElement> domNode, <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. 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 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.
This notification is unrelated to paging activity. New or changed rows are notified regardless that they are being shown in the current page or that they are currently hidden. Also, no notifications are available to signal that a row is entering or exiting the currently displayed page.

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

See:
- setMaxDynaRows()

onCurrentPagesChanged

void onCurrentPagesChanged(<Number> numPages)

Event handler that receives the notification that the number of logical pages has changed. The number of logical pages can grow or shrink because of addition or removal of rows and because of changes in the logical page size setting. By setting a custom handler it is possible, for example, to implement a dynamic page index to allow direct jump to each logical page.

Default implementation: do nothing

Parameters:
numPages - The current total number of logical pages.

See:
- setMaxDynaRows()

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 ADD command, a new HTML row is added to the screen table; this may cause the page to grow significantly, if the maximum number of rows has been configured as unlimited, so that only one page is used to display all the data table. 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, ADD and UPDATE operations may happen on rows placed in the nonvisible part of the including element.
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; otherwise, the automatic scrolling activity may be excessive.
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).

Invocation: optional

Default value: "OFF"

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

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()

setMaxDynaRows

void setMaxDynaRows(<Number> maxDynaRows)

Setter method that sets the maximum number of visible rows allowed in the screen table. 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 goToPage() method.
Note that, due to the dynamical nature of the metapush data table, logical pages other than page 1 may underly to scrolling caused by operations on rows belonging to lower logical pages; this effect is emphasized if sorting is active.

Invocation: optional.

Default value: "unlimited"

Lifecycle: the maximum number of visible rows 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. Moreover, the current logical page is automatically switched to page 1.

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

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 identify 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 sorting policy of the data table. If no sorting policy is set, then 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 at any time. If the data table is currently in "running" state, this causes the immediate adjustment of the data table and the associated screen table. However, disabling the sort leaves the data table in its current state.

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.
Note that parsing the value is not needed for values set as Number objects in an extra field.