Web Client 8.0.8

StaticGrid

StaticGrid

An AbstractGrid implementation that can be used to display the values from the internal model in a statically prepared grid.
The HTML structure suitable for the visualization of the tabular model values
must be prepared up-front in the DOM of the page as a matrix of HTML cells. The cells making up the grid can be any HTML element
owning the "data-source='Lightstreamer'" special attribute. Such cells, to be properly bound to the StatiGrid instance must also define the following custom attributes:

  • "data-grid": an identification string that has to be equal to the id that is specified in the constructor of this class. This id is used to properly bind a cell to its StaticGrid instance.
  • "data-field": the name of a field in the internal model whose value will be displayed in this cell.
  • "data-fieldtype" (optional): "extra", "first-level" or "second-level" to specify the type of field. If not specified "first-level" is assumed. The "data-fieldtype" property is only exploited in the AbstractGrid#extractFieldList and AbstractGrid#extractCommandSecondLevelFieldList methods.
  • "data-row" (only if "data-item" is not specified): a progressive number representing the number of the row associated with the cell. When a new row enters the grid its position will be decided by the AbstractGrid#setAddOnTop and AbstractGrid#setSort settings. The "data-row" attribute will define to which row a cell pertains.
    Note that the maximum value available for a data-row attribute in all the cells pertaining to this StaticGrid will define the size of the view. If the number of rows in the model exceeds the number of rows defined in the HTML grid, rows that would have been displayed in the extra rows are not shown in the view but are maintained in the model.
    Note that if this instance is used to listen to events from Subscription instance(s), and the first Subscription it listens to is a DISTINCT Subscription, then the behavior is different: when the number of rows in the model exceeds the number of rows defined in the HTML grid, adding a new row will always cause the removal of the oldest row from the model, with a consequent repositioning of the remaining rows.
  • "data-item" (only if "data-row" is not specified): the name of a row in the internal model, whose value (for the chosen field) will be displayed in this cell; this attribute should only be used if this instance is used to listen to events from Subscription instance using the MERGE mode; so, this attribute should identify the name or the 1-based position of an item in the MERGE Subscription. This way it is possible to define a static positioning for each item in the MERGE Subscription. On the contrary, by using "data-row" attributes, each item will be placed based only on the AbstractGrid#setAddOnTop and AbstractGrid#setSort settings and the positioning may depend on the arrival order of the updates.
  • "data-replica" (optional): this attribute can be specified in case there are more cells associated to the same field. If used, it will permit to access the single cells during StaticGridListener#onVisualUpdate executions.


The association between the StaticGrid and the HTML cells is made during the execution of the AbstractGrid#parseHtml method. Note that only the elements specified in the AbstractGrid#setNodeTypes and that are descendants of the node specified in the StaticGrid#setRootNode are taken into account, unless a list of cells has been manually specified in the constructor or through the StaticGrid#addCell method, in which case no elements other than the given ones are taken into account.
Cells already associated to the grid can be removed from the page DOM, hence from the grid, at any time. Cells already associated can also be moved or altered so that they become no longer suitable for association or other HTML elements may be made suitable, but, in this case, all changes will affect the grid only after the next invocation of AbstractGrid#parseHtml.
Make sure that all the associated cells specify the same attribute among "data-row" and "data-item"; the behavior of the grid is left unspecified when this condition is not met.

By default, the content of the HTML element designated as cell will be updated with the value from the internal model; in case the cell is an INPUT or a TEXTAREA element, the "value" property will be updated instead. It is possible to update any attribute of the HTML element or its CSS styles by specifying the "data-update" custom attribute. To target an attribute the attribute name has to be specified; it can be a standard property (e.g. "data-update='href'"), a custom "data-" attribute (e.g. "data-update='data-foo'") or even a custom attribute not respecting the "data-" standard (e.g. "data-update='foo'"). To target CSS attributes the "data-update='style.attributeName'" form has to be used (e.g. "data-update='style.backgroundColor'"); note that the form "data-update='style.background-color'" will not be recognized by some browsers.
WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code may reach the internal model (for example through the injection of undesired JavaScript code from the Data Adapter).
More visualization actions can be performed through the provided VisualUpdate event objects received on the StaticGridListener.

Constructor

new StaticGrid(id, autoParse, rootEl, cells)

Creates an object that extends AbstractGrid displaying its values in a grid made of HTML elements. The grid rows are displayed into statically prepared HTML rows. The object can be supplied to Subscription#addListener and Subscription#removeListener in order to display data from one or more Subscriptions.

Parameters:
Name Type Description
id String

An identification string to be specified in the HTML element as the data "data-grid" property value to make it possible for this StaticGrid instance to recognize its cells. The binding between the cells and the StaticGrid is performed during the AbstractGrid#parseHtml execution.

autoParse boolean

If true the AbstractGrid#parseHtml method is executed before the constructor execution is completed. If false the parseHtml method has to be called later by custom code. It can be useful to set this flag to false if, at the time of the StaticGrid instance creation, the HTML elements designated as cells are not yet ready on the page.

rootEl Object

if specified, the cells to make up the HTML grid will only be searched in the list of descendants of this node. Equivalent to a StaticGrid#setRootNode call, but useful if autoParse is true.

cells Array.<Object>

an array of DOMElement instances that will make up the HTML grid for this StaticGrid instance. If specified and not empty, the parseHtml method will avoid searching cells in the DOM of the page. Equivalent to multiple StaticGrid#addCell calls, but also useful if autoParse is true.

Extends

Methods

addCell(cellElement)

Operation method that adds an HTML cell pointer to the StaticGrid.
Note that if at least one cell is manually specified then the AbstractGrid#parseHtml will not perform any search in the DOM of the page and will only use the given cells.

Lifecycle: Cell pointers can be added to a StaticGrid at any time. However, before an HTML element is actually used as a cell by the StaticGrid a call to AbstractGrid#parseHtml is necessary.

Parameters:
Name Type Description
cellElement Object

A DOM pointer to an HTML node. The specified HTML node should be a "legal" cell for the StaticGrid (i.e. should be defined according with the requirements for the StaticGrid as described in the overview of this class). Moreover, nodes of any types are allowed.

addListener(listener)

Adds a listener that will receive events from the StaticGrid instance.
The same listener can be added to several different StaticGrid instances.

Lifecycle: a listener can be added at any time.

Parameters:
Name Type Description
listener StaticGridListener

An object that will receive the events as shown in the StaticGridListener interface.
Note that the given instance does not have to implement all of the methods of the StaticGridListener interface. In fact it may also implement none of the interface methods and still be considered a valid listener. In the latter case it will obviously receive no events.

clean()

Removes all the rows from the model and reflects the change on the view.

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time.

Inherited From:
Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException

extractCommandSecondLevelFieldList() → {Array.<String>}

Creates an array containing all the unique values, of the "data-field" properties in all of the HTML elements, having the "data-fieldtype" property set to "second-level", associated to this grid during the AbstractGrid#parseHtml execution.
The result of this method is supposed to be used as "Field List" of a second-level Subscription.
Execution of this method is pointless if HTML elements associated to this grid specify a field position instead of a field name in their "data-field" property.

Inherited From:
See:
Returns:

The list of unique values found in the "data-field" properties of HTML element of this grid.

Type
Array.<String>

extractFieldList() → {Array.<String>}

Creates an array containing all the unique values of the "data-field" properties in all of the HTML elements associated to this grid during the AbstractGrid#parseHtml execution. The result of this method is supposed to be used as "Field List" of a Subscription.
Execution of this method is pointless if HTML elements associated to this grid specify a field position instead of a field name in their "data-field" property.
Note that elements specifying the "data-fieldtype" property set to "extra" or "second-level", will be ignored by this method. This permits to distinguish fields that are part of the main subscription (not specifying any "data-fieldtype" or specifying "first-level"), part of a second-level Subscription (specifying "second-level") and not part of a Subscription at all, but still manageable in a direct way (specifying "extra").

Inherited From:
See:
Returns:

The list of unique values found in the "data-field" properties of HTML element of this grid.

Type
Array.<String>

extractItemList() → {Array.<String>}

Creates an array containing all of the unique values of the "data-item" properties in all of the HTML elements associated to this grid during the AbstractGrid#parseHtml execution. The result of this method is supposed to be used as "Item List" of a Subscription.


Execution of this method is pointless if HTML elements associated to this grid through "data-item" specify an item position instead of an item name.

Returns:

The list of unique values found in the "data-item" properties of HTML element of this grid.

Type
Array.<String>

forceSubscriptionInterpretation(interpretation)

Operation method that is used to force the choice of what to use as key for the integration in the internal model, when receiving an update from a Subscription this grid is listening to.
Specifying "ITEM_IS_KEY" tells the widget to use the item as key; this is the behavior that is already the default one when the Subscription is in "MERGE" or "RAW" mode (see AbstractWidget for details).
Specifying "UPDATE_IS_KEY" tells the widget to use a progressive number as key; this is the behavior that is already the default one when the Subscription is in "DISTINCT" mode (see AbstractWidget for details).
Note that when listening to different Subscriptions the default behavior is set when the grid is added as listener for the first one and then applied to all the others regardless of their mode.

Lifecycle:this method can only be called while the internal model is empty.

Parameters:
Name Type Description
interpretation String

either "ITEM_IS_KEY" or "UPDATE_IS_KEY", or null to restore the default behavior.

Inherited From:
Throws:

getListeners() → {Array.<StaticGridListener>}

Returns an array containing the StaticGridListener instances that were added to this client.

Returns:

an array containing the listeners that were added to this instance. Listeners added multiple times are included multiple times in the array.

Type
Array.<StaticGridListener>

getNodeTypes() → {Array.<String>}

Inquiry method that gets the list of node of types that would be searched in case of a call to AbstractGrid#parseHtml.

Inherited From:
See:
Returns:

a list of node type names.

Type
Array.<String>

getSortField() → {Number}

Inquiry method that gets the name of the field currently used as sort field, if available.

Inherited From:
See:
Returns:

The name of a field, or null if sorting is not currently enabled.

Type
Number

getValue(key, field) → {String}

Returns the value from the model for the specified key/field pair. If the row for the specified key does not exist or if the specified field is not available in the row then null is returned.

Lifecycle: This method can be called at any time.

Parameters:
Name Type Description
key String

The key associated with the row to be read.

field String

The field to be read from the row.

Inherited From:
Returns:

The current value for the specified field of the specified row, possibly null. If the value for the specified field has never been assigned in the model, the method also returns null.

Type
String

isAddOnTop() → {boolean}

Inquiry method that gets true/false depending on how new rows entering the grid are treated. If true is returned, new rows will be placed on top of the grid. Viceversa, if false is returned, new rows are placed at the bottom.

Inherited From:
See:
Returns:

true if new rows are added on top, false otherwise.

Type
boolean

isCommaAsDecimalSeparator() → {boolean}

Inquiry method that gets the type of interpretation to be used to parse the sort field values in order to perform numeric sort.

Inherited From:
See:
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.

Type
boolean

isDescendingSort() → {boolean}

Inquiry method that gets the sort direction currently configured.

Inherited From:
See:
Returns:

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

Type
boolean

isHtmlInterpretationEnabled() → {boolean}

Inquiry method that gets the type of interpretation to be applied for the pushed values for this grid. In fact, the values can be put in the target cells as HTML code or as text.

Inherited From:
See:
Returns:

true if pushed values are interpreted as HTML code, false otherwise.

Type
boolean

isNumericSort() → {boolean}

Inquiry method that gets the type of sort currently configured.

Inherited From:
See:
Returns:

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

Type
boolean

onClearSnapshot(itemName, itemPos)

Event handler that is called by Lightstreamer each time a request to clear the snapshot pertaining to an item in the Subscription has been received from the Server. More precisely, this kind of request can occur in two cases:

  • For an item delivered in COMMAND mode, to notify that the state of the item becomes empty; this is equivalent to receiving an update carrying a DELETE command once for each key that is currently active.
  • For an item delivered in DISTINCT mode, to notify that all the previous updates received for the item should be considered as obsolete; hence, if the listener were showing a list of recent updates for the item, it should clear the list in order to keep a coherent view.

Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). This kind of notification is not possible for second-level items (which are in MERGE mode).
This event can be sent by the Lightstreamer Server since version 6.0
Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.

itemPos Number

1-based position of the item within the "Item List" or "Item Group".

Inherited From:

onCommandSecondLevelItemLostUpdates(lostUpdates, key)

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item that was subscribed to as a second-level subscription. Such notifications are sent only if the Subscription was configured in unfiltered mode (second-level items are always in "MERGE" mode and inherit the frequency configuration from the first-level Subscription).
By implementing this method it is possible to perform recovery actions.

Parameters:
Name Type Description
lostUpdates Number

The number of consecutive updates dropped for the item.

key String

The value of the key that identifies the second-level item.

Inherited From:
See:

onCommandSecondLevelSubscriptionError(code, message, key)

Event handler that is called when the Server notifies an error on a second-level subscription.
By implementing this method it is possible to perform recovery actions.

Parameters:
Name Type Description
code Number

The error code sent by the Server. It can be one of the following:

  • 14 - the key value is not a valid name for the Item to be subscribed; only in this case, the error is detected directly by the library before issuing the actual request to the Server
  • 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
  • 21 - bad Group name
  • 22 - bad Group name for this Schema
  • 23 - bad Schema name
  • 24 - mode not allowed for an Item
  • 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item
  • 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item
  • 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only)
  • 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
  • 68 - the Server could not fulfill the request because of an internal error.
  • <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation

message String

The description of the error sent by the Server; it can be null.

key String

The value of the key that identifies the second-level item.

Inherited From:
See:

onEndOfSnapshot(itemName, itemPos)

Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the Subscription have been received, so that real time events are now going to be received. The received snapshot could be empty. Such notifications are sent only if the items are delivered in DISTINCT or COMMAND subscription mode and snapshot information was indeed requested for the items. By implementing this method it is possible to perform actions which require that all the initial values have been received.
Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). Snapshot-related updates for the second-level items (which are in MERGE mode) can be received both before and after this notification.

Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.

itemPos Number

1-based position of the item within the "Item List" or "Item Group".

Inherited From:
See:

onItemLostUpdates(itemName, itemPos, lostUpdates)

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription. Such notifications are sent only if the items are delivered in an unfiltered mode; this occurs if the subscription mode is:

  • RAW
  • MERGE or DISTINCT, with unfiltered dispatching specified
  • COMMAND, with unfiltered dispatching specified
  • COMMAND, without unfiltered dispatching specified (in this case, notifications apply to ADD and DELETE events only)
By implementing this method it is possible to perform recovery actions.
Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.

itemPos Number

1-based position of the item within the "Item List" or "Item Group".

lostUpdates Number

The number of consecutive updates dropped for the item.

Inherited From:
See:

onItemUpdate(updateInfo)

Event handler that is called by Lightstreamer each time an update pertaining to an item in the Subscription has been received from the Server.

Parameters:
Name Type Description
updateInfo ItemUpdate

a value object containing the updated values for all the fields, together with meta-information about the update itself and some helper methods that can be used to iterate through all or new values.

Inherited From:

onListenEnd(subscription)

Event handler that receives a notification when the SubscriptionListener instance is removed from a Subscription through Subscription#removeListener. This is the last event to be fired on the listener.

Parameters:
Name Type Description
subscription Subscription

the Subscription this instance was removed from.

Inherited From:

onListenStart(subscription)

Event handler that receives a notification when the SubscriptionListener instance is added to a Subscription through Subscription#addListener. This is the first event to be fired on the listener.

Parameters:
Name Type Description
subscription Subscription

the Subscription this instance was added to.

Inherited From:

onRealMaxFrequency(frequency)

Event handler that is called by Lightstreamer to notify the client with the real maximum update frequency of the Subscription. It is called immediately after the Subscription is established and in response to a requested change (see Subscription#setRequestedMaxFrequency). Since the frequency limit is applied on an item basis and a Subscription can involve multiple items, this is actually the maximum frequency among all items. For Subscriptions with two-level behavior (see Subscription#setCommandSecondLevelFields and Subscription#setCommandSecondLevelFieldSchema) , the reported frequency limit applies to both first-level and second-level items.
The value may differ from the requested one because of restrictions operated on the server side, but also because of number rounding.
Note that a maximum update frequency (that is, a non-unlimited one) may be applied by the Server even when the subscription mode is RAW or the Subscription was done with unfiltered dispatching.

Parameters:
Name Type Description
frequency String

A decimal number, representing the maximum frequency applied by the Server (expressed in updates per second), or the string "unlimited". A null value is possible in rare cases, when the frequency can no longer be determined.

Inherited From:

onSubscription()

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully subscribed to through the Server. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.
This notification is always issued before the other ones related to the same subscription. It invalidates all data that has been received previously.
Note that two consecutive calls to this method are not possible, as before a second onSubscription event is fired an onUnsubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level subscriptions are not notified.

Inherited From:

onSubscriptionError(code, message)

Event handler that is called when the Server notifies an error on a Subscription. By implementing this method it is possible to perform recovery actions.
Note that, in order to perform a new subscription attempt, LightstreamerClient#unsubscribe and LightstreamerClient#subscribe should be issued again, even if no change to the Subscription attributes has been applied.

Parameters:
Name Type Description
code Number

The error code sent by the Server. It can be one of the following:

  • 15 - "key" field not specified in the schema for a COMMAND mode subscription
  • 16 - "command" field not specified in the schema for a COMMAND mode subscription
  • 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
  • 21 - bad Group name
  • 22 - bad Group name for this Schema
  • 23 - bad Schema name
  • 24 - mode not allowed for an Item
  • 25 - bad Selector name
  • 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item
  • 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item
  • 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only)
  • 29 - RAW mode is not allowed by the current license terms (for special licenses only)
  • 30 - subscriptions are not allowed by the current license terms (for special licenses only)
  • 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
  • 68 - the Server could not fulfill the request because of an internal error.
  • <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation

message String

The description of the error sent by the Server; it can be null.

Inherited From:
See:

onUnsubscription()

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully unsubscribed from. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.


After this notification no more events can be recieved until a new SubscriptionListener#onSubscription event.
Note that two consecutive calls to this method are not possible, as before a second onUnsubscription event is fired an onSubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level unsubscriptions are not notified.

Inherited From:

parseHtml()

Operation method that is used to authorize and execute the binding of the widget with the HTML of the page.

Lifecycle: This method can only be called once the HTML structure the instance is expecting to find are ready in the DOM. That said, it can be invoked at any time and subsequent invocations will update the binding to the current state of the page DOM. Anyway, newly found cells will be left empty until the next update involving them.

Overrides:
See:

removeListener(listener)

Removes a listener from the StaticGrid instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Parameters:
Name Type Description
listener StaticGridListener

The listener to be removed.

removeRow(key)

Removes a row from the internal model and reflects the change on the view. If no row associated with the given key is found nothing is done.

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time.

Parameters:
Name Type Description
key String

The key associated with the row to be removed.

Inherited From:
Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException

setAddOnTop(isAddOnTop)

Setter method that decides whenever new rows entering the model will be placed at the top of the grid or at the bottom.
Note that if the sort is enabled on the Grid through AbstractGrid#setSort then this setting is ignored as new rows will be placed on their right position based on the sort configuration.
Also note that the sort/add policy may be ignored depending on the grid configuration; see the use of the "data-item" cell attribute in StaticGrid.

Default value: false.

Lifecycle: this setting can be changed at any time.
Note anyway that changing this setting while the internal model is not empty may result in a incosistent view.

Parameters:
Name Type Description
isAddOnTop boolean

true/false to place new rows entering the model as the first/last row of the grid.

Inherited From:
Throws:

if the given value is not a valid boolean value.

Type
IllegalArgumentException

setAutoCleanBehavior(onFirstSubscribe, onLastUnsubscribe)

Utility method that can be used to control part of the behavior of the widget in case it is used as a listener for one or more Subscription instances.
Specifying the two flags it is possible to decide to clean the model and view based on the status (subscribed or not) of the Subscriptions this instance is listening to.

Lifecycle: This method can be called at any time.

Parameters:
Name Type Description
onFirstSubscribe boolean

If true a AbstractWidget#clean call will be automatically performed if in the list of Subscriptions this instance is listening to there is no Subscription in the subscribed status and an onSubscription is fired by one of such Subscriptions.
As a special case, if in the list of Subscriptions this instance is listening to there is no Subscription in the subscribed status and this instance starts listening to a new Subscription that is already in the subscribed status, then it will be considered as if an onSubscription event was fired and thus a clean() call will be performed.

onLastUnsubscribe boolean

If true a AbstractWidget#clean call will be automatically performed if in the list of Subscriptions this instance is listening to there is only one Subscription in the subscribed status and the onUnsubscription for such Subscription is fired.
As a special case, if in the list of Subscriptions this instance is listening to there is only one Subscription in the subscribed status and this instance stops listening to such Subscription then it will be considered as if the onUnsubscription event for that Subscription was fired and thus a clean() call will be performed.

Inherited From:
See:

setHtmlInterpretationEnabled(enable)

Setter method that enables or disables the interpretation of the values in the model as HTML code. For instance, if the value "<a href='news03.htm'>Click here</a>" is placed in the internal model (either by manual call of the AbstractWidget#updateRow method or by listening on a SubscriptionListener#onItemUpdate event)
and HTML interpretation is enabled, then the target cell will contain a link; otherwise it will contain that bare text. Note that the setting applies to all the cells in the associated grid. Anyway if it's not the content of a cell that is going to be updated, but one of its properties, then this setting is irrelevant for such cell.
WARNING: When turning HTML interpretation on, make sure that no malicious code may reach the internal model (for example through the injection of undesired JavaScript code from the Data Adapter).

Default value: false.

Lifecycle: this setting can be changed at any time.
Note that values that have already been placed in the grid cells will not be updated to reflect the new setting.

Parameters:
Name Type Description
enable boolean

true/false to enable/disable HTML interpretation for the pushed values.

Inherited From:
Throws:

setNodeTypes(nodeTypes)

Setter method that specifies a list of HTML element types to be searched for during the mapping of the grid to the HTML made by AbstractGrid#parseHtml.

Default value: an array containing DIV SPAN and INPUT.

Lifecycle: Node types can be specified at any time. However, if the list is changed after the execution of the AbstractGrid#parseHtml method then it will not be used until a new call to such method is performed.

Parameters:
Name Type Description
nodeTypes Array.<String>

an array of Strings representing the names of the node types to be searched for. If the array contains an asterisk (*) then all the node types will be checked.

Inherited From:
See:

setRootNode(rootNode)

Setter method that specifies the root node to be used when searching for grid cells. If specified, only descendants of the supplied node will be checked.
Anyway note that if nodes are explicitly set through the constructor or through the StaticGrid#addCell method, then the search will not be performed at all.

Default value: the entire document.

Lifecycle: a root node can be specified at any time. However, before a new search is performed for the StaticGrid a call to AbstractGrid#parseHtml is necessary.

Parameters:
Name Type Description
rootNode Object

a DOM node to be used as starting point when searching for grid cells.

setSort(sortField, descendingSortopt, numericSortopt, commaAsDecimalSeparatoropt)

Setter method that configures the sort policy of the grid. If no sorting policy is set, new rows are always added according with the AbstractGrid#setAddOnTop setting. If, on the other hand, sorting is enabled, then new rows are positioned according to the sort criteria. Sorting is also maintained upon update of an existing row; this may cause the row to be repositioned.
If asynchronous row repositioning is undesired, it is possible to set the sort and immediately disable it with two consecutive calls to just enforce grid sorting based on the current contents.
The sort can also be performed on fields that are part of the model but not part of the grid view.
Note that the sort/add policy may be ignored depending on the grid configuration; see the use of the "data-item" cell attribute in StaticGrid.

Default value: no sort is performed.

Lifecycle: The sort configuration can be set and changed at any time.

Parameters:
Name Type Attributes Default Description
sortField String

The name of the field to be used as sort field, or null to disable sorting.

descendingSort boolean <optional>
false

true or false to perform descending or ascending sort. This parameter is optional; if missing or null, then ascending sort is performed.

numericSort boolean <optional>
false

true or false to perform numeric or alphabetical sort. This parameter is optional; if missing or null, then alphabetical sort is performed.

commaAsDecimalSeparator boolean <optional>
false

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.

Inherited From:
Throws:

if one of the boolean parameters is neither missing, null, nor a valid boolean value.

Type
IllegalArgumentException

updateRow(key, newValues)

Updates a row in the internal model and reflects the change on the view. If no row associated with the given key is found then a new row is created.
Example usage:
myWidget.updateRow("key1", {field1:"val1",field2:"val2"});

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time. If called while an updateRow on the same internal model is still executing (e.g. if called while handling an onVisualUpdate callback), then the new update:

  • if pertaining to a different key and/or if called on a Chart instance, will be postponed until the first updateRow execution terminates;
  • if pertaining to the same key and if called on a StaticGrid / DynaGrid instance, will be merged with the current one.

Parameters:
Name Type Description
key String

The key associated with the row to be updated/added.

newValues Object

A JavaScript object containing name/value pairs to fill the row in the mode.
Note that the internal model does not have a fixed number of fields; each update can add new fields to the model by simply specifying them. Also, an update having fewer fields than the current model will have its missing fields considered as unchanged.

Inherited From:
Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException