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:
Defined in lspushpage.js
Constructor Summary |
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.
|
Method Summary |
Number
|
getMaxDynaRows()
Inquiry method that gets the maximum number of rows allowed in the
data table.
|
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.
|
void
|
setAutoScroll(<String> type, <String> elementId)
Setter method that enables or disables the automatic adjustment of
the screen table scrollbars at each new update.
|
void
|
setMaxDynaRows(<Number> maxDynaRows)
Setter method that sets the maximum number of rows allowed in the
data 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
|
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.
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.
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.
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.
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.
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.
Lightstreamer HTML Client API
Documentation generated by
JSDoc on Tue May 22 11:46:54 2012