As we said above, web browsers display HTML pages. This means that OpenLaszlo applications are delivered to browsers by means of HTML pages. Sometimes those HTML pages contain nothing visible to the user other than the LZX application itself. In such cases the HTML page is essentially invisible, and the fact that there's an HTML page there at all doesn't really matter to the developer or to the user of the application. Such HTML pages, whose only function is to present the OpenLaszlo application to the browser, are sometimes called "wrapper pages."

Depending on which target runtime they're compiled for, OpenLaszlo applications have different relationships with the JavaScript engine of the browser in which they run. To a rough approximation, LZX applications compiled to SWF are foreign objects embedded into an HTML page, and you must use a formal protocol to get across this logical barrier between the LZX application and the JavaScript engine. Applications compiled to DHTML become just a part of the HTML page that contains them. From the point of view of the browser, there is no difference between the OpenLaszlo application and the surrounding page.

But although some of the implementation details differ for the different runtime targets, the OpenLaszlo APIs are, wherever possible, consistent, so that you use the same programming model regardless of the target runtime. So, for example, there is a method called lz.embed.swf() for embedding SWF OL applications into the HTML page; this generates an HTML <embed> tag. Similarly, there is an lz.embed.dhtml() for placing an OL application compiled to DHTML within a web page. In this case there is no <embed> generated or required, but the methods have similar names because they perform analogous functions.

Applications compiled to SWF are executed by the Flash player and must make use of the lz.Browser service in order to "escape" to the browser's JavaScript environment.

Any attributes that are declared on the canvas are visible to the browser JavaScript. To go "the other way", from the browser "into" the OpenLaszlo application, the lz.embed['lzapp'].getCanvasAttribute() and lz.embed['lzapp'].setCanvasAttribute() methods are used, where 'lzapp' denotes the application ID.

These are discussed below.

Although OpenLaszlo applications deployed on the Flash runtime are not dependent on the browser or operating system for their look or behavior, there are some important limitations that the browser container places on the application. There are also a number of Flash Player features that your application can use which are not available in applications compiled to DHTML.

OpenLaszlo applications compiled to SWF can be sent from the OpenLaszlo Server to client in any of several forms:

2.2.1. The lz.Browser service

SWF only: The features described in this section only work in applications compiled to SWF. They do not work in applications compiled to other runtimes.

The lz.Browser service provides access to the browser and player environment. It includes methods to load URLs in the browser and check the version of the player. Furthermore, by using the lz.Browser service together with other OpenLaszlo functions described below, you can build applications that pass information and control between the OpenLaszlo application and the JavaScript of the browser.

The lz.Browser service is always running.

DHTML only: The features described in this section only work in applications compiled to DHTML. They do not work in applications compiled to other runtimes.

Applications that are compiled for DHTML run within the browser's JavaScript environment. They are essentially compiled into the DOM of that page.

Each LZX application has exactly one <canvas> element, which, when compiled to DHTML, becomes an object. When you embed an LZX application compiled to DHTML into an HTML page, it just becomes part of that page's DOM, and you can address it directly. The "foo" object of the LZX application becomes canvas.foo of the DOM. If there is a swf embedded in that (DHTML) Openlaszlo application, you can still use the mechanism for talking to SWF applications to reach it.

For DHTML, you can call canvas JavaScript directly because it is loaded in the browser. That is to say, unlike in the case of communicating with SWFs, you do not need to use getCanvasAttribute() or setCanvasAttribute(), nor do you need to use the lz.Browser service.

2.3.1. Embedding the LFC for DHTML applications

DHTML only: The features described in this section only work in applications compiled to DHTML. They do not work in applications compiled to other runtimes.

When you compile an application to SWF, the compiler includes the Laszlo Foundation Class, or LFC in the resulting file. This does not happen for applications compiled to DHTML, therefore the LFC must be downloaded explicitly. To make the LFC available to DHTML applications, include the following call in the page head:

<script type="text/javascript">
    lz.embed.lfc('/lps-5.0.x/lps/includes/lfc/LFCdhtml.js', '/lps-5.0.x/'); 
</script>

The optional appenddivid property can be passed in to lz.embed.swf() or lz.embed.dhtml() method to specify the id of a div whose contents should be replaced with the LZX application. If a div with that ID doesn't exist, one will be written into the document where lz.embed.{swf,dhtml}() is called. If appenddivid is not specified, the div written will be based on the id property + 'Container'.

Alternatively, you can generate wrappers by using the various request types on the url you use to browse to your application, as explained in Chapter 49, Understanding Compilation:

The default wrapper page contains logic to detect the version of flash running on the client.

Depending on which version is running, you may wish to use some LZX features that run in some, but not all, versions of the Flash Player.

When laying out a page that will use OpenLaszlo applications in different places, you can use a frameset like this:

<html>
  <frameset cols="128,*">
    <frame name="navBar" src="myOpenLaszloNav.lzx?lzt=html"/>
    <frame name="contentArea" src="myOpenLaszloContent.lzx?lzt=html"/>
  </frameset>
</html>

Inside your application use the target parameter of lz.Browser.loadURL() to load pages in the target frame.

lz.Browser.loadURL('http://www.openlaszlo.org','contentArea');

Like framesets, OpenLaszlo applications can be embedded within an "inline frame" or <iframe> which can be more flexible for your layout and easier to use. Like regular frames, inline frames can be named for later reference by the OpenLaszlo application.

<html>
  <body>
    <h1>Here is a header</h1>
    <div align="center">
      <iframe src="myOpenLaszloApplication.lzx?lzt=html" width="200"
        height="200" frameborder="0" name="inlineApplication"
        scrolling="no"/>
    </div>
  </body>
</html>

Bear in mind that the iframe will contain a canvas, and unless you want the browser to provide scrollbars, you should set the width and height equal to that of your canvas plus any margin you may have included.

The same way you would target content to a frame, you can target the loadURL to new window.

Example 35.7. new blank browser window

<canvas width="100%" height="27">
  <button onclick="lz.Browser.loadURL('http://www.openlaszlo.org','_blank');" text="Click Me!"/>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008, 2010 Laszlo Systems, Inc.  All Rights Reserved.             *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

This mechanism can also be used to name the window allowing subsequent loads to occur in the same window

Example 35.8. reusing new browswer window

<canvas width="100%" height="56">
  <simplelayout/>
  <button onclick="lz.Browser.loadURL('http://www.openlaszlo.org','newOpenLaszloWindow');" text="OpenLaszlo Homepage"/>
  <button onclick="lz.Browser.loadURL('http://forum.openlaszlo.org','newOpenLaszloWindow');" text="OpenLaszlo Forum"/>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2008, 2010 Laszlo Systems, Inc.  All Rights Reserved.             *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

Once the data has been passed in you can simply access it by calling getInitArg() from within the OpenLaszlo application.

<canvas debug="true"
    oninit="Debug.debug("%w", lz.Browser.getInitArg('myData'))"/>

In many cases you will have full control of the HTML content that is embedding your application. In many other cases you won't be able to depend on the existence of those query parameters so it is wise to provide sane defaults for those values:

Example 35.11. setting defaults

<canvas debug="true" width="100%" height="200">
  <attribute name="onceData" value="$once{lz.Browser.getInitArg('myData')}"/>
  <handler name="oninit">
    var innerVar = lz.Browser.getInitArg('myData');
    if (innerVar == null) innerVar = 'bar'; // default to 'bar'
    Debug.debug("%w", canvas.onceData);
    Debug.debug("%w", innerVar);
  </handler>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2010 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

The above application is requested without a myData query parameter. The debugger therefore displays the default value bar. If this application is requested with the myData=foo query parameter, it will display the value foo. Click here to see the application in a popup window with the query parameter applied.

Using query parameters, you can craft your application to start up in a specific state. The default behavior of a tabslider is to have none of the tabelements opened at startup. The following application changes that default to open to the tab specified on the query parameter, and if one isn't provided, open to the first element.

Example 35.12. setting defaults

<canvas width="100%" height="250">
  <tabslider width="150" x="10" y="10" height="200" spacing="2" slideduration="300">
    <handler name="oninit">
      var opened = lz.Browser.getInitArg('tab') || 'one';
      this[opened].setAttribute('selected', true);
    </handler>
    <tabelement name="one" text="Tabelement One"/>
    <tabelement name="two" text="Tabelement Two"/>
    <tabelement name="three" text="Tabelement Three"/>
  </tabslider>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007-2008, 2010 Laszlo Systems, Inc.  All Rights Reserved.        *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

Flash

HTML5

Click here to see this application in a popup with a different initial state applied. This is useful when creating links from outside the application, or for creating a bookmark for an application. Another thing to do is read browser cookies from JavaScript and pass in the parameters when calling the application.