# Customising Application Startup

By default, the compiler will output a standard `index.html` into the
application's output directory; this creates a vanilla output which is suitable
for many applications, but does not provide any loading feedback and has a
standard title.

If you just want to change the title of the application web page, the easier way
to do it is set the title on the Application object - if you're using the
compiler API, see the `title` property of `qxcompiler.app.Application`, but if
you're using `qx` command line tool modify your `compile.json` to look like
this:

```json
{
    /** Applications */
    "applications": [
        {
            "class": "demoapp.Application",
            "theme": "demoapp.theme.Theme",
            "name": "demoapp",
            "title": "My Demo Application"
        }
    ],
```

If you want to customise this further, you can replace the `index.html` with your own version by adding a "bootPath" setting to your application in `compile.json` which contains the path to the directory (normally `"source/boot"`), for example:

```json
{
    /** Applications */
    "applications": [
        {
            "class": "demoapp.Application",
            "theme": "demoapp.theme.Theme",
            "name": "demoapp",
            "title": "My Demo Application",
            "bootPath": "source/boot"
        }
    ],
```


# Custom index.html for your applications

To customise the index.html which is generated, create a file called
`boot/index.html` that will be used as a template.  The `boot/index.html` is
copied with template variables in form `${variableName}` replaced.

The template variables supported are:
* `resourcePath` - a relative path to the `resource` output folder 
* `targetPath` -  a relative path to the target output folder
* `appTitle` - the application title, as configured in `compile.json`
* `appPath` - a relative path to the application's output folder
* `preBootJs` - a code snippet to be placed in index.html immediately before the boot.js script is loaded

Note that previous version of the compiler would also add a `<script>` tag which
links to `boot.js` but this is now also done by template replacements - you MUST
include this code (or it's equivalent) in your index.html:

```
${preBootJs}
<script type="text/javascript" src="${appPath}boot.js"></script>
```

Here's a complete, although minimal, example of an index.html:
```
<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>${appTitle}</title>
</head>
<body>
  ${preBootJs}
  <script type="text/javascript" src="${appPath}boot.js"></script>
</body>
</html>
``` 


# Splash Screens

**NOTE** It's fair to say that this is still a work in progress - although this
*treatment for SplashScreens works just fine, it is only able to update the UI
*as each individual script loads, which means that for a `build` target, nothing
*will appear because there is only one script file.

Splash screens are an optional feature of the application loader in
`qooxdoo-compiler` that will provide an attractive feedback with a progress bar
all the way through your application's startup.

By default, the loader does not provide any splash screen or progress bar; to
add one, you need to replace the application's `.html` file with your own, and
provide a global object called `QOOXDOO_SPLASH_SCREEN` that the boot loader can
call during the boot process.

## Loading Speed

Splash screens will slow down the load fractionally, but only in the order of
100-200ms.  It's important to remember that loading speed is subjective, and as
a developer the progress bar emphasises an unnecessary slow down of the load,
whereas to a user a blank screen emphasises waiting for startup.  But if you
measure it, the difference in time is negligable.

The new loader supports URL query parameters which allow you to customise the
startup to fine tune or eliminate the boot loader so that you can time various
different approaches.  If you have installed a boot loader, try appending
`?qooxdoo:feedback-disable=true` to your application's URL and comparing boot
times.  For more information on loader URLs, see [here](LoaderUrls.md).

## Example

For a working example, take a look at the demo (LINK MISSING)
- if you add this folder to your application's `source` folder and re-run `qx
compile`, it will have a splash screen with loading progress bar.

## Chunking

Previously, the only option for loading scripts was either asynchronously (also
called "parallel" loading) or not.  Asynchronous loading queues all scripts to
be loaded by the browser (which could be hundreds thousands) and allows the
browser to go ahead and load as fast as possible.  For splash screens this is
not ideal because the browser is working so hard at loading scripts that it does
not redraw the display with any updated progress information, so from the point
of view of the user the progress bar will be stuck at a low number until the
application is suddenly running.

To solve this, chunking (enabled by default *only if* there a
`QOOXDOO_SPLASH_SCREEN` object) divides the list of scripts to load into
"chunks" and adds a small 1ms timeout between each chunk to allow the browser to
redraw the screen.  This slows the loading because of the 1ms delay and the time
it takes to redraw, but on the other hand your user will get feedback all the
way through the load.

By default the chunks are 20% of the total number of scripts, but you can
override this with the `getSettings` method in the API.

## API

`QOOXDOO_SPLASH_SCREEN` is a plain Javascript object that looks like this:

```javascript
  window.QOOXDOO_SPLASH_SCREEN = {
    loadBegin: function(callback) {
      /* ... snip ... */
      callback();
    },

    loadComplete: function(callback) {
      /* ... snip ... */
      callback();
    },

    scriptLoaded: function(options, callback) {
      /* ... snip ... */
      callback();
    },

    getSettings: function() {
      /* ... snip ... */
      return null;
    }
  };

```

The `options` parameter has a `command` property (e.g. `"script-loaded"`) that
determines what the other properties of the object will be.

### `loadBegin(callback)`

This is fired immediately before scripts start to be loaded; `callback()` must
be called at the end (script loading will not begin until it has been called)

### `loadComplete(callback)`

This is fired when all scripts are loaded and the application is about to
startup; `callback()` must be called at the end (the application will not start
until it has been called)

### `scriptLoaded(options, callback)`

This is fired every time a script completes loading, and has these properties in
`options`:

- `numScripts` - total number of scripts to load
- `numScriptsLoaded` - number of scripts fully loaded so far
- `numScriptsLoading` - number of scripts in progress

### `getSettings()`

This is called once before any scripts are loaded to allow the loader to
override default settings.  The result can be null, or an object which has these
properties:

- `isLoadChunked` - (**optional**) whether to load scripts in "chunks"
- `loadChunkSize` - (**optional**) if loading with chunks, how big each chunk
should be (default is 20% of the number of scripts)
