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

Today, I stumbled upon Sugar,  a really nice–and small–JavaScript library. Unlike monster libraries such as jQuery and ExtJS (which are awesome in their own ways…), Sugar is narrowly focused. It’s niche is simply extending native JS objects with intuitive methods.

So want to capitalize the first word in a string? Easy: string.capitalize(). Want to replace dashes/underscores with spaces? Nothing to it: string.spacify().

I’ve worked up a quick couple of demos of a few of the string methods, just to show how dead simple Sugar is to use. Of course, you should check out Sugar’s API for the full enchilada. Mmmm, enchildas…

Impressions

While I am a die-hard ExtJS user, there is something about the simplicity of Sugar that I really like. While it certainly won’t give you the tools to build a full-fledged web app with components, data grids, and what-not, it’s perfect for the small or one-off websites/pages where JS’ native objects could use some extra lovin’.

The one drawback (and it’s a slight one) is that there does not appear to be a way to do a custom build of Sugar to include *only* those methods which you need. According to their blog, this is because of some internals of Sugar that are needed throughout the library for IE support. What, IE ruining yet another otherwise great project? Surely not!

Although the custom-build-ness is lacking, the full library is only 17k gzipped, so there’s really not a huge hit including the whole thing anyway. That’s what caching is for anyway, right?

Wrapping Up

Honestly, I haven’t looked closely at Sugar’s internals to make a judgement about how “well done” their extension of native JS objects is. However, my initial impression is that I really like the approach they’ve taken. The ridiculously simple implementation of their API makes Sugar a library worth keeping in mind when you’ve got some light to moderate JS-in’ to do.

Ah, but that’s the neurosis of the Western mind; what can be done about it? Nothing

But even though I’m reticent about making resolutions, I have been thinking about the year that lies ahead, particularly from a professional standpoint. Over the last year, I’ve been very productive in my professional development. Particularly in relation to ColdFusion, JavaScript and SQL, I have tremendously expanded my competency, and I feel quite comfortable with where I am as a developer.

However, as we all know, complacency can be a silent killer. While it may not immediately harm a person in relation to their employment prospects, it can be detrimental in the long-term, if nothing else than by souring them to the prospects of learning new skills, exploring new technologies, etc.

I don’t want this to ever happen. I don’t feel like it’s a particular danger right now; I’m a naturally inquisitive person, so exploring new technologies, improving skills, etc. is just something I like to do. However, I do see this problem manifest in others, and I don’t like what it looks like. So, in my pre-emptive attempts to ward off such a fate, I’ve come up with a resolution (or two) of sorts for 2012.

Becoming “Expert”

When it comes to ColdFusion and JavaScript development, I feel very confident in my abilities. For any task, no matter the complexity, I am more than capable of crafting a solution that utilizes these technologies. I don’t say that in arrogance; it’s simply a fact. Ater so many years of using each, I can accomplish many things…and very quickly at that.

But while I am fully capable of using these technologies, I am also keenly aware of the extent (and limitations) of my competency. I have no delusions about my understanding of CF and JS. Yes, I can use them quite capably to do just about anything that is proposed. However, in regard to a more fundamental knowledge about the technology qua technology, I find many gaps in my understanding.

Therefore, one of the things that I want to pursue in 2012 is to begin a journey of becoming “expert” in ColdFusion and JavaScript. To me, the “expert” part that I’m missing is precisely this deeper understanding of how each technology *works* apart from the day-to-day grind of *using* them to accomplish discreet tasks. So this will mean that I will probably be doing a lot more reading about the technologies than actually using them. And you know what? I think that’s okay. The school of “learning by doing” has gotten me a VERY long way in my career. However, I think the next step wil come only by a very deep commitment to learning the bits that won’t necessarily come by trial and error.

You’ll notice I said “begin a journey.” I don’t expect to become “expert” by the end of 2012. However, I do want to determine a path that will get me where I intend to go. If I can accomplish just that, 2012 will have been a success.

Explore New Frontiers

One of the biggest keys to professional development, especially when it comes to web development, is to have an expansive portfolio of skills. This doesn’t mean, of course, that one needs to be “expert” in 7 different languages; that would probably be impossible for most people. However, it does mean that one is open to actively pursuing an understanding of how different technologies work and how each can be leveraged in various situations to accomplish particular goals.

In the coming year, there are a lot of technologies that I want to explore. In order to not get completely overwhelmed, I’m going to take a dual approach.

First, I’ve selected a handful that I want to do more of a “deep dive” into; these will require several weeks/months of exploration each. By the end of the year, I’d like to be able to say that I have a base-level competency with each technology–not something on the basis of which you’d hire me, but a working knowledge expansive enough to be able to accomplish something, and a solid foundation upon which I can build in the future. Here are the targets:

• Ruby
• Node.js
• jQuery
• Python
• ORM
• Git

Second, I want to build time into each week to take an hour or two to make a surface exploration of new technologies/snippets/etc. that I come across in the course of my daily blog trolling. So for example, if a new JavaScript framework is highlighted in one of the blogs I read, I want to explore that. My intention is, at the very most, to devote enough time to make a surface exploration. While this will not by any means make me competent in this or that technology, I think the practice will help to expand my skill set, simply by seeing how other people do things. I don’t have a discreet list for these, as I hope to leave time open for exploration as opportunities present themselves.

Avoiding Blackhole Projects

Over the last year, I found myself buried in blackhole projects. These were projects that I came up with on my own that didn’t have particular goals, or defined execution plans. With each of them, I started with the *intention* of learning/doing something new. However, I dreamed way too big, never accomplished whatever I had set out to do, and wasted a ton of time and effort for nothing except frustration.

In 2012, I’m going to make a concerted effort to avoid projects altogether. I’ve found that projects tend to devour an inordinate amount of time, simply because I end up spending a lot of effort on things that aren’t even central to the project itself (like getting the design pixel perfect, abstracting the 20 lines of JavaScript being used, etc.). So instead of using projects as a way of exploring this or that technology, I’m going to try to focus on simply executing very small, manageable development tasks. Whether this is simply creating a nice “Hello world” or developing some extension/module/whatever, keeping the scope tiny and defined will hopefully help me be much more productive in my learning and exploration.

Blogging

My blogging output in 2011 was a little underwhelming. While I did add some fairly in-depth posts, the number of posts was a bit disappointing. While quantity doesn’t really mean anything, it does reiterate to me the project blackhole problem I had during the year. So one of the things I really want to focus on in 2012 is becoming a better blogger. For me, I think this means being more intentional about regularly positing my experiences, while also not being quite so concerned with feeling like I have to write a novel each time.

Wrapping Up

So, it’s an ambitious plan for 2012. However, I’ve already made one important step: today, I officially abandoned a blackhole project that I had started last week. I’m beginning with a clean slate, and am looking forward to a great year of leaning, improving, and expansion of my development skills.

If anyone has any constructive thoughts/suggestions, I’d love to hear them!

• 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 let’s talk about a specific example. Let’s imagine that you want to simply change the background color on your app’s toolbars. The first thing you’ll probably do is pop open Firebug or Developer Tools to inspect the CSS that’s being applied to your toolbar. Unless you’ve already customized it, you’ll probably seem something like this:

I’ve highlighted “x-toolbar-dark”, because by default, the “UI” configuration option for Ext.Toolbar is set to “dark,” which applies the “x-toolbar-dark” class to your toolbar (it will apply “x-toolbar-light” if you specify “light” for ui…more on this later).

Here’s what the toolbar actually looks like:

If you inspect the properties of this CSS class, you should see something like this:

• background-color: #456F8D;
• background-image: -webkit-gradient(linear, 50% 0%, 50% 100%, color-stop(0%, #9cbacf), color-stop(2%, #5182a5), color-stop(100%, #395c75));
• background-image: -webkit-linear-gradient(#9cbacf,#5182a5 2%,#395c75);
• background-image: linear-gradient(#9cbacf,#5182a5 2%,#395c75);
• border-color: black;

Nothing too crazy here…just some background-image gradients to give the toolbar a nice textured feel. Now at this point, you might be tempted to do something crazy, something like creating a new class in an extra custom stylesheet to override these style rules. Or, you might add a custom class via the Ext.Toolbar’s “cls” config, and add the styles for this custom class in your custom stylesheet.

While both of these options will certainly work, they miss out on the power of theming within Sencha Touch. So let’s look at a better way to approach this.

Toolbar UI

If you look at the documentation for Ext.Toolbar (as well as several of the other common components), you’ll notice that it has a config option for “ui”. By default, you can specify either “dark” or “light,” which is what applies either the “x-toolbar-dark” or “x-toolbar-light” classes to our toolbar. So knowing this, the ideal approach to customizing our toolbar’s style is not by creating custom, external style rules to override or circumvent default Sencha Touch styling, but rather to create our own “ui” that we can use in the configuration of our Ext.Toolbar itself.

Fortunately, this is ridiculously easy…but first, some context

Default Toolbar UIs

As mentioned, the Toolbar has two default UIs: dark and light. By specifying either of these in the configuration of your Ext.Toolbar, you can easily switch between the two to get the feel that you would like (this is especially helpful if you have stacked toolbars).  Let’s take a look at how these UIs are created.

First, we’ll need to find the .scss (Sassy CSS) file that generates the toolbar CSS classes. You can find that here:

sencha-touch-1.1.0/resources/themes/stylesheets/sencha-touch/default/widgets/_toolbar.scss

A ways down the page, you’ll see something like the following:

@include sencha-toolbar-ui('dark', darken($base-color, 10%));
@include sencha-toolbar-ui('light', $base-color);

Here, our two default UIs are created. This is done by using the sencha-toolbar-ui “mixin,” which is really just a mechanism to allow you reuse chunks of code to construct CSS classes. The great part about mixins, though, is that you can utilize arguments, so it makes creating custom iterations of the same family of classes super easy.

Now let’s take a look at the mixin itself:

@mixin sencha-toolbar-ui($ui-label, $color, $gradient: $toolbar-gradient) {
   $toolbar-border-color: darken($color, 50%);
   $toolbar-button-color: darken($color, 10%);
   .x-toolbar-#{$ui-label} {
      @include background-gradient($color, $gradient);
      border-color: $toolbar-border-color;
      .x-toolbar-title {
         @include color-by-background($color);
         @include bevel-by-background($color);
      }
      .x-button, .x-field-select .x-input-text, .x-field-select:before {
         @include toolbar-button($toolbar-button-color, $gradient);
      }
   }
}

As you can see, the mixing takes up to 3 arguments:

• The name of the UI
• The base color for the UI
• The type of gradient to use for the UI (defaults to the variable $toolbar-gradient)

Then, based on the arguments passed, this mixin will create a CSS class in the form of “x-toolbar-[UI Name]“, and will additionally create classes that riff on the color and gradient that are specified for the overall UI. This will give the toolbar a unified “feel” if it contains buttons.

Creating our Own Toolbar UI

While this UI/SASS/mixin stuff can be a little overwhelming at first, hopefully you see now how it starts to come together. Since we know that the “dark” and “light” UIs for the toolbar are crafted simply by using the sencha-toolbar-ui mixin, it’s pretty clear how we need to proceed to create our own UI. So let’s do that now.

In sencha-touch-1.1.0/resources/sass/, I’ve created a custom .scss file (I’ve called it “custom”…pretty original, I know). In this .scss file, I’m going to create a custom toolbar UI. Since “blue” is way to predictable for a developer, I want to try something sheik, but safe. How about a nice “charcoal” UI?

Here’s how we do it:

$base-color: #588aad; // go big blue!
$include_default_icons: false;
@import 'sencha-touch/default/all';
@include sencha-panel;
@include sencha-buttons;
@include sencha-sheet;
@include sencha-picker;
@include sencha-tabs;
@include sencha-toolbar;
@include sencha-toolbar-forms;
@include sencha-indexbar;
@include sencha-list;
@include sencha-layout;
@include sencha-form;
@include sencha-msgbox;
@include sencha-loading-spinner;

@include pictos-iconmask("bookmarks");
@include pictos-iconmask("compose");
@include pictos-iconmask("trash");
@include pictos-iconmask("search");
@include pictos-iconmask("my-logo");
@include pictos-iconmask("bookmark2");

@include sencha-toolbar-ui('charcoal', #333333,'glossy');

Ok, 98% of the code above has nothing to do with our custom UI. I just wanted to include it, in case you’ve never seen an .scss file. The most important line for our UI is the last one.

What? One line? Is that really all there is to creating a custom toolbar UI? The simple answer is YES.

Easy, right? And this is precisely why I advocate for creating the custom UI, over and against modification of a custom stylesheet. With the custom UI, we don’t need to do anything else besides this one line of code here. Any maintenance moving forward (like tweaking for a more nuanced “charcoal” color) will only require a quick modification here. No extra style sheet to worry about, which is always a good thing.

Using the Custom UI

Alright, so we’ve created our custom UI. How do we use it?

Well, first, we’re going to need to recompile our app’s stylesheet.

In Terminal, navigate to sencha-touch-1.1.0/resources/sass (where we created our custom .scss file), and then type “compass compile“. If everything goes through ok, you should now see a “custom.css” (or whatever you named it) in the sencha-touch-1.1.0/resources/css folder.

If you have no idea what’s going on here, take a look at this article on getting setup for theming in Sencha Touch.

Take this path to your custom CSS file and add it to your main application file so that it’s using it as the main CSS.

Good? Ok, now we can apply our custom UI to a toolbar!

var myToolbar = new Ext.Toolbar({
   dock: "top",
   title: "Fancy Charcoal Toolbar in the House!",
   ui: "charcoal"
});

That’s it! Save your work, refresh your browser, and you should now see your app with a sheik, sophisticated charcoal toolbar

The final result?

And the underlying HTML:

(Notice it’s exactly the same as before, but now with the new UI class of “charcoal”)

Wrapping Up

I can’t understate the point enough that what’s been outlined above has only scratched the surface of what’s possible. But hopefully it demonstrates some of the really cool things that can be accomplished with very little effort, and in such a way that is a natural extension of Sencha Touch’s powerful theming capabilities.