group: deployment

HTML5 Deployment

Introduction

Note: This is BETA release of HTML5 deployment support. If you intend to use it in production, please test thoroughly that it supports all the functionality you are looking for.

Almost every Internet-connected device has a web browser. If your application can run in a browser, your app can be used anywhere and by anyone, without any need to download or install it.

With LiveCode 8's HTML5 deployment capability, you can now run applications written in LiveCode in any web browser that supports JavaScript and HTML5.

Supported browsers

Only a limited range of browsers are supported for HTML5 deployment in this release of LiveCode.

We hope to broaden the range of supported browsers in the future.

HTML5 engine features

The HTML5 engine in this release of LiveCode has a limited range of features. You can:

Several important features are not yet supported:

Two important unsupported features are unlikely to be added in the near future:

How to deploy an app to HTML5

Step by step

Deploying an app to an HTML5 standalone is straightforward:

1) Open your stack in the LiveCode IDE

2) Select File ? Standalone Application Settings... from the menu bar

3) Browse to the HTML5 tab of the standalone settings window

4) Make sure that the Build for HTML5 checkbox is enabled

5) Close the standalone settings window

6) Select File ? Save as Standalone Application... from the menu bar

Your application will be packaged up and placed in the selected output folder.

Contents of the HTML5 standalone

The HTML5 standalone contains four files:

Testing your HTML5 app with a local web server

Some browsers, such as Google Chrome, do not permit pages to download resources from file:// URLs. You won't be able to test your application in these browsers unless you run a local HTTP server.

A quick and easy way to run a simple local HTTP server is to use Python. Open a terminal window, change directory to your standalone's directory, and run:

python -m SimpleHTTPServer 8080

This will let you access your standalone by opening your web browser and visiting http://localhost:8080.

Reporting bugs

Please report bugs to the LiveCode Quality Centre. Make sure to select "HTML5 Standalone" when you're creating your bug report!

Advanced: HTML5 standalone filesystem

JavaScript applications running in a browser don't have access to the host system's filesystem. Instead, the filesystem-related features of LiveCode, such as open file, use a virtual filesystem (VFS) that exists only in memory. This filesystem is initialised before the engine starts, and is reset and its content discarded when the engine stops (when the user closes the browser view or navigates to a different page).

During engine startup, the VFS is populated from the contents of the standalone.zip file that's created by the HTML5 deployment process. All of the initial files are stored in /boot/ in the VFS.

There are several special files & directories in the /boot/ directory:

In general, if you wish to add new files or directories to the standalone.zip archive, it is best to add them outside the /boot/ directory tree.

Advanced: Embedding an HTML5 standalone in a web page

The default HTML5 page provided by the HTML5 standalone builder is designed for testing and debugging purposes. However, you may want to embed the standalone engine in a more visually appealing page. To do this, you require three elements: 1) a canvas, 2) a JavaScript Module object, and 3) an HTML <script> element that downloads the engine.

The canvas

The engine renders into a HTML5 <canvas> element. There are three important considerations when creating the canvas:

The absolute minimum canvas element would look something like this:

<canvas style="border: 0px none;" id="canvas" oncontextmenu="event.preventDefault();"></canvas>

By default, most web browsers will indicate when the canvas has focus by displaying a highlighted outline. This helps users identify which part of the web page is capturing their key presses. You can usually disable this outline by adding outline: none; to the canvas's CSS styles.

The Module object

The top-level JavaScript Module object contains the parameters that control how the engine runs. At minimum, you need only specify the Module.canvas, which should be your canvas element.

The absolute minimum Module object declaration would look something like:

<script type="text/javascript">
var Module = {
  canvas: document.getElementById('canvas'),
};
</script>

Engine download

The engine is quite a large JavaScript file, so it's downloaded asynchronously in order to let the rest of the page finish loading and start being displayed.

Quite straightforwardly:

<script async type="text/javascript" src="standalone-<version>.js"></script>

Make sure to replace <version> as appropriate.

Bringing it all together

Here's the complete skeleton web page for an HTML5 standalone:

<html>
   <body>
    <canvas style="border: 0px none;" id="canvas" oncontextmenu="event.preventDefault()"></canvas>

     <script type="text/javascript">
       var Module = { canvas: document.getElementById('canvas')  };
     </script>
    <script async type="text/javascript" src="standalone-community.js"></script>
  </body>
</html>

Advanced: Speeding up engine download

Currently, the engine files are almost 30 MB, which is a lot to download before the engine can start. It is possible to speed up the download by enabling deflate compression in the web server configuration.

Enabling deflate compression reduces the total download size to around 6.3 MB. It's recommended to pre-compress the engine with gzip, and then configure your web server to serve the pre-compressed files.

Advanced: Customizing the Module object

There are a number of LiveCode-specific Module attributes that you can modify to affect how the engine behaves:

See also Emscripten's Module object documentation.