This document is the API Specification for HTML Client 5.0.1.

Summary

This javascript library allows any web front-end to request and display pushed data from Lightstreamer Server. In order to achieve this:

• Include lscommons.js and lspushpage.js in each page where pushed data have to be displayed, to make it a "Push-Page". Then create and configure a "PushPage" object in each such Push-Page and add a "Table" object for each data table to be requested.
• Add an Engine page to the front-end. You can accomplish this by calling the "createEngine" method on the PushPage object in some Push-Page. The Engine page is created as a hidden IFRAME. It includes lscommons.js and lsengine.js and creates a "LightstreamerEngine" object.
  If your front-end includes more than one Push-Page, then elect a single Push-Page where "createEngine" has to be called; then link to the created Engine page from any other Push-Page, by calling the "seekEngine" method on each local PushPage object. A Push-Page which hosts the Engine page is referred to as a "Master Push-Page".
• Configure the Engine page. In your Master Push-Page, define an onEngineCreation event handler for the PushPage object. At page startup, the handler will be called and will receive a reference to the LightstreamerEngine object, ready to be configured.

• It is important that only one Engine page is used throughout the front-end, because some browsers use a limited number of HTTP connections. For this reason, only one Master Push-Page should be used. For the same reason, only a limited number of different Lightstreamer-enabled applications supplied by the same host (or different instances of the same application) can be concurrently opened in a single browser instance. Lightstreamer includes checks to help detecting and handling this events.
• If a page is a Master Push-Page or contains a Master Push-Page, then it cannot be used as a link target or referred to in a "window.open" command, because, even in case the link is meant to preserve the page (i.e. to access it without replacing it, as in "myPage.html#position") this would cause some browsers (e.g. Internet Explorer prior to version 7) to stop the Push-frame connection.
• Moreover, if an HTML "A" element is used in such a page to run javascript code, then the href="javascript:myStuff()" syntax should not be used, as it may cause the streaming connection to be stopped on some browsers (e.g. Internet Explorer prior to version 8). The href="#" onClick="myStuff(); return false;" syntax should be used, instead.
  Note the final "return false;" statement, which prevents the execution of the default event handler. If missing, the browser may change the displayed address by adding "/#"; some browsers (e.g. Firefox) may even add a spurious entry in the history list.
• A "document.domain" property setting is needed on the front-end pages in order to allow cross-frame scripting between the front-end pages (supplied by the site web server) and the Push-Frame (supplied by Lightstreamer Server). For each Push-Page, the value of the domain property should be supplied as part of the PushPage object configuration. The domain configuration for the Engine page is performed by the Master Push-Page.
  Note that, as a consequence, you may need to set the document.domain explicitly in other front-end pages.