The Microloader

"Microloader" is the name for Sencha's data-driven, dynamic loader for JavaScript and CSS. The Microloader is provided by Sencha Cmd as part of your generated application. This guide will give you a solid understanding of what the Microloader does and how you can tune it for your specific requirements.

It is important to clarify that the Microloader used by Ext 6 is currently a different implementation than that used by Ext JS 5 or by Sencha Touch. The Ext JS 6 Microloader provides all of the same functionality as was provided by the Sencha Touch microloader, but has some improvements and new controls available in the "app.json" file, which are discussed further later in this document. All microloader implementations are provided by Sencha Cmd, and upgrades to the microloader will be applied by the "sencha app upgrade" process.

The Manifest

app.json

This file is where you specify details about your application. This configuration file is first consumed by the Sencha Cmd build process. Sencha Cmd transforms the content of "app.json" and passes on the resulting manifest to the Microloader to use at runtime. Lastly, Ext JS itself also consults the runtime manifest for configuration options.

Ext.manifest

When you launch your application, you will find the processed content of "app.json" loaded as “Ext.manifest”. Ext JS 6 uses the Ext.manifest properties that you have specified to do things like enable the Compatibility Layer. There are various options supported by the Microloader for getting this object loaded which we'll discuss later.

The script Tag

To use the Microloader, your page will need to contain the following script tag:

<script id="microloader" data-app="12345" type="text/javascript" src="bootstrap.js"></script>

By default, this script tag will be replaced by the build process but is used during development to load the application. The data-app atrribute should have been generated for you during app scaffold. This is a unique ID used in local storage to prevent data collision.

Defaults and Customization

The "app.json" file generated by Sencha Cmd contains many properties that you may want to adjust. These properties are documented inline to explain what they each control.

If you are upgrading a project, your "app.json" may not contain all of the possible options. After performing the upgrade, the default values for any missing properties can instead be found in “.sencha/app/app.defaults.json”.

The following are the properties most often of interest.

indexHtmlPath

This is the path to the application's HTML document (relative to the "app.json" file). By default this property is set to "index.html". If you server uses PHP, ASP, JSP or other technology, you can change this value to point at the proper file like so:

"indexHtmlPath": "../page.jsp"

If you change this setting, you will likely also need to change your "output" options (see below).

framework

The name of the framework; either "ext" or "touch". For example:

"framework": "ext"

theme

For Ext JS applications, this is the name of the theme package. For example:

"theme": "ext-theme-crisp"

toolkit

For Ext JS 6 applications, this is the name of the toolkit package. For example:

"toolkit": "classic"

js

An array of descriptions of JavaScript code files to load. By default, an Ext JS 6 application will have something like this:

"js": [{
    "path": "app.js",
    "bundle": true
}]

This entry specifies your application's entry point. The "bundle" flag indicates that when you run "sencha app build", this entry should be replaced by the concatenated output of the build. You can add other files to this array like so:

"js": [{
    "path": "library.js",
    "includeInBundle": true
},{
    "path": "app.js",
    "bundle": true
}]

When you add extra files, there are some optional properties that indicate how the build process will treat them. For example, in the above case, "library.js" will be included in the concatenated build output and removed from the runtime manifest.

If instead you removed "includeInBundle", then "library.js" would be assumed to reside in your app folder and would then be copied to the build output folder. The entry would remain in the manifest and be loaded separately by the Microloader.

To simply pass along the entry for the Microloader to load (and not be copied by the build process), add the "remote" property like so:

"js": [{
    "path": "library.js",
    "remote": true
},{
    "path": "app.js",
    "bundle": true
}]

While you can add entries to this array, most dependencies will appear in "requires" statements in your code or in "app.json" (to require packages).

Note: For Sencha Touch, you will typically have "sencha-touch-debug.js" in the "js" array. This entry is not needed for Ext JS 6 because the "framework" setting is sufficient.

css

Your CSS assets are handled slightly different than JavaScript. This is because in a stock Sencha Cmd application, CSS is compiled from the .scss source. The initial content of the "css" property looks something like this:

"css": [{
    "path": "boostrap.css",
    "bootstrap": true
}],

This CSS file is a simple stub that imports a build of your "sass" folder. The "bootstrap" flag indicates that the entry is used for development but should be removed from build output. For a build, the compiled CSS file will be appended to the "css" array of the generated manifest.

Initially, "bootstrap.css" imports the theme from the framework and looks something like this:

@import "..../ext-theme-neptune/build/ext-theme-neptune-all.css";

As you build your app, this file is updated to point at the most recently built CSS file. For example if you run "sencha app build", the production CSS file will be imported by "bootstrap.css" like so:

@import "..../build/..../app-all.css";

The "css" entries also support the "remote" property. When remote is not set they operate in the same way as "js" entries in that they are copied to the build output folder.

requires

This array holds names of required packages. When Sencha Cmd processes this list, it will automatically download and extract any missing packages into your workspace. Packages can likewise contain requires in their "package.json". These will also be downloaded and extracted as needed.

These package names can also contain version requirements. For details on specifying version numbers, see Sencha Cmd Packages.

output

The "output" object gives you the ability to control where and how build outputs are generated. This object can control many aspects of the build output. In our use of indexHtmlPath above, we told Sencha Cmd that the source for the page was "../page.jsp". To complete this process, we use output to tell Sencha Cmd where the built page will reside relative to the built JavaScript and CSS. To maintain the same relative arrangement as in the source tree, we would add this to "app.json":

"output": {
    "page": {
        "path": "../page.jsp",
        "enable": false
    },
    appCache: {
        "enable": false
    },
    "manifest": {
        "name": "bootstrap.js"
    }
}

In this case, we've also added "enable" and set it to false. This combination tells Sencha Cmd were the final page will be but also not to generate it by copying the source (as specified by "indexHtmlPage").

Since we are not generating the page, the Microloader script tag will contain the same "src" value of "bootstrap.js". The "manifest" option above instructs Sencha Cmd to generate the built Microloader using the same name. This is a common need for server-side template environments like JSP or ASP, but also others.

Application Cache

The Application cache is a manifest used to determine what assets the browser should store for offline access. To enable this simply toggle the enable flag for the appCache property inside your output object. For example:

"output": {
    "page": "index.html",
    "appCache": {
        "enable": true
    }
}

The appCache property seen here is used to determine if the build process will generate an Application Cache Manifest file. If this is set to true the manifest will be generated from the top level appCache config object in your app.json. It will look something like this:

"appCache": {
    "cache": [
        "index.html"
    ],
    "network": [
        "*"
    ],
    "fallback": []
}

Local Storage Cache

The Local Storage Caching system is a seperate offline caching system from the browsers built in Application Cache. Assets are stored in Local Storage via unique keys and during bootstrap these assets will be requested first before attempting any remote loading. This allows for applications to be loaded very fast and without an internet connection. This cache also allows for delta patching of assets which means that only the changed bits of your assets, css or js, will be loaded over the network. The file will then be patched in local storage and delievered to the user.

This cache is enabled per asset via the update propety. This can be set to either "full" or "delta". Below is an example of JS and CSS assets both with Local Storage Caching enabled.

// app.js will be delta patched on updates
"js": [
    {
        "path": "app.js",
        "bundle": true,
        "update": "delta"
    }
],

// app.css will be fully downloaded on updates
"css": [
    {
        "path": "app.css",
        "update": "full"
    }
]

Once Local Storage Caching has been enabled on an asset one must globally enable the cache config "app.json". Normally during development builds one will want this set to false and in production builds this would be set to true.

"cache": {
    "enable": false
}

One can also configure the path and generation of deltas. When the deltas property is set to a truthy value all assets using Local Storage Caching will have detas generated into the builds "deltas" folder. If deltas is set to a string the value will be used as the folder name that all patch files will be saved into. The delta toggle will have no effect if enable is set to false.

"cache": {
    "enable": true,
    "deltas": true
}

Both Application Cache and Local Storage Cache will instantly load files for offline access. Because of this updated files will not be loaded into the users current application experience. Once the Microloader has detected and loaded new Application Cache or Local Storage files it will dispatch a global event allowing you to prompt the user to reload the application for the latest updates. You can listen for this event by adding the following code to your application:

Ext.application({
name: 'MyApp',
mainView: 'MyMainView',
onAppUpdate: function () {
    Ext.Msg.confirm('Application Update', 'This application has an update, reload?',
        function (choice) {
            if (choice === 'yes') {
                window.location.reload();
            }
        }
    );
}

More

Many of the properties we've seen are instructions to the build process, while others are processed by the Microloader. As mentioned, the manifest is also understood by Ext JS as a means to configure some of its capabilities. For details on these and other properties, consult the comments in "app.json".

Build Profiles

When an application has multiple variations, we can add a “builds” object to "app.json" to describe the desired builds like this (taken from Kitchen Sink):

"builds": {
    "classic": {
        "theme": "ext-theme-classic"
    },
    "gray": {
        "theme": "ext-theme-gray"
    },
    "access": {
        "theme": "ext-theme-access"
    },
    "crisp": {
        "theme": "ext-theme-crisp"
    },
    "neptune": {
        "theme": "ext-theme-neptune"
    },
    "neptune-touch": {
        "theme": "ext-theme-neptune-touch"
    }
}

Each key in “builds” is called a "build profile". The value is a set of property overrides that are applied to the base content of "app.json" to produce the output manifest as described below. In this case, the “theme” property is all that is being modified for each build profile.

In addition, there are two other optional properties that are common variations for application builds: “locales” and “themes”. These are used to automate the process of producing the final build profiles. For example, Kitchen Sink uses “locales”:

"locales": [
    "en",
    "he"
],

When “locales” or “themes” are given, each of the values are combined with each of the entries in “builds” to produce the final manifests. In this case “neptune-en”, "neptune-he", “crisp-en”, etc. are the final build profile names.

Generating The Manifest

As mentioned previously, "app.json" undergoes a transformation during the build process prior to being presented at runtime as "Ext.manifest". This process consists of merging object much like Ext.merge but with a twist: when two arrays are "merged" they are concatenated.

The first step in this transformation is to merge settings for the desired build "environment" (for example, "production" or "testing"). Following this, if a build profile is being used, its contents are merged. The, if either the root or build profile specified a "toolkit" ("classic" or "modern"), that object's properties are merged. Finally, if a packager ("cordova" or "phonegap") is configured, its properties are merged.

In pseudo-code this would be something like this:

var manifest = load('app.json');

// These would come from the "sencha app build" command:
var environment = 'production';
var buildProfile = 'native';

mergeConcat(manifest, manifest[environment]);
if (buildProfile) {
    mergeConcat(manifest, manifest.builds[buildProfile]);
}
if (manifest.toolkit) {
    mergeConcat(manifest, manifest[manifest.toolkit]);
}    
if (manifest.packager) {
    mergeConcat(manifest, manifest[manifest.packager]);
}

Packages

The final step in producing the manifest is to add any required packages.

When a required package specifies "js" or "css" entries in its package.json, these are concatenated in package dependency order to the front of the arrays already produced. This allows a package to handle such dependencies itself.

In addition to "js" and "css" entries, the content of each required package's package.json file is cleaned up slightly and added to the "packages" object in the final manifest keyed by the package name. If "app.json" already contains a “packages” object, then that object will be merged with the content of the corresponding package.json file. Priority is given to "app.json" to allow its properties to pass through as configuration options to packages (see below).

In pseudo-code, the "app.json" and package.json contents are merged like so:

var manifest;  // from above

manifest.packages = manifest.packages || {};

var js = [], css = [];

// Expand required packages and sort in dependency order
expandAndSort(manifest.requires).forEach(function (name) {
    var pkg = load('packages/' + name + '/package.json');

    js = js.concat(pkg.js);
    css = css.concat(pkg.css);
    manifest.packages[name] = merge(pkg, manifest.packages[name]);
});

manifest.css.splice(0, 0, css);

var k = isExtJS ? 0 : manifest.js.indexOf('sencha-touch??.js');
manifest.js.splice(k, 0, js);

This produces an Ext.manifest that might look like this:

{
    "name": "MyApp",
    "packages": {
        "ext": {
            "type": "framework",
            "version": "5.0.1.1255"
        },
        "ext-theme-neptune": {
            "type": "theme",
            "version": "5.0.1.1255"
        },
        ...
    },
    "theme": "ext-theme-neptune",
    "js": [{
        "path": "app.js"
    }],
    "css": [{
        "path": "app.css"
    }],
}

The result of this merging means that package "foo" can provide some global options in its package.json (for example, "bar") and set its default value. Any application that uses the foo package can configure this option like so in "app.json":

"packages": {
    "foo": {
        "bar": 42
    }
}

The package retrieves this value like so:

console.log('bar: ' + Ext.manifest.packages.foo.bar);

Load Order

One of the major differences between loading your application in development and from a build is the order in which the individual files are presented to the browser. In previous releases, your app.js file was very nearly the first file processed by the browser. As its requirements were stated, more files were loaded and their requirements discovered and so on.

In a build, however, this order is reversed. Your app.js file will be almost always the very last file in the build output. This can easily lead to situations where code works in development but fails in production - clearly an undesirable outcome.

With Ext JS 5, the load order that will be used for the build is added to the manifest and used to load files in that same order. While this makes the manifest considerably larger, it is only used during development.

Loading The Manifest

The Microloader will load your application as it is described in "app.json" and passed along in Ext.manifest. To do this, the Microloader must first load the manifest. There are three basic ways to accomplish this.

Embedded Manifest

For typical applications there is a single theme, locale and framework selection and that results in a single manifest. This manifest can be placed in the output markup file to optimize download time.

To enable this option, add the following to "app.json":

"output": {
    "manifest": {
        "embed": true
    }
}

This setting will embed the manifest and the Microloader in the markup file.

Named Manifest

If you use build profiles, embedding the manifest is not an option. Instead the Microloader can request the manifest at load time given a name. By default, the generated "app.json" file is placed in the same folder as the markup file and that is the default manifest name. To specify a different name, you can do this:

<script type="text/javascript">
    var Ext = Ext || {};
    Ext.manifest = 'foo';  // loads "./foo.json" relative to your page
</script>

This approach is a useful way to manage build profiles on the server side by generating the name rather than hard-coding it.

Dynamic Manifest

There are times when you may want to select a build profile client-side. To simplify this, the Microloader defines a hook method called “Ext.beforeLoad”. If you define this method like the following, you can control the name or content of “Ext.manifest” prior to the Microloader processing it while leveraging its platform detection.

<script type="text/javascript">
    var Ext = Ext || {};
    Ext.beforeLoad = function (tags) {
        var theme = location.href.match(/theme=([\w-]+)/),
            locale = location.href.match(/locale=([\w-]+)/);

        theme  = (theme && theme[1]) || 'crisp';
        locale = (locale && locale[1]) || 'en';

        Ext.manifest = theme + "-" + locale;
    };
</script>

The above is taken from the Ext JS 5 Kitchen Sink example. That example is built in several themes and 2 locales (English “en” and Hebrew “he”). By providing this method the build profile name is changed to a value like “crisp-en” which instructs the Microloader to load the “crisp-en.json” manifest as opposed to "app.json".

The build profile selection process can be whatever is needed by your application. A server-side framework might chose to make this selection as the page is rendered. This could be based on cookies, or other personal data. In the above case, it is based purely on the URL.

Platform Detection / Responsiveness

Often the device or browser is a key selection criteria, so the Microloader passes an object called “tags” to beforeLoad. This object contains as properties the various platform tags it has detected. The set of all tags are these:

• phone
• tablet
• desktop
• touch
• ios
• android
• blackberry
• safari
• chrome
• ie10
• windows
• tizen
• firefox

The beforeLoad method can use these tags or even modify them. This object is subsequently used to control filtering of assets (js or css items described in the manifest) as well as run-time config values set by platformConfig. This hook then allows you to control what these filters will match. Modifying the tags is, however, primarily intended for adding new tags that have meaning to your application. Custom tags should be prefixed by “ux-”. Sencha provided tags will not begin with this prefix.

Tags specified by the manifest

The manifest also provides a "tags" property for setting the available tags. This prpoerty may be either an array of strings

"tags": ["ios", "phone", "fashion"]

or as an object literal, keyed by tag name, where the value will be the value of that tag.

"tags": {
    "ios": true,
    "phone": true,
    "desktop": false,
    "fashion": true
}

When supplied, this tags will take priority over autodetected values. Since these values are supplied by the manifest, they will not be available to the "beforeLoad" method, and will overwrite any updates to the tags made by that method in the event of a tag name collision.