Ext JS 4.1.3 Sencha Docs

Multi-page and Mixed Apps

Large Application Alternatives

Workspaces in Sencha Cmd describes the new workspace support in Sencha Cmd that is designed specifically to facilitate large, multi-page applications.

This guide picks up where that guide left off and describes how to use lower-level commands to perform some advanced build operations. These are primarily focused on creating two scripts per page instead of the typical one ("all-classes.js") to improve caching as users navigate between pages. While there are many variations on the ideas discussed here that could be similarly implemented, this guide describes two approaches:

  • Putting all code common to multiple pages in a "common.js" file.
  • Putting all framework code needed by any page in a "common.js" file.

Further, since we are using lower-level commands in this guide, we use a custom application folder structure to show how Sencha Cmd can be used to fit your own specific choices for code organization.

This guide focuses primarily on Ext JS applications. Support for these techniques will be available for Sencha Touch in future releases.

Custom Structure Application

To consider applications that do not have a workspace, lets assume that we have a two-page application with the following folder structure:

build/              # The folder where build output is placed.
common/             # Things common to all pages of the application.
    src/            # Shared JavaScript code for all pages.
ext/                # The framework distribution.
    src/            # The framework source tree.
page1/
    index.php       # The markup file for page 1.
    src/            # Folder containing JavaScript code unique to page 1.
page2/
    index.php       # The markup file for page 2.
    src/            # Folder containing JavaScript code unique to page 2.

This example could be extended to cover many more pages, which would make it harder to follow the example commands. There are some features that only apply to applications with three or more pages so we will expand the example to illustrate that usage.

Caching Shared Code

If users of the application tend to visit more than one page, it may be helpful to split up the code such that common code is in a shared file while page-specific code is isolated to a second script file.

In set operations terminology this is called a set "intersection". That is to say, we want to take the files in the intersection of the two sets of files needed by each page and generate a file with just those classes.

The following command will do precisely that:

sencha compile -classpath=ext/src,common/src,page1/src,page2/src \
    page -name=page1 -in page1/index.php -out build/page1/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page2/index.php -out build/page2/index.php \
         -scripts ../common.js and \
    intersect -set page1,page2 and \
    save common and \
    concat -yui build/common.js and \
    restore page1 and \
    exclude -set common and \
    concat -yui build/page1/all-classes.js and \
    restore page2 and \
    exclude -set common and \
    concat -yui build/page2/all-classes.js

Let's look closely at what each part of this command accomplishes.

The first thing is to create the compile context and tell it the classpath for all of the source code folders:

sencha compile -classpath=ext/src,common/src,page1/src,page2/src \

Then we use two page commands to include the source from each page as well as generate the appropriate output pages in the build folder. Each page command produces a set of files containing exactly the files needed by that page. These sets are given the names page1 and page2. Finally, each generated output page will get an extra script tag whose src attribute is "../common.js".

    page -name=page1 -in page1/index.php -out build/page1/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page2/index.php -out build/page2/index.php \
         -scripts ../common.js and \

Now that all of the files needed by each page are recorded in two sets, we use intersect to determine the files needed by both pages. Only these files will be included in the current set.

    intersect -set page1,page2 and \

We use save to record the current set of files (the result of the intersection). These are the files we will put in "common.js". The name for the new set is common.

    save common and \

Then we use concat to combine the files and produce "build/common.js" (also compressing the file using `-yui' to engage the YUI Compressor).

    concat -yui build/common.js and \

Now we need to produce the "all-classes.js" for each page, so we use restore to make the current set equal to the previously saved set for the page:

    restore page1 and \

Then we remove from this set all of the files that we just generated in "common.js":

    exclude -set common and \

And then use concat again to produce "all-classes.js" for the page:

    concat -yui build/page1/all-classes.js and \

We repeat the last few steps again for page2:

    restore page2 and \
    exclude -set common and \
    concat -yui build/page2/all-classes.js

Alternative Strategy - Sharing A Framework Subset

A different way to partition shared code would be to isolate all of the framework code needed by the application and produce a file similar to "ext-all.js" but only containing those classes needed by some part of the application. This approach might load more of the framework than needed by each page, but the benefits of the browser cache could easily make up for this increase.

The following command contains only a slight adjustment to the above:

sencha compile -classpath=ext/src,common/src,page1/src,page2/src \
    page -name=page1 -in page1/index.php -out build/page1/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page2/index.php -out build/page2/index.php \
         -scripts ../common.js and \
    union -set page1,page2 and \
    exclude -not -namespace Ext and \
    save common and \
    concat -yui build/common.js and \
    restore page1 and \
    exclude -set common and \
    concat -yui build/page1/all-classes.js and \
    restore page2 and \
    exclude -set common and \
    concat -yui build/page2/all-classes.js

The difference between this command and the previous command is in how the common set is calculated.

    union -set page1,page2 and \
    exclude -not -namespace Ext and \

In this case the union command is used to include all files used by either page. This set is then reduced using the exclude command to remove all classes that are not in the Ext namespace. This will leave only the framework code that is needed by either page in the current set.

The remainder of the command above and below these two lines is the same as before.

Beyond Two Pages

Applications with more than two pages can be managed as an extension of a two-page application as discussed above. Just add extra page commands (one for each page) and extra set operations to produce the appropriate "all-classes.js" file for each page.

There are interesting possibilities for code sharing among the multiple pages. For example, let's consider a five-page application structured in the same basic way.

It may be that the common set of files produced by the intersection of all pages is quite small. This will force code that is not used by all pages out of "common.js" and into an "all-classes.js" file for each page. One strategy for dealing with this is to manually divide up similar pages and treat the application as multiple, independent, multipage applications.

Another, simpler, way would be to use a "fuzzy intersection," that is an operation the selects all classes used by a specified minimum number of pages. Here's an example:

sencha compile -classpath=ext/src,common/src,page1/src,page2/src \
    page -name=page1 -in page1/index.php -out build/page1/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page2/index.php -out build/page2/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page3/index.php -out build/page3/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page4/index.php -out build/page4/index.php \
         -scripts ../common.js and \
    page -name=page2 -in page5/index.php -out build/page5/index.php \
         -scripts ../common.js and \
    intersect -min=3 -set page1,page2,page3,page4,page5 and \
    save common and \
    concat -yui build/common.js and \
    restore page1 and \
    exclude -set common and \
    concat -yui build/page1/all-classes.js and \
    restore page2 and \
    exclude -set common and \
    concat -yui build/page2/all-classes.js and \
    restore page3 and \
    exclude -set common and \
    concat -yui build/page3/all-classes.js and \
    restore page4 and \
    exclude -set common and \
    concat -yui build/page4/all-classes.js and \
    restore page5 and \
    exclude -set common and \
    concat -yui build/page5/all-classes.js

Other than the three additional page commands as well as three stanzas of restore, exclude and concat, the above command only changed from the original intersection in this one way:

    intersect -min=3 -set page1,page2,page3,page4,page5 and \

The -min switch activated the fuzzy intersection method. By default, intersect selects classes used by 100% of the specified sets or, in this case, all 5 sets. With -min you can override this threshold. By specifying -min=3 we are saying to include in the current set any class used by at least 3 sets (or 60%).