LZX is designed to make it easy for you to integrate media resources into your application in a flexible and dynamic manner. You can include images, audio, video, and animations that were created using standard third-party content creation tools. This chapter describes the media formats that are currently supported as resources to <view> s in OpenLaszlo 4.0. It then goes on to describes how to integrate and control media in your application. It concludes with some optimization tips.

Note that in addition to media that can be attached as resources to views, streaming audio and video can be played by <videoview> s. Please see Chapter 39, Audio and Video for a discussion of streaming media.

For a discussion of streaming media, see Chapter 39, Audio and Video.

The list of supported media types varies slightly depending on the target runtime and whether the application is to be deployed SOLO or proxied.

2.1. Media for SWF SOLO applications

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.

SOLO applications compiled to SWF depend on Flash to load images (whereas the proxied applications get help from the transcoder on the server). This means that SOLO applications are limited to file types supported natively by Flash.

2.1.1. Flash 7 and Flash 8 limitations

Flash player version 7 it can only load a limited set of jpegs encodings; it cannot do interleaved or progressive jpeg. If you run Flash player 8 it can do more wide range of jpeg encoding. Set the compiler to compile for Flash 8 as a target runtime to get this expanded range of image formats (also PNG and GIF).

2.2. DHTML Limitations and workaround

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.

Browsers do not natively support .swf or audio or video formats. You must transcode them, omit them from your application, or embed a flash player in your application to handle them.

2.2.1. Transcoding .swf to .png

Files in .swf format can be transcoded to .png format for display by the DHTML runtime. OpenLaszlo provides a facility, called autopng, for doing this automatically. As a convenience, the server and compiler search for a corresponding png file if a swf file is referenced in the DHTML runtime. To use this mechanism in your own code, create a png file with the same basename as the swf file, and place it in the same directory as the swf resource you want it to replace.

2.2.2. Audio and Video in DHTML applications

	Note
	The following discussion applies to audio and video resources attached to <view>s, not to <videoview>s. <videoview>s are not supported at all for the DHTML runtime.

In order to display swf-formatted audio and video within a DHTML application, you may embedd a swf player in the page. For a discussion of how to do this, see Chapter 35, Browser Integration.

The <view> is the most basic viewable element in an OpenLaszlo application and it is described in the chapter on views. A view may have a resource attached to it. The resource represents a piece of media (image, audio, video, or animation) that the view controls. For images, the view typically displays the image. For time-based media (audio, video, animation), the view can be used to start, stop, or jump to a specific frame or time in the media.

For a simple informal introduction to attaching resources to views, see Chapter 8, Introduction to Media and Art Assets. The chapter you're reading now briefly goes over topics covered in that tutorial and then goes into greater depth.

Resources may be declared directly inside a view using the view's resource attribute:

Example 18.1. Importing a resource

<canvas height="110">
  <view resource="../resources/logo.gif"/>
</canvas>

Or they may be declared externally as first-class objects themselves:

Example 18.2. Declaring a resource

<canvas height="110">
  <resource name="myname" src="../resources/logo.gif"/>
  <view resource="myname"/>
</canvas>

Laszlo supports the notion of a resource <frame> . A multi-frame resource is a resource that has a single name but refers to multiple independent pieces of media that are sequenced. Here is an example of declaring a multi-frame resource:

Example 18.3. Declaring a multi-frame resource

<canvas height="180">
  <resource name="myresource">
    <frame src="../resources/logo.gif"/>
    <frame src="../resources/sky.jpg"/>
  </resource>
  <simplelayout spacing="5"/>
  <view id="myview" resource="myresource"/>
  <view layout="axis: x; spacing: 3">
    <text>Frame:</text>
    <radiogroup>
      <radiobutton selected="true">1</radiobutton>
      <radiobutton>2</radiobutton>
      <handler name="onvalue" args="v">
        myview.setResourceNumber(Number(v));
      </handler>
    </radiogroup>
  </view>
</canvas>

You can use a multi-frame resource to construct an animation that moves between frames when you call the LzView.play() method. Conversely, when you import a resource that contains an animation, each frame of the animation automatically becomes a frame in that resource. In other words, art assets that contain multiple frames themselves are multi-frame resources. Just as with multi-frame resources that are constructed in LZX by importing each frame individually, you can control the frame that is currently displayed.

Example 18.4. Importing an animation

<canvas height="220">
  <simplelayout spacing="5"/>
  <resource name="myresource" src="resources/logo.swf"/>
  <button onclick="me.stop()"> Stop </button>
  <button onclick="me.play()"> Play </button>
  <text text="${me.frame + ' out of ' + me.totalframes + ' frame(s)'}"/>
  <view layout="axis: x; spacing: 4">
    <button isdefault="true" text="Set current frame: " 
      onclick="me.setAttribute('frame', Number(tt.text))"/>
    <edittext id="tt" width="50"/>
  </view>
  <view id="me" resource="myresource"/>
</canvas>

Multi-frame resources are also useful for structuring the display of a single visual element or component that takes on different appearances:

Example 18.5. Using multi-frame resources

<canvas height="120">
  <!-- create the multi-frame resource and give it a name -->
  <resource name="mybutton_rsrc">
    <!-- first frame is the mouseup state of the button -->     
    <frame src="../resources/button-up.png"/>   
    <!-- second frame is the mouseover state of the button -->     
    <frame src="../resources/button-over.png"/> 
    <!-- third frame is the mousedown state of the button -->     
    <frame src="../resources/button-down.png"/> 
  </resource>

  <!-- attach the resource to a view with mouse events -->
  <view resource="mybutton_rsrc" 
        onmouseover="setResourceNumber(2)"
        onmouseout="setResourceNumber(1)"
        onmousedown="setResourceNumber(3)"
        onmouseup="setResourceNumber(2)"/>

</canvas>

In the examples above, we've declaratively tied resources to view. But we haven't expressed anything about when or how the application should pull in the needed resource. We call this resource loading and LZX provides flexibility over how and when the application loads resources. The most important choice is whether a resource should be loaded at compile time or run time.

  <resource name="myname" src="resources/logo.gif"/>

5.2. Run-time resources

There are two main ways to load resources at run-time. The first is to use special syntax that is understood by the <view> 's resource attribute. If you specify a value for this attribute that is an HTTP url, the compiler assumes that this resource should be loaded at runtime:

Example 18.7. Loading a resource at runtime

<canvas height="180">
  <view resource="http:../resources/logo.gif"/>
</canvas>

The second method is to use the LzView.setSource()() method. The previous example is equivalent to the following one:

Example 18.8. Loading a resource at runtime via script

<canvas height="180">
  <view oninit="this.setSource('http:../resources/logo.gif')"/>
</canvas>

	Note
	LZX treats HTTP URLs that omit the two slashes // after the colon (:) as being relative to the application.

LzView.setSource()() provides more control over the loading of the resource. Using this method, you can:

• choose whether or not the server and/or client should cache the resource;

• specify a URL that instructs the server to use a specific protocol to fetch the resource;

• specify HTTP request headers that should be used when fetching the resource over HTTP.

5.2.1. Protocols for proxied applications

	Note
	This section does not apply to SOLO applications.

Before sending resources to a running, proxied, OpenLaszlo application, the OpenLaszlo Server first fetches (or proxies) the resource. The server uses the URL for the resource to determine how and where to get the resource. The term back-end is used to refer to the server that is ultimately providing the resource. Depending on your configuration, the back-end can be the OpenLaszlo Server host itself. Or it may be another distinct host.

The OpenLaszlo Server determines the protocol to use to communicate to the back-end based on the URL for the resource. By default, URLs that are to be loaded at runtime, that don't specify the protocol are assumed to be HTTP urls. OpenLaszlo supports communication to back-end hosts (including localhost itself) via the HTTP protocol. Relative HTTP URLs are thus fetched using a localhost HTTP transfer.

5.2.2. Caching

By default, in proxied applications, media that is accessed at runtime is cached both in the server and in the client browser. The OpenLaszlo Server uses the standard HTTP If-Modified-Since/Last-Modified caching mechanism specified in the HTTP 1.1 specification.

The OpenLaszlo Server actually maintains two media caches. One cache is used for resources that are requested at runtime. This is simply called the Media Cache. It also maintains a second cache for resources that are compiled into applications called the Compiler Media Cache. In general, the Compiler Media Cache settings only affect the speed of the OpenLaszlo compiler. The settings for the Media Cache can affect server performance. See The Deployer's Guidefor details.

The example below provides a text input area for you to type in urls that you'd like to test. To run the example, copy it into your local environment and compile it:

Example 18.9. Testing runtime resource loading

<canvas height="400">
  <font src="helmetr.ttf" name="helvet"/>
  <simplelayout spacing="3"/>

  <view>
    <simplelayout axis="x" spacing="2"/>
    <text valign="middle">Type url:</text>
    <edittext width="500" id="url">http:../resources/logo.gif</edittext>
  </view>
  <text>(also try resources/logo.swf)</text>

  <command onselect="butt.doit();"  key="['Enter']" active="true"/>

  <checkbox text="Cache in client" id="ccache"/>
  <checkbox text="Cache in server" id="scache"/>

  <button id="butt">Make request
    <handler name="onclick">
      this.doit();
    </handler>

    <method name="doit">
    <![CDATA[
      status.setText("Requesting: " + url.getText()); 

      // Determine caching from checkboxes
      var caching = 'none'
      if (ccache.getValue() & scache.getValue()) {
          caching = 'both';
      } else if (ccache.getValue()) {
          caching = 'clientonly';
      } else if (scache.getValue()) {
          caching = 'serveronly';
      }

      me.setSource(url.getText(), caching) ;
    ]]></method>
  </button>
  <button onclick="me.stop()"> Stop </button>
  <button onclick="me.play()"> Play </button>
  <text text="${me.frame + ' out of ' + me.totalframes + ' frame(s)'}"/>
  <text multiline="true" width="200" height="100" id="status"/>
  <view id="me">
    <handler name="onload" args="e">
      status.setText('loaded: ' + e);
    </handler>
    <handler name="onerror" args="e">
      status.setText('error: ' + e);
    </handler>
    <handler name="ontimeout" args="e">
      status.setText('timeout: ' + e);
    </handler>
  </view>
</canvas>

The <image> tag has the effect of declaring a view and associating a resource with it. This is a convenient shorthand that can make your programs easier to read and maintain. Do not confuse the <image> with the <img> . The latter is used to include images inside HTML text and behaves like the <img> tag in HTML.