Class ScrollTable
Object
|
+--Table
|
+--VisualTable
|
+--ScrollTable
- class
ScrollTable
- 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 make the older ones scroll.
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.cellScroll(), 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, each value is displayed in a cell that is
associated to the involved field; the declared cell row numbers are
then used to perform scrolling operations on the updates that have been
already displayed. 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 (in case of a DIV
or SPAN element, the stylesheet used is the one supplied through the
"class" attribute).
More visualization actions can be performed through the event
handlers provided.
See:
Defined in lspushpage.js
Constructor Summary |
ScrollTable
(<GroupDescriptor> tGroup, <SchemaDescriptor> tSchema, <String> tSubscriptionMode)
Creates an object to be used to describe a data table whose values
should be displayed and scrolled into existing HTML cells.
|
Method Summary |
void
|
onChangingValues(<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.
|
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.
|
void
|
setLastVisibleRow(<Number> rowNumber)
Setter method that specifies the row number of the last row in the
screen table.
|
void
|
setUpwardScroll(<boolean> isUpwardScroll)
Setter method that enables or disables upward scroll.
|
Methods inherited from class Table |
getSchema, getGroup, setDataAdapter, getId, setSelector, setItemsRange, setRequestedMaxFrequency, setRequestedBufferSize, setSnapshotRequired, onItemUpdate, onLostUpdates, onEndOfSnapshot, onStart, getClassName
|
ScrollTable
ScrollTable(<GroupDescriptor> tGroup, <SchemaDescriptor> tSchema, <String> tSubscriptionMode)
Creates an object to be used to describe a data table whose values
should be displayed and scrolled 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 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.
onChangingValues
void onChangingValues(<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.
Before displaying the new 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
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 passed 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 (this can involve only the
first or the last row, depending on the setUpwardScroll()
setting)
- because of a scroll operation
- in order to clear the screen table
By setting a custom handler it is possible to perform custom display
operations for the screen table rows in a way consistent with scrolling
and clearing operations on the screen table.
Note that a row that is about to be cleared or scrolled
may have been displayed in the context of a different data table, if
false was set by VisualTable.setClearOnRemove() for that data
table.
Note that data rows that scroll after the last row or before the
first row (depending on the setUpwardScroll() setting) are
discarded and no notifications are 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 updated.
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.
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.
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.
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 (row number 1), 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 so that old updates scroll upward.
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.
However, if a screen table is reused with a scrolling policy that is,
different than the one previously used, then the screen table should
be cleared, through the VisualTable.setClearOnAdd() setting on
the incoming data table.
Parameters:
isUpwardScroll
- true/false to enable/disable upward scroll on the data table rows.
Lightstreamer HTML Client API
Documentation generated by
JSDoc on Tue May 22 11:46:54 2012