HTML Client Development
Total Page:16
File Type:pdf, Size:1020Kb
HTML Client Development Target API: Lightstreamer HTML Client v. 5.0 Last updated: 13/06/2011 Table of contents 1 INTRODUCTION..............................................................................................................3 2 HTML CLIENT DEVELOPMENT.............................................................................................4 2.1 Deployment Architecture..................................................................................4 2.2 Site Architecture..............................................................................................5 2.2.1 A traditional site containing one Push-Page only.................................................6 2.2.2 A traditional site with multiple Push-Pages navigated serially..............................6 2.2.3 A traditional site with multiple Push-Pages navigated in parallel..........................6 2.2.4 A full-blown AJAX site.......................................................................................9 2.2.5 HTML5 offline applications................................................................................9 2.3 The Push-Pages.............................................................................................10 2.4 The Screen Tables..........................................................................................14 2.4.1 OverwriteTable...............................................................................................14 2.4.2 ScrollTable.....................................................................................................15 2.4.3 DynaScrollTable.............................................................................................16 2.4.4 MetapushTable...............................................................................................17 2.4.5 DynaMetapushTable.......................................................................................18 2.4.6 MultiDynaMetapushTable................................................................................20 2.5 Error Handlers................................................................................................21 - 2 - 1 Introduction This document provides a conceptual introduction to the development of Lightstreamer Web Clients based on HTML and JavaScript. A full JavaScript API reference is available both online or within the software distribution: – Online JSDoc: http://www.lightstreamer.com/docs/client_web_jsdoc/index.html – Bundled JSDoc: “Lightstreamer/DOCS-SDKs/sdk_client_html/doc/API-reference-index.html” - 3 - 2 HTML Client Development The Lightstreamer HTML Client (also known as the Lightstreamer Web Client) is a set of JavaScript libraries and HTML files that can be included into any Web site in order to make it “Lightstreamer-enabled”, that is, ready to receive real-time updates pushed from Lightstreamer Server. The resources to be deployed on the web server are available under the “Lightstreamer/DOCS- SDKs/sdk_client_html/lib” directory of Lightstreamer distribution and comprise the following files: version.number (the version of Lightstreamer Web Client) build.number (the build number of Lightstreamer Web Client) compatibility_version.number (the required minimum version of Lightstreamer Server) lsblank.html lscommons.js lsengine.html lsengine.js lsform.html lspushpage.js These files must not be modified. They should be copied to a directory of your web server (for example the “/LS” directory in the root of your web site). 2.1 Deployment Architecture For demo purpose, Lightstreamer Server contains an internal web server that is able to serve static web resources. This makes it simple to distribute out-of-the-box demos (such as the StockList Demo) and to get started with Lightstreamer development. But for actual projects and production scenarios, it is highly recommended that an external web server is used (because Lightstreamer is optimized for pushing real-time data, not for serving static pages). Typically, a Lightstreamer Server and any common web server (e.g. Apache, Tomcat, IIS or any other web server of your choice) are deployed in the DMZ network. Lightstreamer Server gets the data and metadata from the back-end servers that are protected by the second firewall. The web browser gets the static web pages, as usual, from your web server, then it connects to Lightstreamer Server to receive the flow of real-time updates. Of course, both of the servers can be clustered for fail-over and load balancing. - 4 - In order for the system to work properly in this scenario (Lightstreamer Server + external web server), it is fundamental that both the servers share the same domain name in the DNS. For example: www.mycompany.com: the web server name push.mycompany.com: the Lightstreamer Server name TIP: If you are developing on a stand-alone PC (so you probably have Lightstreamer Server and the web server on the same machine on different ports), in an environment without a domain, you can simulate the final environment by editing the host file of your PC. For example, in a Windows environment, you will edit the “C:\WINDOWS\system32\drivers\etc\hosts” file and add something like: 127.0.0.1 www.mycompany.com 127.0.0.1 push.mycompany.com NOTE: In any case, when launching your web application inside a browser, you will always need to specify the full URL, e.g.: http://www.mycompany.com/myapplication and not a shortcut such as: http://localhost/myapplication or http://127.0.0.1/myapplication or http://mypcname/my-application. DEPLOYING A WEB APP ON AN EXTERNAL WEB SERVER After installing and running Lightstreamer Server from the distribution package, you will be able to see several demos, which are pre-installed in the internal web server. In order to deploy any demo on an external web server and get acquainted with the actions needed to embrace this deployment scenario for your own applications, please see the follow the “Lightstreamer/pages/demos/HOW_TO_DEPLOY_ON_YOUR_WEB_SERVER.TXT” document. 2.2 Site Architecture Each page of the site that is destined to receive real-time updates from Lightstreamer is defined as a Push-Page. The site can contain as many Push-Pages as needed, which can be displayed both concurrently and in sequence. All of the Push-Pages will be part of the same Lightstreamer session and will share a common LightstreamerEngine object. A LightstreamerEngine object is a JavaScript object that encapsulates the logic used to communicate with Lightstreamer Server and to dispatch the events to the Push-Pages. LightstreamerEngine handles the physical connections to the Server, including the permanent stream connection. The LightstreamerEngine object must live inside a Push-Page (under the hood, a LightstreamerEngine object creates a hidden iframe inside the Push-Page and loads a page inside it; in the JSDoc this is referred to as the “Engine page”). The Push-Page that hosts the LightstreamerEngine object is called the Master Push-Page. NOTE: The protocol used to connect to Lightstreamer Server is always the same used to download the Master Push-Page. So if the Master Push-Page is downloaded through HTTP, then HTTP will be used for all the connections to Lightstreamer Server. If the Master Push-Page is downloaded through HTTPS, all the connections to Lightstreamer Server will use HTTPS. There exist different ways to integrate the Master Push-Page in the site, depending on the site architecture and on the navigation style. The following sections discuss some alternative strategies (by “traditional site” we mean any site that does not take advantage of the AJAX paradigm). Please consider those are just examples of possible integration architectures and other strategies are possible. - 5 - 2.2.1 A traditional site containing one Push-Page only In this scenario there is only one page in the site that needs to display real-time data. That means there is only one Push-Page and it is a Master Push-Page Each time the user navigates to the Master Push-Page, a Lightstreamer session is initiated. When the user leaves the Push-Page, the Lightstreamer session is closed. 2.2.2 A traditional site with multiple Push-Pages navigated serially Multiple Push-Pages exist in the site but only one at a time is displayed (e.g. no pop-up Push-Pages are used; no Push-Pages in different frames are present). It could be decided that each Push-Page is a Master Push-Page (because only one Master Push-Page at a time exists, due to serial navigation). The effect is that a Lightstreamer session is initiated and closed each time the user enters and exits a Push-Page. A better strategy for this scenario is to use a frameset, as explained in paragraph A of section 2.2.3 (see Example 2). 2.2.3 A traditional site with multiple Push-Pages navigated in parallel Multiple Push-Pages exist in the site and two or more Push-Pages at a time can be displayed (this is typically accomplished by using pop-up windows or multiple frames). To support this scenarios several solutions are possible: A) Using a FRAMESET An HTML frameset is leveraged in order to add a permanent frame that contains the Master Push-Page. Other Push-Pages contained in frames or pop-ups can be created and destroyed through the navigation, but all of them use the same LightstreamerEngine that is part of the permanent Master Push-Page. The Master Push-Page frame can be a visible or an invisible (i.e. zero-sized) frame. Example 1. The site already contains a frameset in the index.htm page, that loads two frames (menubar.htm and homebody.htm). A first option is to