An LZX application file may include other LZX files using the <include> element. When you use the <include> tag, the libraries you reference will be compiled into the program.

For example,

<canvas>
  <include href="hello-incl.lzx"/>
</canvas>

<library>
  <text>Hello World!</text>
</library>

A dynamic library is a portion of a program that can be loaded after the main application execution file has loaded. The goal for dynamic libraries is to reduce the initial download size of an OpenLaszlo application. This is required because initial download size (including all requests that precede initial user interaction) is used to evaluate web applications. Reducing the initial download size has the additional benefits of reducing the time to first interaction (although there are other ways of doing this), and of reducing bandwidth costs in the case where an optional feature of the application is not used.

Imported libraries can contain classes, instances, datasets, and <script> blocks. But any media resources in them are moved to the main (calling) application. For example, if this tag is included in the library file to be imported,

<view resource="foo.png"/>

the image resource is baked into the canvas application itself as a Flash resource. This means that the image is downloaded with the calling file, not the called file, as one might otherwise expect.

Resources that are loaded over http, as for example,

<view resource="http:foo.png"/> 

are still compiled into a runtime request.

<include> and <import> both break an application into source files: they let you distribute an application's sources among multiple source files. They address developer workflow, code ownership, and source control issues.

However they are incorporated into an application, all library files share the same namespace.

<import> additional breaks an application into multiple delivery components: they let an application defer download of some components. It addresses the initial download size of an application; nothing more. It is intended for the scenario where all the source files are available when an application is created; it's synonymous with <include> except that the bits it creates are distributed across multiple files, instead of all placed in one file. These bits can't be mixed and matched any more than the bits in a single-object-file application created with <include> can.

OpenLaszlo does not support separate compilation: the library files will only work with the specific application file that they were compiled against, and vice versa.

The rest of this chapter explores these concepts in greater detail.

When the target is a library file (an XML file whose root element is <library> ), the contents of the library file are included in the application. Any views, scripts, fonts, resource, audio, datasource, dataset, and class definitions in the library file are included in the application. A library file can include other libraries, but a library is included in an application only once, no matter how many include statements reference it. For example:

Example 15.3. Including a library file

<canvas height="100" width="400">
  <include href="library.lzx"/>
  <mywindow/>
</canvas>

<library>
  <class name="mywindow" extends="window"
   title="MyTitle">
    <button>Click me!</button>
  </class>
</library>

When the target is an XML file that is not a library file, its root element is included at the point of the include element. This can be used to break a view hierarchy into multiple files. Unlike including a library file, a non-library file is inserted once each time it is included.

The following example shows a view with two buttons, both labeled "Click me!":

Example 15.4. Including a node

<canvas height="100">
  <window layout="axis: y">
    <include href="inner.lzx"/>
    <include href="inner.lzx"/>
  </window>
</canvas>

<button>Click me!</button>

If the type attribute has the value text, the included file is included as characters, rather than XML. This can be used to include literal text from another file.

Example 15.6. Including text

<canvas height="100">
  <window>
    <button>
      <include href="mytext.txt" type="text"/>
    </button>
  </window>
</canvas>

Click me!

If a directory contains a file named library.lzx, you can include that file by referencing the name of the directory. For example, the utils components directory contains a file named library.lzx. Therefore, the following two fragments have the same effect:

<include href="utils/library.lzx"/>

<include href="utils"/>

Similarly, you can write <include href="utils/states"/> to include the files that the file utils/states/library.lzx includes, and <include href="lz"/> to include the OpenLaszlo component set.

3.1.1. Auto-includes

Some of the distributed components are automatically included, if the application references them. If the application uses a tag that it has not defined, but that is defined in the base, lz, charts or utils directory, the file that contains this class is included. The following pairs of programs are therefore equivalent:

Example 15.10. Use button with explicit include

<canvas height="50">
  <include href="lz/button.lzx"/>
  <button>Click me!</button>
</canvas>

Example 15.11. Use button with implicit include

<canvas height="50">
  <button>Click me!</button>
</canvas>

Example 15.12. Subclass button with explicit include

<canvas height="50">
  <include href="lz/button.lzx"/>
  <class name="mybutton" extends="button" fgcolor="red"/>
  <mybutton>Click me!</mybutton>
</canvas>

Example 15.13. Subclass button with implicit include

<canvas height="50">
  <class name="mybutton" extends="button" fgcolor="red"/>
  <mybutton>Click me!</mybutton>
</canvas>

A file is only included if the application references a class that it does not define in its own sources. The following two programs define their own <button> tag, and therefore do not implicitly include the file that defines the OpenLaszlo <button> tag.

Example 15.14. Define button

<canvas height="50">
  <class name="button">
    <text>Click me!</text>
  </class>
  <button/>
</canvas>

Example 15.15. Define and subclass button

<canvas height="50">
  <class name="button">
    <text>Click me!</text>
  </class>
  <class name="mybutton" extends="button" fgcolor="red"/>
  <mybutton/>
</canvas>

Say you had a view, call it "blueview" in a library to be imported. If you merely used the load()to import the code for "blueview", you would see the view show up at the bottom of the application, not at the place where the method was invoked. This is because the load() method only tells <import> what to load, not where to load it. To get the effect we want, we could define a class in a library and instantiate it dynamically. (The following discussion assumes an understanding of delegates and timers, explained in Chapter 30, Delegates.)

To do position code where we want it in the importing application, we would make a delegate that directly listens for the onload event from the <import> and instantiates the class (or calls a method to do so). Something like:

   <handler name="onload" reference="blueview">
      this.makeChild({name: 'blueview', ...});
   </handler>

We could define an onload() on <import> to call a method to set a global variable "loaded" to true.

Then, at the place where we want blueview to appear, we could load the library and then set up a delegate and timer which calls a method to see if the variable "loaded" is true, and if not reset the timer. If it is true--that is, if the class has been loaded-- the view is created.

Accessibility is implemented using five attributes on <view> and two methods on LzBrowser.

In LZX, the most basic visible object is a view. Since almost every visible object inherits from view, almost all visible objects will inherit accessibility support including image, text, button, checkbox, and radio button. (The one exception, images embedded within editable text views, is covered at the end of this section.) The following methods and attributes will be added to view:

These are the attributes on view. They are described briefly below.

These are the methods on LzBrowser.

By default, all text contained in an OpenLaszlo application will be read by supported screen readers. Therefore, the activation feature allows you to specify which views should be read by the screen reader. Activation applies to the current view and all of its children. Accessibility name and description provide the overview and detailed text for the screen reader. Accessibility tab ordering, specifies the reading order for accessible objects. Silencing/unsilencing specifies whether an individual item is accessible or not. Finally, LzBrowser provides the isAAActive() method to determine if a screen reader is active and the Flash player is currently focused.

aadescription is treated separately from the contents. If it's specified, aadescription will be read in addition to the aaname. By default, aaname is equal to the contents of the text field. aaname can also be specified or overridden.

For non-MSAA compliant screen readers such as R&W Gold, OpenLaszlo supports the ability to place text on the clipboard from within an OpenLaszlo application using the LzBrowser.setClipboard().

In this example, there are two views that provide accessibility information. When the first view is clicked, it uses the scripting API to unsilence the button.

<view aaactive="true" aaname="Activation Button" aadescription="This button allows you to access more information by activating important views." aatabindex="1" onclick="important.setAASilent(false)">

<button id="important" aaactive="true" aaname="Important Information" aadescription="Here is some important information." aatabindex="2" aasilent="true"/>