Ext.define('Validations.model.Person', {
    extend: 'Ext.data.Model',
    fields: [
        {name:"name", type:'string'},
        {name:"age", type:"int"},
        {name:"hobby", type:"string"}
    ]
})

Also, assume we have a form defined like so:

Ext.define('Validations.view.people.Form', {
    extend: 'Ext.form.Panel',
    alias: 'widget.peopleform',
    bodyPadding: 10,
    border: false,
    initComponent: function() {
        var me = this;
        Ext.applyIf(me, {
            defaults: {
                width: 250,
                labelWidth: 70
            },
            items: [
                {
                    xtype: 'textfield',
                    name: 'name',
                    id: 'name',
                    fieldLabel: 'Name'
                },
                {
                    xtype: 'numberfield',
                    name: 'age',
                    id: 'age',
                    fieldLabel: 'Age',
                    value: 20
                },
                {
                    xtype: 'textfield',
                    name: 'hobby',
                    id: 'hobby',
                    fieldLabel: 'Hobby'
                }
            ]
        });
        me.callParent(arguments);
    }
})

NOTE: Notice that the “name” properties of each form field maps 1:1 with the “name” properties in my Model.

Now, let’s say that we want to edit a Model instance. We could, of course, manually set the value of each form field to that of the corresponding field in the Model. However, this is clunky and unnecessary, given that the form itself has a method for doing this automatically. Consider the following:

// get first model instance in store
 myrecord = somestore.getAt(0)
 // load form with data from selected model instance
 myform.loadRecord(myrecord)

Pretty simple, right? When calling the loadRecord() method on the form, any field in the form whose name value matches the name definition in the specified Model will be loaded with the data of that particular field.

Try it out. Open the demo, and double-click on any record in the grid. On the itemdblclick event of the grid, the form’s loadRecord() method is invoked, and the Model data corresponding to the clicked row in the grid is applied to the form’s fields

Validation, Validation, Validation

So that’s pretty easy. But of course, when dealing with data–whether on the Model or in a form–you’re going to want to validate it to make sure that you have the data you’re expecting, and that the data is in the right format.

In ExtJS, there are a few different ways you can validate Model data.

First, you can apply validations directly to the model itself. For example, let’s add in a few to the Model already setup:

Ext.define('Validations.model.Person', {
    extend: 'Ext.data.Model',
    fields: [
        {name:"name", type:'string'},
        {name:"age", type:"int"},
        {name:"hobby", type:"string"}
    ],
    ,
    validations: [
        {type: 'presence', field: 'name', message: 'You have to enter a name, silly'},
        {type: 'presence', field: 'age', message: 'You must specify an age'},
        {type: 'presence', field: 'hobby', message: 'You must enter a hobby'},
        {type: 'length', field: 'hobby', min:5, message: 'You must specify a hobby with more than 4 characters'}
    ]
})

In this example, I’ve applied a “presence” validation to each field, which requires that each field has a value, as well as a “length” validation to the “hobby” field. When calling the Model’s validate() method, the instance’s current data will be run through the validations.

The second, albeit indirect, way to validate the Model is to apply validations to the form fields themselves, such as defining properties like allowBlank (e.g., “presence”), specifying a custom vType for the field, using a regex, etc.

While both of these approaches are great, they are not particularly related. For example, if we have NO validations whatsoever on the form, we could submit perfectly valid Form data, but this data may yet trigger validations when the Model is validated. By default, the form doesn’t care about the Model-level validations, and will only trigger Form-level validations that have been defined.

Applying Model Validation to Form Fields

While this disconnect is certainly understandable, I thought it would be cool if both validations could be supported when the form is being validated. Here’s a short list of my requirements:

• Model validations should be enforced at a field by field level (e.g., if there are two validations for “name”, these should both be enforced on the “name” field in the form)
• Both Model and Form field validations should be respected
• Both Model and Form field validations should be communicated to the user

So how to do this? While there are probably a dozen ways to accomplish this goal, the approach I took was to simply override Ext.form.Basic and Ext.form.field.Base.

The first step is to make the form aware of Model validations. Since we really only care about this when the Model data is loaded to the form via loadRecord(), we can start by overriding this method like so:

Ext.override(Ext.form.Basic, {
    loadRecord: function(record) {
        this._record = record;
        this.setModelValidations(record.validations);
        return this.setValues(record.data);
    },
    setModelValidations: function(validations) {
        var fields = this.getFields(), i;
        for(i=0;i<validations.length;i++) {
            if(fields.map[validations[i].field]) {
                fields.map[validations[i].field].setModelFieldValidation(validations[i])
            }
        }
    }
})

When loadRecord() is invoked, we pass the record to a new custom method, setModelValidations(). This custom method will iterate over the validations object of the specified Model, and will invoke the setModelFieldValidation() method of any form field it finds whose mapping matches that of the Model validation.

The next override is on the base definition for form fields, and looks like so:

Ext.override(Ext.form.field.Base, {
    setModelFieldValidation: function(validation) {
        this.modelValidations = Ext.isArray(this.modelValidations) ? this.modelValidations : [];
        this.modelValidations.push(validation);
    },
    getModelErrors: function(value) {
        var errors      = Ext.create('Ext.data.Errors'),
            validations = this.modelValidations,
            validators  = Ext.data.validations,
            length, validation, field, valid, type, i;

        if (validations) {
            length = validations.length;

            for (i = 0; i < length; i++) {
                validation = validations[i];
                field = validation.field || validation.name;
                type  = validation.type;
                valid = validators[type](validation, value);

                if (!valid) {
                    errors.add({
                        field  : field,
                        message: validation.message || validators[type + 'Message']
                    });
                }
            }
        }
        return errors;
    },
    validateValue: function(value) {
        var me = this,
            errors = me.getErrors(value),
            modelErrors = me.getModelErrors(value),
            isValid = Ext.isEmpty(errors) && modelErrors.isValid();
        if (!me.preventMark) {
            if (isValid) {
                me.clearInvalid();
            }
            else {
                if(!modelErrors.isValid()) { modelErrors.each(function() { errors.push(this.message); }) }
                me.markInvalid(errors);
            }
        }
        return isValid;
    }
})

There’s a lot going on here, so let’s go method by method.

setModelFieldValidation(): This is method that is called from the Form’s setModelValidations() method, and it simply adds a new property to the instance of the form field (modelValidations). This modelValidations is an array which will store any Model-level validations which have been configured for the Model field which matches this form field’s “name”.

getModelErrors(): This method is almost identical to the Model’s getErrors() method. The primary difference is that instead of iterating over every validation defined for the Model, this method only iterates over the Model validations which have been assigned to this form field (via setModelFieldValidations()).

validateValue(): This is an override of the field’s existing validateValue() method, which is invoked everything a validation occurs. The only additions are to add the Model validation to the check for whether the form “isValid”, as well as a short section to append the model validation error messages to the main “errors” array (which is ultimately used for communicating the form’s validation errors to the user).

Demo and Source

If you’d like to see this in action, check out the demo. If you’d like to see the full source for this mini-app, grab it from GitHub.

Wrapping Up

In all honesty, I’m not sure how practical this approach actually is, or whether you’d actually want to forge this relationship between the form and model validations. But regardless of the practicality, I think it does, at the very least, demonstrate precisely how stupid simple it is to extend ExtJS to do pretty much whatever you want it to do. And notwithstanding the usefulness of this particular example, this extensibility is precisely why I love this framework.

When I saw the news about the release, I have to say I was a bit hesitant to look much further. I’ve tried Sencha Designer several times in the past, and I’ve been somewhat disappointed with it. Sure, it was great for laying out apps, but when you actually needed to *code*, it was lackluster at best. But even worse, I found it to be very buggy; it would crash at random times, and overall I found the process of trying to mockup an app to be more frustrating than anything else.

So initially, I wasn’t planning on even trying out the newest iteration. But then I noticed that one of the biggest additions to the product is  support for creating a full ExtJS or Touch app–not just the UI. I felt I had to take a closer look, and I’m glad I did.

UI

Out of the box, Architect 2 is worlds better than its previous iterations. The interface is slick and responsive, and the way the UI is organized makes the process of laying out and configuring components feel much more intuitive. One especially nice feature is that in the “Property” panel, you can toggle between commonly used configurations and the comprehensive list. Additionally, the configuration options are nicely grouped by inheritance, so you know precisely where your configs are being applied.

Application Flow

The coolest part of Architect 2 (to me) is that you can now *really* build applications with it. If you drink the MVC architecture Kool-Aid (and you should!), Architect 2 makes it very simple to build full-on applications.

For example, you can very simply choose to add controllers to your app. Within the controllers, you can customize handlers and custom methods to take care of the all of the business logic of your application.

Best Practices

But perhaps the best part of Architect 2 is that in the course of adding components, wiring up event handlers, and just fleshing out your app, you can instantly switch to “Code” view to see how the entire app is getting constructed behind the scenes. This gives a much welcome insight into “best practices” for developing ExtJS and Touch apps within the MVC architecture–a much desired feature that many devs have been begging for for quite a while.

I was happy to see that my methodology that was about 95% on point; however, the differences that I’ve noticed while reviewing the code have filled in some gaps in my understanding, which will simply make building ExtJS and Touch apps that much more fun

So…Will I Buy It?

At $399, the price tag for Sencha Architect 2 initially feels a little steep. Personally, I would not have paid that much for previous versions, purely based on my lackluster experiences during the trials. However, given how much more solid Architect 2 feels, and based on the fact that it is now geared toward full soup-to-nuts app development, I’ll have to seriously consider it.

At some point, however, you’ll need to retrieve data from your Store in a query-like manner. That is, instead of looking up a record by a known ID or position within the store, you may need to find one or more records based on a search term, a category, or whatever else is required by your app.

Of course, as with everything else, ExtJS makes this pretty simple. Let’s suppose that we have the following Model:

Ext.define("MyApp.model.Bookmark", {
     extend: "Ext.data.Model",
     idProperty: "id",
     fields: [
         {name: "id", type: "int"},
         {name: "target", type: "string"},
         {name: "title", type: "string"},
         {name: "category", type: "string"},
         {name: "created", type: "date"}
     ]
});

Nothing to crazy here. Just a simple model with some standard kinds of fields for storing data, in this case, “bookmarks.” Now, let’s define our data store:

Ext.define("MyApp.store.Bookmarks", {
    extend: "Ext.data.Store",
    model: "MyApp.model.Bookmark",
    autoLoad: true,
    storeId: 'bookmarks',
    proxy: {
        type: 'localstorage',
        id  : 'myapp-bookmarks'
    }
});

As with the model, this is very straightforward. We’ve configured a simple store which happens to have a localStorage proxy (change it if you want–ExtJS doesn’t care!).

Simple Data Lookup

Ok, so now that we’re up and running with our model and store, let’s pretend we’ve created a simple app to save bookmarks into our data store. As we’re plugging along, we find that we need to put some kind of tollgate in place to prevent the same bookmark from being entered over and over: after all, having one bookmark to Charlie the Unicorn 2 is certainly enough!

How can we prevent this? In our addBookmark() method, we can do a simple lookup on our data store to see if a bookmark with the same title already exists. This might look something like so:

function addBookmark(target,title,category) {
    var store = Ext.data.StoreManager.lookup('bookmarks');
    var match = store.find('title','title');
    if(match == -1) {
        ...add the bookmark
    }
}

In this simple example, we use the store’s find() method to search through the store’s records. The find() method takes two required arguments–the column to search, and the value to be used in the search–but has more flexibility for case-sensitivity, partial matches, etc. Based on whether the index of a record in our store is returned, we decide whether or not to add the new data to our store.

Of course, if we don’t care about the index of the record and simply want to get a matched record, we could use findRecord() instead. It functions in the same way, but returns a model instance instead of a record index.

More Complex Data Lookup

The store’s find() and findRecord() methods are great if you only need to find matches based on a single data column. What if you need to match on more than one column, though? For example, let’s say that we want to be able to store bookmarks with the same title as long as they belong to a different category. Obviously, our previous method will not work, since the method will prevent insertions of records with already-existent titles. Nope, we need something a bit more robust. Thankfully, ExtJS data stores have just the ticket: findBy().

The findBy() method’s power lies in the fact that you can specify a custom function that will be executed against every record in the data store. Within this custom function, you can do any manner of checks on the entire data record (not just the value of one column). If the conditions you specify succeed, the method will return the index of the first matching record.

So here’s what that might look like for our scenario of checking for the uniqueness of both bookmark title AND category:

function addBookmark(target,title,category) {
    var store = Ext.data.StoreManager.lookup('bookmarks');
    // custom function for finding record with complex criteria
    var match = store.findBy(function(record,id) {
        if(record.get('target')==target && record.get('category')==category) {
            return true;
        }
    });
    if(match == -1) {
        ...add the bookmark
    }
}

As you can see, the custom function is passed two arguments: the model instance of the currently-evaluated record, and the id of the record. Since we want to check to make sure that the combination of bookmark title and bookmark category are unique, we can simply check the “title” and “category” values of the would-be-bookmark against each model in our data store. If no match is found, we know the record is unique and we can add it to the data store. Magical

Wrapping Up

Obviously, the example provided above is very simple; however, I hope it shows just how easy it is to not only query data from a data store, but moreover to create custom functions to apply more complex query logic to the data in your stores.

A big part of the appeal of ExtJS data Models is their flexibility. While some data “plugins” in other JS frameworks certainly allow you mimic some of the behaviors of a data model, ExtJS’ data Model wins hands down because of its extreme flexibility. With a ExtJS Model, you can quickly and easily create powerful definitions of data objects (fields, data types, associations, validations, etc.) in your application. These models can then in turn be used to craft a data Store, which can themselves be plugged into many of ExtJS’ data components (DataView, Grid, Chart). What you end up with is a super-powerful, deeply-data-driven application in a ridiculously small number of lines of code.

Of course, the perfect complement to the simplicity and grace of ExtJS’s data Model is to “feed” it using ColdFusion. Below, I’ll outline how to retrieve data from CF, as well an extremely easy way (there are obviously more!) to format data from a ColdFusion query directly into an ExtJS data Model.

Note: For these examples, I am using ColdFusion 9 and ExtJS 4.0.7

ExtJS Models

As mentioned above, the ExtJS data Model allows you to create pretty powerful–and flexible–definitions for data objects in your application. The beautiful part about this is that you can create a Model out of pretty much any data structure that is presented to your application. This allows you to spend your time making your JavaScript application work the way you want it to, without being enslaved to a particular requirement for data formatting (or type, for that matter). So whether you’re consuming XML, JSON, JSONP, etc., the ExtJS Model is flexible and configurable enough to normalize the incoming data structure into what you ultimately want (and need) your data objects to be for your application.

ColdFusion Query to JSON

How does this relate to ColdFusion? Well, let’s say that you have an existing, remotely-accessible component that returns a query result. In ColdFusion 8 and above, you can specify the “returnformat=json” argument in your method invocation, and ColdFusion wil serialize the query object into a JSON-formatted string, and return it to your JavaScript application.

remote any function getqueryarrays() {
    fauxquery = querynew('id,name,age');
    queryaddrow(fauxquery,4);
    querysetcell(fauxquery,"id","1",1);
    querysetcell(fauxquery,"name","Joel",1);
    querysetcell(fauxquery,"age","31",1);
    querysetcell(fauxquery,"id","2",2);
    querysetcell(fauxquery,"name","Jason",2);
    querysetcell(fauxquery,"age","31",2);
    querysetcell(fauxquery,"id","3",3);
    querysetcell(fauxquery,"name","Godzilla",3);
    querysetcell(fauxquery,"age","100000",3);
    querysetcell(fauxquery,"id","4",4);
    querysetcell(fauxquery,"name","Batman",4);
    querysetcell(fauxquery,"age","0",4);
    return fauxquery;
}

The one downside of this approach is that you don’t have a lot of control over how ColdFusion formats the JSON that it returns. It looks something like this:

As you can see, ColdFusion’s JSON-encoding has done a few things:

• To represent the data, it has created two arrays: one for the column definitions, and one for the data. I would prefer an array of objects, but this is CF’s default behavior…
• Perhaps worse, all of the “keys” have been uppercased, regardless of the original case of the columns

In other JS libraries, you might have to do some pre-processing of the JSON in order to get the data into something more like an array of structures, and/or even re-work the casing on the keys (or modify the requirements in your app to account for the casing). This all, of course, assumes that you have control over the source generating the JSON. Good luck if you don’t!

Making the Model

With ExtJS’s data Model, the JSON formatting–and even the ultimate structure of the source data–just doesn’t matter. The Model is flexible enough to adapt, and you can easily configure it to consume just about any incoming structure/format that you can think of.

Here’s what we can do for our example data:

Ext.define('Person', {
    extend: 'Ext.data.Model',
    fields: [
        {name:"ID", type:'int'},
        {name:"NAME", type:"string"},
        {name:"AGE", type:"number"}
    ],
    proxy: {
        type: 'ajax',
        url: 'remote.cfc?method=getqueryarrays&returnformat=json',
        reader: {
             type: 'array',
             root: 'DATA'
        }
    }
})

Seriously, it’s that simple. We just tell the Model that we’d like to define a data object with a certain number of fields, and it’s smart enough to automatically find and create an association with the incoming data. Here’s how we did it:

• The “fields” config option allows us to tell ExtJS what we want our data object to look like. Notice that in this example, the “name” attribute is upper-case. This matches the upper-case keys being returned from CF.
• The “proxy” config allows us to tell the Model how we’ll retrieve the data that will build the Model. In this case, we’re using the AjaxProxy.
• In the proxy, we’ve also defined a “reader.” This is where the flexibility really comes into play. For the reader type, “array” has been specified. This tells ExtJS, at the very least, that our data is in an array format. Next, we’ve specified a “root” of “DATA.” This tell ExtJS that the “DATA” array will contain the values for the field definitions that we’ve already created.

And with that, our Model is complete. We can now hook this up to a data store, and we’ll be able to use the store on any number of data-driven ExtJS components.

A Bit of Tweaking

Even though that’s pretty simple, we’re still a bit tied to the formatting that ColdFusion has returned–after all, we used the uppercase column names in our field definitions. But what if we don’t want uppercase field definitions in our Model?

While we can certainly leave it as is, the ExtJS Model allows us to alternatively map field definitions using the “mapping” attribute. For the ArrayReader, the mapping can be the position in the data structure, rather than the explicit field name. So with just a slight modification, we can easily map our fields as before, but also create arbitrary field names in our Model field definitions:

Ext.define('Person', {   
     extend: 'Ext.data.Model',   
     fields: [       
        {name:"theid", type:'int',mapping:0},       
        {name:"myname", type:"string",mapping:1},       
        {name:"myage", type:"number",mapping:2}   
     ]
})

Wrapping Up

As we’ve, ExtJS’s data Model is an extremely powerful and versatile way of creating robust data objects for JavaScript applications. Not only do they serve as a great foundation for ExtJS’ data-driven components, but they (perhaps more importantly) are flexible enough to suit just about any requirement for incoming data. So instead of having to craft your application around the arbitrary data definitions which come from systems over which you may not have any control, you can easily leverage ExtJS data Models to take back the reins and define data objects based on the needs of your application alone. Pretty awesome

• Filtering on a property (e.g., “field”)
• Filtering with a custom function

Ext.define('Person', {
    extend: 'Ext.data.Model',
    idProperty: 'id',
    fields: [
         {'firstname', type:'string'},
         {'middlename', type: 'string'},
         {'lastname', type: 'string'}
    ]
});

Ext.create('Ext.data.Store', {
    autoLoad: true,
    model: 'Person',
    storeId: 'PersonStore',
    proxy: {
         type: 'ajax',
         url: 'myurl.json',
         reader: {
              type: 'json',
              root: 'people'
         }
    }
});

var store = Ext.data.StoreManager.lookup('PersonStore');
var peoplefilter = new Ext.util.Filter({
     property: 'lastname',
     value: 'son',
     anyMatch: true,
     caseSensitive: false,
     root: 'data'
 });
 store.filter(peoplefilter);

var store = Ext.data.StoreManager.lookup('PersonStore');
var peoplefilter = new Ext.util.Filter({
    filterFn: function(item) {
        return item.data.lastname.substr(0, 2)=='Mc' ? true : false
    }
});

While a little different than using the property method, filterFn is very easy to use. You can simply do custom processing on each item, and determine (via returning true or false) whether the record should be part of the filtered set or not. Pretty simple.

Passing Multiple Fields to the Property Filter

Now consider this: you have a larger set of fields in your model, and you want to do something of a wild card search against a number of fields in your model. How would you accomplish this?

Unfortunately, the property filter does not out-of-the-box support passing multiple fields. True enough, you could add 1 filter for each field, but this would leave you with something of an X AND Y AND Z result, instead of the desired X OR Y OR Z result. You could, of course, figure all of this out in a custom filter function. Here’s an example of that:

var searchfilter = new Ext.util.Filter({
     filterFn: function(item){
         var searchtest,fnmatch,mnmatch,lnmatch;
         var escapere = Ext.String.escapeRegex;
         searchtest = new RegExp(escapere(search), 'i');
         // check match on first name
         fnmatch = searchtest.test(item.data.firstname);
         // check match on middelname
         mnmatch = searchtest.test(item.data.middlename);
         // check match on name
         lnmatch = searchtest.test(item.data.lastname);
         // if any of the fields matched, return true, which will include  record in filtered set
         if(fnmatch || mnmatch || lnmatch) {
             return true;
         }
         // otherwise, return false, which will exclude record from filtered set
         else {
              return false;
         }
    }
})

While not particularly pretty, it works. The main problem is that it more or less duplicates what the property filter is already doing, just a in a bit clunkier way. So instead of doing this, a better approach might be to override the default implementation of Ext.util.Filter. Instead of only allowing for a single property to be evaluated, we’ll beef it up a bit to accept either an array or string of properties.

Ext.override(Ext.util.Filter,{
    createFilterFn: function() {
        var me       = this,
            matcher  = me.createValueMatcher(),
            property = !Ext.isArray(me.property) ? me.property.split(',') : me.property
        return function(item) {
            var hasmatch = false;
            for(var i=0;i<property.length;i++) {
                if(matcher.test(me.getRoot.call(me, item)[property[i]])) {
                    hasmatch=true;
                    break;
                }
            }
            return matcher === null ? value === null : hasmatch;
       };
    }
})

In fact, the last post that I wrote was meant to be this one. However, as I worked through the process of creating a custom UI, I found that the setup of Compass compilation for ExtJS 4 might have some *gotchas* that could trip people up (like me), so I decided to start from the beginning, get a solid foundation, and now move on to the actual fun stuff.

Ok? Good? On we go!

What We’re Going to Make

In this walkthrough, we’re going to try to accomplish a few things.

Objective #1: I want to show how it’s perfectly possible (maybe preferable?) to mix custom UIs with the stylesheets/images/etc. of the “default” ExtJS 4 theme. In this particular example, we’re going to create a custom Ext.ProgressBar UI.

Objective #2: We’re also going to create a custom stylesheet that produces only the minimum of what we need for the “application” we’re going to build. So instead of having a monster ext-all.css file that includes ALL the styles for the entire library, we’re going to pare down our final stylesheet to only the bare bones of what we need.

Objective #3: We’re going to use the SDK’s “slice” tool to create “backup” images for old, crappy browsers that don’t support CSS3 goodness like background gradients and borde-radius.

BTW, I want to be completely up front about this. Nothing I’m doing here is “new” to me. The basic structure of what we’ll be doing is shamelessly stolen from the Theming Guide on Sencha’s website. I wanted to walk through the process, though, a bit more in depth with screenshots, code snippets, and real examples, just so any trip-ups can be explained and dealt with along the way.

Let’s Get Started

In what follows, I’ll be using the structure that we setup in the last post on this subject. Obviously, you can flex it to suit your needs; however, if you want to follow along step-by-step, be sure to take care of that first. If you’d like some source code, grab it on GitHub.

Before we start creating our custom UI, let’s build our “app.” First, let’s create an HTML file in the root of my project (playground). Now, let’s create a JavaScript file that will house our app’s code.

Here’s the JS code:

playground/js/progress.js

Ext.onReady(function(){
   var pb = Ext.create('Ext.ProgressBar', {
      margin: 50,ui:'default'
   });
   // Wait for 5 seconds, then update the status el (progress bar will auto-reset)
   pb.wait({
      interval: 500, //bar will move fast!
      duration: 50000,
      increment: 15,
      text: "Hi, I've got a custom UI...",
      scope: this,
      fn: function(){
         p.updateText('Done!');
      }
   });
   var pa = Ext.create("Ext.panel.Panel", {
      title: "I'm a regular 'default' UI Panel",
      width: 500,
      items: pb, // put the progressbar in our panel
      floating: true,
      renderTo: Ext.getBody(),
      closable: true
   })
})

Here’s the HTML file:

playground/progress.html

<html>
   <head>
      <title>Custom Progress Bar UI</title>
      <link rel="stylesheet" type="text/css" href="extjs/resources/css/ext-all.css">
      <script type="text/javascript" src="extjs/ext-all.js"></script>
      <script type="text/javascript" src="js/progress.js"></script>
   </head>
   <body></body>
</html>

Once you’ve got these set up, go ahead a open your file in the browser. You should see a fancy blue panel, which contains a fancy blue animated progress bar.

Now that we have something that’s working, let’s get down to styling the darn thing!

Ok, the first thing we’re going to do is to make a copy of our “my-ext-all.scss” file with the playground/extjs/resources/custom folder. Since we’re making a custom Ext.ProgressBar UI, I’m going to call this new file “progress.scss” (if you can’t tell, I’m a sucker for originality). Since our config.rb file was working as expected in our last walkthrough, it’s fine how it is; no need for us to mess with it anymore.

Now, open up progress.scss. At the very top, you’ll see a variable called $include-default. If it’s not already, set it to false. This tells the compiler to NOT include the entire all components in our final .css file. Also, setting this to false will allow us more granularly specify exactly what components we want to include (see Objective #2 above).

Moving on down the file, we’ll come to a section that has a list of all the components. It should look something like this:

@include extjs-boundlist;
@include extjs-button;
@include extjs-btn-group;
@include extjs-datepicker;
@include extjs-colorpicker;
@include extjs-menu;
@include extjs-grid;
@include extjs-form;
   @include extjs-form-field;
   @include extjs-form-fieldset;
   @include extjs-form-checkboxfield;
   @include extjs-form-checkboxgroup;
   @include extjs-form-triggerfield;
   @include extjs-form-htmleditor;
@include extjs-panel;
@include extjs-qtip;
@include extjs-slider;
@include extjs-progress;
@include extjs-toolbar;
@include extjs-window;
@include extjs-messagebox;
@include extjs-tabbar;
@include extjs-tab;
@include extjs-tree;
@include extjs-drawcomponent;
@include extjs-viewport;

If we leave this as is, the compiler is going to pull in all of the style rules for these components into our stylesheet. However, since we’re only using 2 of them (panel and progress bar), let’s get rid of the others.

The final list should look like this:

@include extjs-panel;
@include extjs-progress;

Awesome. Ok, the final line in our progress.scss file is the variable $relative-image-paths-for-uis, and is set to true. I’ll leave the note for you to read, but let’s leave its value as true.

Excellent. So these slight modifications, our progress.scss file looks like this:

// Unless you want to include all components, you must set $include-default to false
// IF you set this to true, you can also remove lines 10 to 38 of this file
$include-default: false;

@import 'compass';
@import 'ext4/default/all';

// You may remove any of the following modules that you
// do not use in order to create a smaller css file.
@include extjs-progress;
@include extjs-panel;

// This line changes the location of your images when creating UIs to be relative instead of within the ExtJS directory.
// You MUST set this to true/string value if you are creating new UIs + supporting legacy browsers.
// This only applies to new UIs. It does not apply to default component images (i.e. when changing $base-color)
// The value can either be true, in which case the image path will be "../images/"
// or a string, of where the path is
$relative-image-path-for-uis: true; // defaults to "../images/" when true

Before moving on, let’s go ahead an compile. I want to show that while we haven’t actually done any style customization yet, we can reduce the size of our CSS file by only including the components we need.

To compile, navigate to the custom folder and execute the compass compile command. Once this completes successfully, you should see a new CSS file in the playground/extjs/resources/css folder called progress.css.

Now go back to your progress.html file and change the stylesheet link to point to this new CSS file. Reload the page. If everything compiled correctly, you shouldn’t notice any difference. However, if you look at the progress.css file itself, you’ll notice that it’s quite a bit lighter than the full ext-all.css. Yay, we did it Objective #2 is complete!

Get on with the Custom UI Already!

Yeah, I know, we’ve gone through a lot of background stuff. However, I think it’s important. After all, you don’t want to spend a bunch of time creating custom UIs if your .scss file’s basic structure won’t compile correctly. So I strongly advocate verifying that each step is working correctly before moving on. But since we’ve already done that, let’s get to some styling!

As with creating a custom toolbar UI in Sencha Touch, a great place to start with creating our custom ProgressBar UI is to figure out what the “mixin” for the ProgressBar UI looks like, what arguments it takes, etc. This will allow us to fully maximize the customization that we make in our custom UI.

To inspect the ProgressBar UI mixin, we can simply navigate to the following:

• playground/extjs/resources/themes/stylesheets/ext4/default/widgets/_progress-bar.scss

On line 66, we’ll see the beginning of the extjs-progress-ui mixin. As you can see, this mixing accepts a number of arguments:

• label (the name of our custom UI)
• base-color (the foundation color for the UI)
• border-color
• background-color
• bar-background-color
• bar-background-gradient
• color-front (the color of text when the progress bar is not behind the text)
• color-back (the color of text when the progress bar is behind the text)

SImple enough. So let’s go back to our progress.scss file. After the @includes of the progress bar and panel, we can simply include our custom UI via the mixin. Here’s what my example looks like:

// set a custom progress base color to use in custom UI
$custom_pb_base_color: #Bfff00;
// here's the custom UI! 
@include extjs-progress-ui(
   'lime',
   $ui-base-color: $custom_pb_base_color,
   $ui-background-color: $progress-background-color,
   $ui-border-color: adjust-color($custom_pb_base_color, $hue: 0deg, $saturation: -3.08%,       $lightness: -23.725%),
   $ui-bar-background-color: adjust-color($custom_pb_base_color, $hue: 0deg, $saturation: -11.37%, $lightness: 7.451%),
   $ui-color-front: #333333,
   $ui-color-back: #333333
);

In the above, I’m creating a new progress bar UI called “lime.”  I set a custom variable for the base-color I want to use, and then simply specify the colors that I’d like for the background, border, text, etc.

Once everything looks good, it’s time to compile. Now that my newly compiled CSS file has the “lime” ui for my progress bar, all that’s left is to apply the UI to the progress bar itself:

In playground/js/progress.js:

var p = Ext.create('Ext.ProgressBar', {
      margin: 50,
      ui: 'lime'
   });

Once I save this, I should be able to reload my HTML page, and see a beautiful lime green progress bar inside of the default blue themed panel.

Using this approach, we could create as many UIs as we’d like, simply adding similar snippets to our progress.scss file and recompiling when ready to use them.

Ah, But We Couldn’t Get This Far WIthout a Gotcha…

Yes, indeed. Even though we’ve successfully compiled our custom CSS file with a custom progress bar UI, there’s one slight problem…depending on how you look at it, at least. What’s the issue?

Pop open your progress.css file that you just compiled. If you go all the way to the end of it, you’ll see this style rule:

.x-nlg .x-progress-lime .x-progress-bar{background:url(‘../themes/images/default/progress/progress-lime-bg.gif’) repeat-x}

Notice the background-image with “lime” in its name. Now, if you go to that path, guess what you’ll find? You’ll find a progress-default-bg-gif file, but no progress-lime-bg.gif file. What gives?

Well, because ExtJS is a thoroughly committed cross-browser framework, the theming tools automatically create style rules to accomodate old, crappy browsers like < IE9. So for example, since older versions of IE don’t support background gradients and rounded corners in pure CSS. ExtJS 4′s stylesheets achieve the same effect through background images.

Therefore, when you create a custom UI, the compilation automatically provides a rule to a theoretical image that you will create, and even handily names it according to your theme.

At this point, you might feel hoodwinked. After all, who wants to be bothered with creating images for background gradients and rounded corners? Not me, for sure. And if you really don’t care, just skip it. However, if you need to finish out this process, the SDK fortunately has one more tool that will make this ridiculously easy…and you’ll never have to open Photoshop, not even once.

Sencha Slicing Tool

Sorry, the Sencha Slicing Tool won’t give you finely shaved roast beef (I tried…). However, it will help you create the “helper” images to support your theme in outdated browsers. Here’s how we do it.

The first step is that you have to create a “manifest” of your UIs and the components to which they correspond. This basically allows the Slicing Tool to determine precisely which images it needs to create based on the type of component, the parameters of your UI, etc.

The manifest is a simple JSON file. I added mine into the playground/extjs/resources/custom folder, right along side my custom .scss file.

Here’s what the contents should look like:

Ext.onReady(function() {
   Ext.manifest = {
      widgets: [
         {
            xtype: 'widget.progressbar',
            ui   : 'lime'
         }
      ]
   };
});

Nothing to it. We simply define the component’s xtype, as well as the label of our custom UI that we’re going to use for it.

If you don’t know the “xtype” for the component you’re using, the easy way to find out is to look up the component in the documentation. Next to the class’ name, you’ll see the xtype.

Now for the fun part. Open up Terminal, and navigate to the root of your project.

Now, we need to execute the proper command with the appropriate arguments in order to allow the SDK to do its magic. First, here’s the full string I used. Assuming you have the same setup, it should work without issue:

sencha slice theme -d extjs -c extjs/resources/css/progress.css -o extjs/resources/themes/images/default -m extjs/resources/custom/manifest.json -v

Here’s the break down of this:

• slice theme : this the command for firing up the Slicing tool
• -d extjs : -d is for the directory of ExtJS. In our case, this is “extjs”, relative to our root directory
• -c …progress.css : -c is for the path to the CSS file which will be used in the Slicing process
• -o …default : the path to the main “theme” images folder. Since our CSS is already pointing to the “default” theme’s images folder, that’s where we want the new image(s) created by the Slicing tool to go
• -m …manifest.json: -m is for the path to the manifest.json file we created, which will tell the Slicing tool what kinds of images it needs to be creating, based on the custom UIs that we’ve specified
• -v : this simply instructs the program to give us a listing of the images that its creating

Alright, good to go. Let’s run the command. You should see something like the following:

As you’ll notice, the tool has generated a new image, and saved it to the location we specified. If we go back and look now, we’ll see that we now have two images in our folder.

…And with that, we’re done. Objective #3 complete!

Wrapping Up

If you’ve been following along this and the previous posts on theming ExtJS 4 and Sencha Touch, I hope you’re catching on to just how powerful the theming possibilities are. Sure, it can take a few minutes to get setup…but once you are set up, making remarkable changes to your application’s theme is dead simple. As we’ve only just scratched the surface of what can be done, I hope you’ll continue to explore.

Of course, ExtJS 4 has many of the same theming features, and a very similar workflow for creating and compiling custom themes. I’ve been playing around within some theming experiments, and learned some frustrating lessons along the way. So I thought I’d share, step-by-step, how I set up my environment for successfully compiling custom stylesheets for ExtJS 4…just in case you’re having issues

Getting Started

First off, I’m assuming you already have Ruby and the Compass/SASS gem installed. If you don’t take a few minutes to get that done. For instructions on how to do this, check out this walkthrough.

Before breezing on, take a few deep breaths. This is a critical step…if you don’t do it right, you have hours of frustration ahead of you.

I start off with a blank project (I’m using Eclipse, so insert whatever terminology you use for your IDE). First, I create the root folder for my project. I’m calling this one “playground.”

With my root folder created, the next step is to create a folder in our project to hold our ExtJS assets. I’m creating one that’s creatively named “extjs“. It doesn’t really matter what you name it…just make sure it’s something you can quickly and repetitively type (more on this later).

Now, we need to add the ExtJS 4 library to our project. If you just downloaded it, you should see something like following in the downloaded folder:

From this folder, copy, at a minimum, the following:

• ext-all-debug.js
• ext-all.js
• resources (the whole folder…the whole folder…the whole folder…do not fail to copy the whole folder!!)

Ok, you copied these, right? Double-check, and when you’re sure you have EVERYTHING you need, paste them into the “extjs” folder within your project.

Create a Custom Sassy Style Sheet

Excellent. If you followed along with the steps above, you’ve got a solid structure, not only for theming, but for creating your ExtJS 4 app in general. Here’s what my setup looks like:

Now for the fun stuff. While it’s certainly possible to create a full-on custom “theme” for your ExtJS 4 app, the best introduction to theming is creating a custom stylesheet that’s based on the default style structure that comes baked into ExtJS 4 by default. In this walkthrough, we’re actually not going to customize anything at all. Rather, we’re simply going to create our own “ext-all.css” file, just with a different name. The idea is that once we’ve got the process down, we can start customizing without the frustration of set up getting in our way.

So the first thing I like to do is to create a custom folder to store my .scss (sassy cascading style sheet) files. I do this at the following location:

• playground/extjs/resources/custom/

The next step I take is to copy the helpful .scss template that ExtJS 4 provides. You can find this at the following location:

• playground/extjs/resources/themes/templates/resources/sass

Take the “config.rb” and “my-ext-theme.scss” files, copy them, and paste them into the custom folder we just created. Rename the .scss file to something more relevant…I’m going to use “my-ext-all.scss“.

If you open up my-ext-all.scss, you’ll note that there are a few variables being set, and a lot of guidance notes. I’d encourage you to take a few moments to read through them to being gaining some understanding about what’s going on.

Let’s Compile

At this point, we’ve technically created a custom stylesheet for ExtJS 4. All that’s left is to compile. Check out Compass’ website if you have no idea what this means. If you don’t care what it means and just want to compile something, keep reading

To compile, first open up Terminal. Navigate to the “custom” folder that we created a few steps ago. Here’s what it looked like for me:

Once you’ve successfully navigated to this folder, simply type “compass compile.”

CRAP!  CRAP!  CRAP!  On your first compile, you’re probably going to see a lot of RED. You might see a bunch of warning messages to the effect that “Theme image not found…”

On the bright side, this process still created a stylesheet, in spite of the errors. If you look in playground/extjs/resources/css, you should see a new .css file with the same naming convention as our .scss file: “my-ext-all.css“. On the not-so-bright-side, if we actually try to use this, it will be broken. Most things will look pretty okay, but important images (tool icons, etc.) will be nowhere to be found. Not great.

Fortunately, this is *relatively* easy to fix.

In your project, navigate to the following file and open it:

• playground/extjs/resources/themes/lib/utils.rb

Two small changes here:

• Line 44(ish): Change relative_path = “../images/” to relative_path = “../themes/images/default” ***
• Line 62(ish): Replace images_path = File.join($ext_path,’resources’,'themes’,'images’,theme) with images_path = relative_path

With these changes made, go delete the “my-ext-all.css” file (NOT THE .SCSS FILE!). Now, recompile. You *shouldn’t* see any more RED, but simply see a confirmation that the compilation was successful and that your new CSS file was created.

*** Some walkthroughs will tell you to make a copy of your “themes/images/default” folder and place it in the root of “resources.” If you use this approach, you won’t need to make a copy.

Now, if we take a peek in our css folder (playground/extjs/resources/css), we should notice a new my-ext-all.css file. And if we hook it up to one of our pages, it should display the correct style AND successfully deliver the correct image paths for loading.

Wrapping Up

At first glance, it might appear that we didn’t really accomplish a whole lot. Honestly, in terms of “producing” things, we didn’t…we merely duplicated what was already a perfectly good stylesheet.

But from a more important perspective, we actually accomplished a lot. Now that we have things wired up correctly, we can really begin digging into customizing our custom style sheet. While we could have certainly jumped right into that from the beginning, believe me, it’s better to get things wired up first. There’s nothing more frustrating that staring at error messages for hours on end because you didn’t take the time to get things set up properly from the start.

So what about customization? In my next post, I’ll show just how easy it is to begin customizing our stylesheet now that we’ve got our compilation process worked out.

But the big problem with switching stylesheets in the old days was the incredible headache of trying to maintain X-number of iterations of stylesheets. Need to switch the hue of the link colors? Bust out the find and replace, and be sure you don’t miss any! Want to add a bit of padding to your navigation? Rinse, repeat, and puke. It was burdensome, and prone to many mistakes. I can remember advocating STRONGLY on many occasions to just “live with” the current styles, rather than facing down the daunting task of modifying 8 different stylesheets which may or may not have had any comments/guidance/formatting to them (ok, some of that’s my bad I’m sure…).

So because of these frustrations, stylesheet-switching fell out of favor…at least with me. Too much work for not enough payoff. But those days are behind us now. With SASS, it’s ridiculously easy to not only create several “themes” based on a root stylesheet, but SASS also allows you to get ridiculously complex with variables, mixins, and the like–all with the end result of minimized maintenance needed when making small or large changes.

Getting This Thing to Go

Long story short, I’m giving stylesheet switching another go. Using SASS, I created my theme variations. It took, oh, about 5 minutes. Done. Next step? Getting my app to “remember” the user’s stylesheet choice. In the old days, I used cookies. How trite! With ExtJS 4, I can leverage localStorage, and quickly and easily save, modify and retrieve user’s stylesheet selections.

So with those chores out of the way, my last task was to actually make the “switch” happen. Before anything else, I dug up some old code to see what I had done. As expected, it looked something like this.

First, the HTML:

<link type="text/css" rel="stylesheet" href="ss1.css" />
<link type="text/css" rel="alternate" href="ss2.css" />
<link type="text/css" rel="alternate" href="ss3.css" />
<link type="text/css" rel="alternate" href="ss4.css" />

Then the JS (stolen from an excellent, albeit old, article from A List Apart:

function setActiveStyleSheet(title) {
   var i, a, main;
   for(i=0; (a = document.getElementsByTagName("link")[i]); i++) {
     if(a.getAttribute("rel").indexOf("style") != -1
        && a.getAttribute("title")) {
       a.disabled = true;
       if(a.getAttribute("title") == title) a.disabled = false;
     }
   }
}

So here’s the thing. This TOTALLY still works. And it works well. There’s nothing particular “bad” about it. Right? If it works, it works, it works. But I wasn’t quite happy with it. And here’s why.

This particular method presumes that all the potential stylesheets are loaded when the page initially loads. While this is probably no big deal for relatively small files (heck, it’s probably not even a big deal for moderately large files…), what happens when you have 7 or 8 alternate stylesheets that you want to be available? Obviously, you don’t want to load all those up front, and since you want them standalone, you can’t smash them altogether into one. So we need a better way.

The First Try

The first thing I tried was to load a single, default stylesheet. Then, whenever the stylesheet selection changed, I simply swapped the “href” of the stylesheet link with that of the new stylesheet, like so:

HTML:

<link type="text/css" rel="stylesheet" href="ss1.css" id="stylesheetswitch" />

JavaScript:

switchstylesheet: function(sheet) {
    var base = "resources/css/"
    Ext.get("stylesheetswitch").set({href:base+sheet+".css"});
}

Nothing to it, and it worked…sort of. In Chrome and Safari, it seemed to work pretty smoothly. The switch from stylesheet to stylesheet was seamless. However, when I tried it in Firefox, I noticed a pretty gnarly “flicker” in the interim between the old sheet shoving off and the new one being loaded. By “flicker,” I mean, of course, that my page lost all CSS structuring. Complete mayhem.

So obviously this wasn’t going to work. I flirted with the idea of masking the entire page for a set duration (maybe 300 milliseconds) to hide the flicker, but it just felt hacky.

The Second Try

For my second (and successful try), I decided to take a completely different approach, one that is actually a cousin of the “old-school” way of switching stylesheets. In my version, though, I take a slightly different approach. In the “old” version, the switch is made from a link with a “rel” of “stylesheet” to one with the “rel” of “alternate.” Mine does the same thing. The difference, however, is that instead of pre-loading all my stylesheets on the initial page load, I only load the one’s I need upfront. Then, when a stylesheet that hasn’t been loaded is requested, I simply load it to the page and then do the normal stylesheet switch.

Here’s my approach:

HTML:

<link rel="stylesheet" type="text/css" href="resources/css/ext-all-gray.css" id="ss-gray">

JavaScript:

switchstylesheet: function(sheet) {
    var base = "resources/css/";
    if(Ext.get("ss-" + sheet)) {
        Ext.select("link[id!=ss-"+sheet+"]").each(function(){
            this.set({rel:"alternate"});
        });
        Ext.get("ss-"+sheet).set({rel:"stylesheet"});
    }
    else {
        var dh = Ext.core.DomHelper;
        dh.append("header",{tag:"link",rel:"stylesheet",type:"text/css",href:base+"ext-all-"+sheet+".css",id:"ss-"+sheet});
    }
}

First, you’ll notice that I gave my “default” stylesheet a unique id (“ss-” + ‘theme’ name). In my switch function, I do a few things. First of all, I check the DOM to see if a stylesheet with the expected “theme” id has already been loaded. If it has, I first loop over all the other stylesheets, setting their “rel” to alternate, and finish by setting the selected stylesheet’s “rel” to stylesheet.

If the selected stylesheet has not been loaded, however, I do something different. Using ExtJS’ excellent DomHelper, I create new link tag on the fly, append it to my <head> element, and the switch is made.

Wrapping Up

So that’s about it. A new approach (at least for me) to an old issue. The thing I really like about this method is that it keeps the CSS file footprint small on page load, but also bypasses the “flicker” issues of manipulating a single <link> tag’s href attribute. Even though it’s possible [likely?] that every single stylesheet will eventually be loaded to the page (for example, if the user is browsing through all of them to find the perfect mood), this approach distributes the “load” of those stylesheets through the lifetime of the application, rather than forcing the hit right off the bat.

Of course, all of this is really meant for your development environment. While it’s fine to load 70+ individual JavaScript files while working out your app’s functionality, you *definitely* do not want to impose such a monstrous load on your site’s actual visitors. This, after all, is why everyone uses ext-all.js. It’s the whole framework, smashed down into a single, minified file. But the problem is that it’s still the *whole* thing. There are probably a bunch of bits of ExtJS that you don’t need. This is where the Sencha SDK tool’ can help create a custom build that includes everything you need for your application to run, without the overhead of all the stuff you don’t.

In what follows, I’m going to outline my first ExtJS 4 build using the SDK tools. As a disclaimer, this is my first go, so take it with a grain of salt. If I’ve missed some important bits, or am just plain wrong on any part, please let me know in the comments. And of course, any constructive criticism as to how I can go about this better/more efficiently/etc. is most welcome.

Good? Okay, on we go!

Getting the SDK Tools Setup

First things first. Grab a copy of the SDK tools (for this walkthrough, I’m using v1.2.3). I simply installed them to the default directory. On my Mac, this is /Applications/SenchaSDKTools-1.2.3.

Ok, as we move on I’m going to assume you already have an ExtJS-based application more or less running on your development machine. For me, my application’s path is like so: /Applications/sites/gloss/. In this directory, I have my app structured according to the guidelines outlined in Sencha’s MVC introduction. I’m going to assume that you do as well

Before moving on, here’s a quick look at the index.html file of my app: you’ll notice I’m using the ext-debug.js file and my custom app.js (per the MVC Architecture recommendations).

<html>
<head>
    <title>Gloss</title>
    <link rel="stylesheet" type="text/css" href="resources/css/ext-all-gray.css">
    <script type="text/javascript" src="extjs/ext-debug.js"></script>
    <script type="text/javascript" src="app.js"></script>
</head>
<body>
    ....
</body>
</html>

Creating the JSB3 File

The first real step to creating our custom build is to use the Sencha SDK tools to generate a .jsb3 file. This will be used to tell the SDK tools precisely which resources (.js files) need to be included/smashed/minified/obfuscated. This file is generated in one step, and the actual build is created in another. There’s a good reason for this, namely that you can modify the .jsb3 file (if needed) before finalizing the build (more on this later).

To create the .jsb3 file, open up Terminal. Navigate to your application’s root. For me, this looks like:

cd /Applications/sites/gloss/

You should now be in your application’s root folder.

Next, we need to run the Sencha create command to generate the .jsb3 file. I’ll include the command first, then describe it a bit:

sencha create jsb -a http://127.0.0.1/gloss/index.html -p app.jsb3

The most important part, really, is the address in the middle. According to the docs, you can use either the file name relative to your application (e.g., “index.html”), or the URL of your application (e.g., “http://127.0.0.1/gloss/index.html”). I didn’t have luck with the relative path, but the full URL worked well for me. Give it a try both ways, and see what result you get.

If you didn’t run into any errors, you should now see a new file in your application’s root, based on whatever name you specified in the “create” command above (for this example, it’s simply called app.jsb3). If you open it up, you should notice something like the following:

{
    "projectName": "Project Name",
    "licenseText": "Copyright(c) 2011 Company Name",
    "builds": [
        {
            "name": "All Classes",
            "target": "all-classes.js",
            "options": {
                "debug": true
            },
            "files": [
                {
                    "path": "extjs/src/util/",
                    "name": "Observable.js"
                },
                {
                    "path": "app/controllers/",
                    "name": "MyController.js"
                },
                ....a lot more here....
            ]
        },
        {
            "name": "Application - Production",
            "target": "app-all.js",
            "compress": true,
            "files": [
                {
                    "path": "",
                    "name": "all-classes.js"
                },
                {
                    "path": "",
                    "name": "app.js"
                }
            ]
        }
    ],
    "resources": []
}

The .jsb3 specifies that two “builds” will be created. One will be all-classes.js, which will be a smashi-fication of all the needed ExtJS resources, as well as your custom files. This will be a human-readable collection of all the possible ExtJS and custom scripts that your application uses.

The next, app-all.js, will be a concatenation of all-classes.js and your main, custom app.js file (or whatever you called it). This file will be the one that you ultimately deploy to production…but let’s not get ahead of ourselves.

A few important points here. First, you should take a quick glance through the first “build” to ensure that it does, in fact, have both ExtJS files AND your custom application files. If it doesn’t, there’s something misconfigured in how your application is setup, and you should fix that before moving forward. Second, you’ll notice the placeholders for naming your build. Go ahead and fill that out so your smashed files will have good, meaningful documentation on them.

Everything look good? Excellent! Now it’s time to build some files!

Building app-all.js

After verifying that our app.jsb3 file looks correct and filling out the necessary documentation, we’re now ready to complete the build.

To do that, open Terminal back up again, and make sure that you’re back at your application’s root. To create the build, simply enter the following commands:

sencha build -p app.jsb3 -d .

Simple enough: the “build” command grabs the app.jsb3 file we already created, and uses it as a manifest for creating the build files. Once everything completes without error, you should now notice two additional JavaScript files in your application’s root: all-classes.js and app-all.js.

Now that the build has completed, you can go into your index.html file and replace ext-debug.js with ext.js, and app.js with app-all.js. Open up your application, test, and if everything looks good, you should be ready to deploy with your new minified file.

Here’s what my final index.html file looks like:

<html>
<head>
    <title>Gloss</title>
    <link rel="stylesheet" type="text/css" href="resources/css/ext-all-gray.css">
    <script type="text/javascript" src="extjs/ext.js"></script>
    <script type="text/javascript" src="app-all.js"></script>
</head>
<body>
    ....
</body>
</html>

Something of a Caveat

While the build worked without error for me, I did notice one issue. When I loaded up my app to test, I still saw a few additional JavaScript files being synchronously loaded. Sure, it wasn’t the 70+ from before the build, but it was still a handful–in addition to the main ext.js and app-all.js files.

As I looked closer at *which* files they were, however, I noticed that they seemed to mostly deal with the resources needed for my Viewport. Curious, I opened up my original app.js file, and sure enough, noticed the following:

Ext.application({
    name: "Gloss",
    appFolder: "app",
    autoCreateViewport: true,
    ....
});

While I’m not sure I can verify that this is true, it seems like the issue has to do with the “autoCreateViewport” setting. Perhaps because of the way that the internals of the dependency negotiator works, it misses some of these files while creating the .jsb3 file. Your guess is as good as mine.

Fortunately, there is a pretty dang easy way to fix it. I simply opened up Terminal again and re-ran the .jsb3 create command while leaving the app-all.js file set on my index.html page. When the new .jsb3 file was generated, it included only the resources which were missed in the first go. I simply copied the contents of this .jsb3 file, merged them into my original, and re-ran the build. Voila, no more extra files!

Wrapping Up

Overall, I found the build process to be really nice. Notwithstanding the issue which came from how my application is structured, the steps are very straightforward–it’s much better than the efforts I’ve used in the past.

I hope this walkthrough is helpful to someone, and by all means be sure to let me know if there are areas I can improve upon, corrections I can make, etc.

The best part about History, however, is that it is stupid-simple to implement. There are basically 3 steps:

1. Initialize Ext.util.History
2. Build in the “token-building” logic into your application at appropriate places
3. Define the listener for handling History events.

That’s it. History is not only easy to implement, but it is also pretty unobtrusive–you can implement it fairly simply into an existing app without completely reworking the whole thing.
There’s a lot more to History, of course, so be sure to check out the docs and Sencha’s example.

First, My Example…

Before I talk about the limitation I found in History–and how I overcame it–let me lay out the flow in my application.
In my app, I have a navigation tree in which each item functions a link to retrieve the “main page” data from an external data source. So with each click in the navigation, there is one AJAX request to get data, and the data is then added to the body of a panel in my app.

The idea for History, then, is that I want to tokenize the necessary parameters for my AJAX call, so that when users go “back” or “forward” in the browser, the AJAX request will be fired for the “previous” or “next” page, and they’ll get the appropriate content returned…just as if they had clicked the link in the navigation tree.

So let’s walk through how I set this up:

First, I initialize Ext.util.History:

Ext.require(['Ext.util.History']);
Ext.util.History.init();

Pretty hard, right?

Next, I’ll set up my History “token” in the appropriate place. In this example, I’m placing it the handler for a custom event called “afterupdate”–this event fires after I receive my data back from the AJAX request, as well as after the content of my main body panel has been updated. I put the History tokenization here because if this event fires, I know that I have valid data to tokenize…

this.control({
    "maincontent": {
        afterupdate: function(target,type) {
            ...
            // add to real Ext History
            var oldtoken = Ext.util.History.getToken();
            var newtoken = type + ":" + target;
            if(oldtoken === null || oldtoken.search(newtoken) === -1) {
                Ext.History.add(newtoken);
            }
        }
    }
})

So this is pretty self-explanatory. We first get the old token (retrieved by calling Ext.util.History.getToken()), as well as build our new token. As you can see, the value is completely up to you, so you can be as specific as you want (just be sure to use valid URL characters…).

Finally, if the old token is not defined or empty string, OR not equal to the new token (e.g., we clicked the same link twice in a row), we execute History’s add() method.

The last part of this is the listener for the “change” event. It’s here that everything gets pulled together:

Ext.util.History.on('change', function(token) {
    if (token) {
        var page = token.split(":");
        me.getController("Navigation").loadfromhistory(page[1],page[0]);
    }
});

If a token exists, we split it on the same delimiter we used when creating the token. With these values, we can then do whatever we want–such as executing the loadfromhistory() method which will trigger an AJAX request for the specified page.

…Then the Limitation

While this works brilliantly, there is a small limitation, and it’s simply that the “change” event is fired when the browser back/forward buttons are clicked, OR when the add() method is executed. In the context of my application that basically means the following occurs:

Browser Back/Forward Click:

• loadfromhistory() method executed (good)

add() Method:

• Original AJAX request executed
• Main panel updated
• add() method fires –> triggers History change event
• loadfromhistory() method executed (bad)

As you can see, when adding a token, I basically get the same AJAX request executed twice. While this doesn’t hurt anything really (well, unless I didn’t build my token right…), it’s a waste; there’s no need to make two requests for one set of data.

Unfortunately, out of the box I couldn’t figure out a way to get around this. There’s no “suppressChange” flag for the add method, and there’s no additional information that I can key in on within the change event itself to different between these two scenarios.

What’s more, it doesn’t *appear* to be bad implementation on my part (I’ll take correction on that if I’m off base on this). If you look at the example for Ext.util.History, the same behavior occurs: the setActiveTab() method is executed twice when the History add() method is invoked (e.g., when a tab is clicked), but only once when the browser buttons are used.

The Workaround

After doing a bit of Googling, and finding some common complaints about the lack of event suppression on the add() method of Ext.util.History, I decided to implement a “fix” via Ext.apply(). Here’s the final result:

Ext.apply(Ext.util.History,{
    suppressChange : false,
    add: function(token,preventDup,suppressChange) {
        var me = this;
        this.suppressChange = suppressChange ? true : false;
        if (preventDup !== false) {
            if (me.getToken() === token) {
                return true;
            }
        }
        if (me.oldIEMode) {
            return me.updateIFrame(token);
        } else {
            window.top.location.hash = token;
            return true;
        }
    },
    handleStateChange: function(token) {
        this.currentToken = token;
        // only fire "change" event if suppressChange is false
        if (!this.suppressChange) { this.fireEvent('change', token); }
        // now just reset the suppressChange flag
        this.suppressChange = false;
    }
});

There are really 3 parts that are important.

The first is that I added another property to Ext.util.History, namely “suppressChange.” This flag will tell History whether or not to fire the change event.

The second is that I added another argument to the add() method, again, “suppressChange”. It will simply set the value of the Ext.util.History.suppressChange property.

Finally, in handleStateChange(), I wrapped the change event firing in a condition: if Ext.util.History.suppressChange is false, the change event will be fired; otherwise, it will not. And to wrap it up, the handleStateChange() method automatically resets the default value of the suppressChange property back to false so I don’t have to bother with that elsewhere, and since not suppressing the change event is the desired default behavior.

What this boils down to, then is that you don’t have to muck with your change event listener at all. Rather, you can simply add the suppressChange flag when executing the Ext.util.History.add() method, and let the rest flow on as normal:

// add() invocation with suppressChange flag set to true
Ext.History.add(newtoken,true,true); //token, preventDuplicates, suppressChange

Wrapping Up

And that’s that. To be perfectly honest, I’m not sure if this is *best* way to go about this, but in my testing it does work, at least for my purposes. I’d love to hear *constructive* feedback, suggestions on how to do it better, etc.