Configuration Attributes

All of the attributes that can be used to modify the behaviour of the SL4B library are defined here. They have been broken down into sections according to the area of the library to which they apply, whilst an index of all the attributes have also been included.


Contents


Common Attributes

These are the attributes that are most commonly used to configure SL4B.

Attribute Default Description
commondomain   Specifies the common domain shared by the SL4B-enabled page, the Liberator and (if in use) the keymasterurl and keymasterxhrurl property. Supposing the following URLs were being used:
  • http://www.example.com/ (the SL4B enabled page)
  • http://liberator.example.com/ (the Liberator)
  • http://keymaster.example.com/ (the KeyMaster)
Then, the commondomain would need to be set to 'example.com'. Please see JavaScript Security (document.domain Issues) for more information on when this attribute should be used.
configurationfile   Specifies the URL of the JavaScript configuration file.
debug SL4B_DebugLevel.CRITICAL The debug level that has been configured for the SL4B library. The levels, in order of importance, are:
  • SL4B_DebugLevel.CRITICAL (critical)
  • SL4B_DebugLevel.ERROR (error)
  • SL4B_DebugLevel.NOTIFY (notify)
  • SL4B_DebugLevel.WARN (warn)
  • SL4B_DebugLevel.INFO (info)
  • SL4B_DebugLevel.DEBUG (debug)
  • SL4B_DebugLevel.RTTP_FINE (rttp-fine)
  • SL4B_DebugLevel.RTTP_FINER (rttp-finer)
  • SL4B_DebugLevel.RTTP_FINEST (rttp-finest)
Use the text in brackets to set the debug level on the SL4B script tag, e.g.
<script type="text/javascript" id="sl4b" debug="info" ></script>

Alternatively the debug level can be set at runtime within the query string of the SL4B-enabled page (e.g. http://www.example.com/sl4b.html?debug=rttp-finer).
enableautoloading true Determines if the user wishes to invoke the SL4B load function automatically.
The SL4B load function sets up the SL4B environment on application start-up.
If a user wishes to invoke the SLB load function manually using SL4B_WindowEventHandler.onLoad(evt), then enableautoloading must be set to false.
password demopass The password to be used to login to the Liberator.
See the credentialsprovider attribute for more information.
rttpprovider javascript The name of the RTTP Provider that will be used to provide access to the Liberator.
The possible values are:
  • javascript
  • test
Any other values will be handled as a URL that will be loaded to create a custom RTTP provider.
Note: The applet provider was removed in version 4.5.
serverurl   The root URL of the Liberator (e.g. http://liberator.example.com:8080).
suppressexceptions true Determines whether exceptions thrown whilst the SL4B library is invoking a user callback method should be caught by the library or not. By default all exceptions are caught by the SL4B library and a suitable error is logged, which is usually the best behaviour within a production environment where the end users do not want to see script errors whilst they are using the page. However, in a development environment this behaviour can make it considerably harder to track down the cause of the exception. In this instance, the suppressexceptions attribute can be set to false to help diagnose the underlying issue.

Alternatively this attribute can be set at runtime within the query string of the SL4B-enabled page (e.g. http://www.example.com/sl4b.html?suppressexceptions=false).
user demouser The username to be used to login to the Liberator.
See the credentialsprovider attribute for more information.

Back to contents


JavaScript RTTP Provider Attributes

These attributes configure the behaviour of the JavaScript RTTP provider. They will be ignored if a different provider is used.

Attribute Default Description
connectiontimeout 15000 The length of time, in millisecond, the JavaScript RTTP provider will wait for a particular connection to be established, before it fails over to the next connection type.
Note: The default prior to SL4B version 4.3 was 5000.
jscontainerpath sl4b/javascript-rttp-provider The path to the JavaScript container directory on the Liberator.
jscontainerurl (deprecated) [serverurl]/[jscontainerpath] The URL of the JavaScript container directory on the Liberator.
maxgetlength   The maximum length of a message for it to be sent to the Liberator via an HTTP GET. If a message is longer than this value then it will be sent via an HTTP POST. This value should be set to zero if HTTP POST should always be used to send messages to the Liberator. The value set here is the maximum value that will be used, the actual value may be reduced according to the capabilities of the connected Liberator.

If this attribute is not specified the client will use the maximum length supported by the Liberator.
type3pollperiod 1000 The length of time between polls for the next batch of updates from the Liberator for a type 3 (refresh) connection.
type5reconnectcount 10000 The number of messages that will be processed before the library triggers an automatic reconnection to the Liberator. This only applies for type 5 connection, and is necessary to prevent memory leaks in IE.
type5padlength 4096 The number of bytes to pad the streaming JavaScript file to ensure streaming starts correctly. This only applies for type 5 connection, and is required in IE.
noopinterval 5000 The length of time, in milliseconds, between heartbeat (NOOP) messages sent to the Liberator to test connectivity.
nooptimeout 5000 The length of time, in milliseconds, to wait for a response to a heartbeat (NOOP) message before assuming we've lost the connection to the Liberator.
logintimeout 10000 The length of time, in milliseconds, to wait for a response to the login message before assuming we've lost the connection to the Liberator.

Back to contents


Master/Slave Frame Attributes

These attributes apply to the master/slave frame functionality (see Using Multiple Frames in SL4B API documentation for more details).

Attribute Default Description
containerframelocation top The location of the common container frame (relative to this frame) which is the root parent from which all the master and slave frames are children.
frameid   The string that will be used to uniquely identify a slave frame. For backward compatibility the value of the thisframe attribute will be used if this attribute is omitted.
thisframe (deprecated)   The location of the web page within the DOM. The frameid attribute should be used instead.
usemasterframe   Unary attribute that indicates that the frame is a slave. For backwards compatibility with RTML and RTSL, is a value is specified, it is used as the location of the master frame within the DOM.

Back to contents


Latency Attributes

These are the attributes that are used for calculating message latency.

Attribute Default Description
enablelatency false Enables calculation of actual update event latency.
clocksyncbatchsize 5 The number of clock sync messages to send in a batch, the actual clocksync offset is calculated from the message with the shortest round trip time.
clocksyncperiod 60000 The spacing in milliseconds between clock sync batches
clocksyncspacing 1000 The spacing in milliseconds between each batch of clocksync messages. To determin the clock sync a series of messages (a batch) are sent to the server, for each message the round trip time is calculated, the message with the best round trip time is then used to calculate the clock offset between the two machines. The clock offset is used to adjust timestamps sent from the server to calculate latency until the next clock sync is calculated. Using the default values a batch of 5 (clocksyncbatchsize) clocksync messages are sent with 1000ms (clocksyncspacing) between each, the the calculated clock offset is then used for calculating the latency for all messages for the next 60000ms (clocksyncperiod).
timestampfield INITIAL_TIMESTAMP The name of the field used to retrieve the servers timestamp at the time the message was sent, used in conjuction with the clocksync offset to calculate the actual message latency.

Back to contents


Other Attributes

These are the remaining attributes that do not fit specifically into any other category.

Attribute Default Description
applicationid SL4B The page specific application id that will be sent to the Liberator when the page attempts to login. If this attribute is defined, the value that is sent to the Liberator will always be prefixed with SL4B:.
connectiontypes
(Deprecated in version 4.5)
  A comma separated list of the types of connection that SL4B will attempt to use to connect to a Liberator. The possible connection types are listed below:
  • 3 = a polling connection
  • 5 = a streaming javascript connection

As of version 4.5 this attribute has been deprecated, users should now use the SL4B_Configuration setPollingConnectionMethods() and setStreamingConnectionMethods() to override the default connection methods.

Please see Connection Methods for more information.

disablepolling false Disables Polling connection methods, use to disable the default polling connection that is used as a fallback if the streaming connection fails.
disablestreaming false Disables Streaming connection methods, use to disable the default streaming connection that is used.
credentialsprovider standard The name of the user credentials provider that is used to get the username and password that SL4B will use to login to the Liberator.
The possible values are: Any other value is taken to be a URL that is loaded to create a custom credentials provider.
debugwindowtype html The type of window that will be opened to display the SL4B debug log. There are two options:
  • html - opens an HTML page hosted from the server that SL4B was loaded from to display the debug log. This avoid any secure/non-secure warnings when using debugging within a page loaded over https.
  • about:blank - opens a window containing about:blank and writes the debug log messages into it.
enableflash false true if the flash extension library should be loaded (see Using The Flash Library for more details).
includertml false Whether the RTML library scripts should be loaded or not.
includertsl false Whether the RTSL library scripts should be loaded or not.
keymasterconnectiontimeout 10000 The timeout (in milliseconds) on KeyMaster's response to a keep-alive or request for credentials. If retrieving the credentials from the KeyMaster takes longer than this, SL4B will timeout
keymasterkeepaliveinterval 30000 The interval (in milliseconds) between KeyMaster keep-alive polls, used to keep the session with the application server open. If a set to 0 or a negative value, the KeyMaster keep-alive functionality will be disabled.
keymasterurl  

The location of a KeyMaster servlet to use for authentication. This attribute should be set when you are using Caplin KeyMaster to provide a user credentials token that will be used to log the user in to Liberator. The attribute's value should represent the URL of a Caplin KeyMaster servlet, and the protocol (http or https) must be the same as that used for the main SL4B enabled page.

If you are using the default setup of KeyMaster, set keymasterurl to the URL [https | http]://>address-of-application-server</keymaster/servlet/StandardKeyMaster

You are recommended to also set the keymasterxhrurl attribute which provides SL4B with more detailed error messages when there is a problem accessing KeyMaster.

Also see the credentialsprovider attribute.
keymasterxhrurl  

The location of a page providing XHRKeyMaster servlet to use for authentication. This attribute should be set when you are using caplin KeyMaster to provide a user credentials token that will be used to log the user in to Liberator. XHRKeymaster provides more detailed error messages when there is a problem accessing KeyMaster than is the case when just keymasterurl is set. If keymasterxhrurl is set, SL4B will use the specified XHRKeymaster servlet in preference to connecting to KeyMaster through the URL specified in keymasterurl.

SL4B is unable to use this method for connecting to KeyMaster with certain browser/connection type combinations. When it detects that it cannot use the keymasterxhrurl method, it will automatically switch to using keymasterurl and the other method. This means that you should always set both.

If you are using the default set up of KeyMaster, set keymasterxhrurlto the URL [https | https]://>address-of-application-server</keymaster/servlet/XHRKeymaster
Also see the credentialsprovider attribute.
keymasterattempts   If a potentially temporary error occurs while SL4B is attempting to get the credentials from the KeyMaster, SL4B will try to get the credentials up to a total of keymasterattempts times. Potentially temporary errors include a timeout, or a 404 or 500 series response code from the KeyMaster.
maxupdatebatchsize 5000 The maximum number of update callbacks that will be processed within a single batch. This can be used to configure how much "breathing space" the browser has when high update rates are being received.
nobrowserstatus false Determines if the user wishes to suppress RTTP messages being displayed in the status bar relating to the RTTP session. If the attribute is present in the SL4B script tag then these messages will be suppressed and not appear.
true if the user wants to suppress all messages related to the RTTP session.
service   The URL of the XML file containing the failover algorithm and servers information. If this attribute is defined, the commondomain attribute must also be specified.
updatebatchfreq 250 (or 0 if a JavaScript RTTP Provider is configured) The number of milliseconds between each batch of callbacks (typically object updates) being sent. This value can be decreased to reduce the latency of the updates, however this may decrease the performance of the browser, depending on how high the update rate is and how powerful the client PC is.

If a JavaScript RTTP Provider is used, the value of this attribute is 0 and cannot be changed.

Back to contents


Attribute Index

Back to contents