If you’re not familiar with git as a version control system, I encourage you to check it out. I came from Subversion, which was great… but, at least for me, git is better. Better yet, if you use git with open source projects, you can use github.com for free to host your code, which is pretty cool, and self-hosting isn’t very challenging either. One of the aspects of git I’m just coming to understand is git-submodule. The idea is that there is an external project you’d like to pull into your project, but instead of committing it to your own repository, you want to use the external project’s repository. Lots of reasons to want to do this, such as making it easier to track upstream changes, or reducing the size of your own repository.

Ever since I learned about git submodules, I’ve thought that ExtJS seemed like a perfect candidate. As there is a mechanism to change the library at runtime without changing the code on the file system, there’s very little reason to have the library in your own repository. On top of which, ExtJS is big, so why waste the space. Sadly, the fine folks at extjs.com do not provide ExtJS in git form. There is a subversion repository for commercial clients (of which my employer is) but subversion is not git.

Thus, I have decided to take matters into my own hands. As ExtJS is licensed under the GPL, I have the legal right to redistribute the code. So I created my own git repository just for ExtJS at github which anyone can use as to add ExtJS as a git submodule. I’m still trying to figure out some aspects of git-submodule… like, is it possible to specify a tag from the external repo? If so, I will start adding tags to the repository as new versions are released.

For those who want to jump right into using the repo, here’s the magical incantation you want to run from your project root (change the “public/extjs” part to the relative path you want to install ExtJS at):

git submodule add git://github.com/probonogeek/extjs.git public/extjs
git submodule init
git submodule update

Lastly, if there are any extjs.com folks reading this who object to what I’ve done, please don’t hesitate to contact me. While the GPL gives me permission to do as I’ve done, there is a big difference between legal right and community consent. Right now I’m operating on a sort of tacit consent, but will take the repository down if requested.

First things first, setup your application by whatever magical incantation is appropriate, in my case:

merb-gen app extjs_demo

Now we have a clean application all ready to go. Next you need to bring ExtJS into your codebase so you will have access to it. As ExtJS is 99% javascript, you will want to install in whatever directory your app will use as its document_root so that HTTP requests can get at it. In merb/rails, that directory is called public/. I recommend against using public/javascripts/, even though it’s right there calling out for javascript files. The way I see it, ExtJS is an external library, while public/javascripts/ is where you put your own application scripts, but reasonable minds can disagree.

Head on over to extjs.com and grab the latests release (2.2.1 as of this writing). Pay attention here… you want to unzip the file in its own directory named extjs-2.2.1 (or whatever version you downloaded). If you unzip the file directly into public/, you’re going to be sorry. Now create a symlink pointing to extjs-2.2.1 called “extjs”.

ln -s extjs-2.2.1 extjs

This symlinking strategy allows you to easily try out new releases of ExtJS and revert back without having to worry about blowing away old versions until you are ready.

Now you have ExtJS installed and can already do a great deal if you were to startup your empty app right this very second and access http://localhost:4000/extjs/docs/index.html with your trusty browser. Your framework may use a different port number (Rails defaults to 3000). With merb properly installed on my system, I can just startup the app from the merb root directory by running:

bin/merb

Your browser should show you the API docs just as if you had accessed them on the ExtJS website. This is going to be your number one place to learn the finner points of ExtJS, and now you have it with you so long as you have your application’s source. Handy for those times you don’t have internet access. If you’re using source control, now is a good time to commit

Next we face an important choice. As we build our application we are going to define different ExtJS subclasses (more on what that means in a later post). Those subclasses need to be loaded into your application via the familiar script tag. But there are two different ways our application can respond the script tags request:

1. Serve static javascript files from public/
2. Serve dynamic javascript files from a controller/view setup

Static files in public/ have the advantage of loading much faster, as they come directly off the file system and skip over the framework’s call stack. Dynamic files from a controller/view are dynamic, which allow the javascript to be custom tailored for the user’s needs. Both have their uses and after a lot of trial and experimentation, I determined the best approach is to use both. Okay, so I lied… there is no choice.

What we are going to do is define the various subclass methods in public/javascripts/. These files do not need to change on a per-user basis, so we get the benefit of the static load time. But any files that require dynamic generation will be done via a controller and a view. But before we go a step further we need to setup your application’s index page.

In my estimation, there are two ways to use ExtJS in your application. You can either use it as a widget set for things like buttons, dialog boxes, and grids in the way you might use jQuery UI. Or you can do everything in ExtJS. For the app I’m building at work, ExtJS powers the entire display of the administrative back-end. The setup I’ll show you today assumes that you’re entire app is going to be driven by ExtJS. If you think you’re going to be less whole-hog, don’t worry, many of the steps will be the same.

First things first, we need a root index page to work with. By default, I get a lovely No routes match the request: / error message when trying to access http://localhost:4000. There are lots of ways to setup an index page depending on your framework, all of which is beyond the scope of this post. What I did with merb was create a controller called “home” and added a route to connect “/” with “home/index”.

Next we need to get the view for home/index looking how we want. Many MVC frameworks use layouts to reduce code duplication between views — which is great — but for us, it’s actually a real problem. So I recommend you disable layouts for the home controller (in merb you just declare “layout false” in the controller file). Now head over to the view for home/index (in merb, it will be at app/views/home/index.html.erb). This file is going to serve as your loading point for all the ExtJS magic you need to make your application sing.

Now, add the following HTML right into the file:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Your ExtJS Application</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <link rel="stylesheet" type="text/css" href="/extjs/resources/css/ext-all.css">
</head>
<body>

  <!-- External Dependencies -->
  <script type="text/javascript" src="/extjs/adapter/ext/ext-base.js"></script>
  <script type="text/javascript" src="/extjs/ext-all-debug.js"></script>

  <!-- Application Runner -->
  <script type="text/javascript" src="/home/application.js"></script>

  <!-- App Specific Classes -->

</body>
</html>

Let’s look at the lines that may not seem immediately obvious:

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

Loads the ExtJS master CSS file. This has all sorts of CSS definitions that make all the ExtJS widgets look super delicious.

<!-- External Dependencies -->
<script type="text/javascript" src="/extjs/adapter/ext/ext-base.js"></script>
<script type="text/javascript" src="/extjs/ext-all-debug.js"></script>

These two lines load up the ExtJS library itself into your application. Make sure you load them in the order specified here. Couple of important notes here. The first line is the adapter line, and I’m told it allows you to teach ExtJS to play nice with other JS frameworks like jQuery and Prototype. I haven’t played with any of that, so your mileage may vary if you go that direction, here we are using ExtJS with ExtJS. The second line is the monster library include and here you actually have two choices. In development mode, I always load ext-all-debug.js, because Firebug output is far more useful… but in production, you’ll want to use ext-all.js, which has been minified for quicker download to your clients. In a more advanced application, we’d have the view determine which file to send programatically, but we are going to take it slow.

<!-- Application Runner -->
<script type="text/javascript" src="/home/application.js"></script>

<!-- App Specific Classes -->

The Application Runner is the starter pistol of your ExtJS application… the thing which makes it go. We are going to setup a basic one in just a moment. Then under that is where your application specific ExtJS subclasses are going to be loaded. There aren’t any at present, but we will write one shortly and it’s good to have a place ready to put them.

For the Application runner you will need to add an application action to the home controller and indicate that it serves up javascript. In Merb:

  def application
    provides :js
    render
  end

Then create a view at app/views/home/application.js.erb and dump in the following:

Ext.BLANK_IMAGE_URL = '/extjs/resources/images/default/s.gif';
Ext.ns('demo');

// application main entry point
Ext.onReady(function() {

  var viewport = new Ext.Viewport({
    items: [
      {
        region:     'north',
        html:       '<h1 class="x-panel-header">Your Demo Application</h1>',
        autoHeight: true,
        border:     false,
        margins:    '0 0 5 0'
      },{
        region:     'center'
      }
    ]
  });
  viewport.show();

});

The first two lines of code set some global configuration. The first line there is a request from the fine folks at ExtJS to use your own locally hosted single blank pixel instead of theirs (it’s the least you can do). The next creates a namespace for the code you are going to be writing. I’ve chosen the highly descriptive “demo” as my namespace here, but I recommend using a short-hand version of your application. The big advantage of using a namespace is now you can define whatever classes you want without bumping into native javascript classes. All of the ExtJS base classes are namedspaced to “Ext”, so I recommend using something other than that.

Then comes the starter pistol:

Ext.onReady(function() {
  // code goes here
});

If you are familiar with jQuery, this is equivalent to:

$(document).ready(function(){
  // code goes here
});

What it does is ensure the code inside of the block is not executed until the entire page is done loading. Meaning all of the javascript libraries, CSS files, etc. If you try to execute your application code right away, you can’t be sure the environment is full prepped. Wrapping your code in the Ext.onReady method gives you the confidence everything is, well, ready.

Then lastly we’ve got this Ext.Viewport constructor with some configuration parameters passed into the constructor. Don’t worry about the specifics of the configuration at the moment, we’ll talk about Viewports in some other post. What’s important to know is that Viewports setup a full browser window environment to instantiate other components. It is the starting point of any full ExtJS application.

At this point you can save these files, startup your application and go to the index page. You should get a panel at the top that reads “Your Demo Application”. Congratulations, you’ve got an ExtJS application!

One last thing to do before we close down for the day. The Viewport there has application specific configuration variables, and as you will learn in the post on subclassing, that is indicator number one that we should create an ExtJS subclass. To do so, create a file at public/javascripts/demo.viewport.js (note, if you declared a different namespace than “demo” use that wherever I use “demo” in all of the following examples). In the file you just created, paste the following:

demo.viewport = function(config) {

  var base_config = {
    items: [
      {
        region:     'north',
        html:       '<h1 class="x-panel-header">Your Demo Application</h1>',
        autoHeight: true,
        border:     false,
        margins:    '0 0 5 0'
      },{
        region:     'center'
      }
    ]
  };

  Ext.apply(base_config,config);

  demo.viewport.superclass.constructor.call(this,base_config);

}

Ext.extend(demo.viewport, Ext.Viewport, {});

Update your application.js file to read:

Ext.BLANK_IMAGE_URL = '/extjs/resources/images/default/s.gif';

Ext.ns('demo');

// application main entry point
Ext.onReady(function() {

  var viewport = new demo.viewport()
  viewport.show();

});

And under “App Specific Classes” in the index.html file, add:

<script type="text/javascript" src="/javascripts/demo.viewport.js"></script>

Reload the index page and nothing should change. Except now we’ve got the static parts of the application being served from public/javascripts/ and the dynamic parts of the application from the home controller. With this basic framework we are ready to start learning about subclasses and how to organize you ExtJS code.

I honestly can’t imagine a use for this plugin other than someone who blogs about both ExtJS and non-ExtJS topics. But, if you are interested in the plugin, it is available at github.

A few caveats… this plugin is still very much in progress. The ExtJS category ID is hard coded into the code. So, unless your ExtJS category ID == 10, as mine does, the code won’t work. Future releases will allow you to specify which category to load on… and maybe, down the road, allow you to specify which parts of ExtJS to load, as opposed to the whole suite like it’s doing right now.

But here’s the big payoff for all this work. I give you my first embedded ExtJS example:

Now, if you think that was easy, you’ve got another thing coming… took me forever to get that to work. Not because of the ExtJS, but because of all the stylesheet interference with my kick-ass WordPress theme. But I think I’ve got it all sorted out. Here’s the entirety of the code I used to produce the above.

  Ext.onReady(function() {
    button = new Ext.Button({
      text:     "Click me, I won't bite",
      renderTo: 'example-button',
      handler:  function(){
        Ext.Msg.alert("Congratulations","You clicked me!");
      }
    });
  });

And then I defined a DIV on the page with ID = “example-button”. It’s just that easy. I think all the kinks are finally worked out and we can get into some real learning with the next post.

Firebug, the Indispensable Tool

The first central concept to cover is basic tools. Back in the day, javascript debugging involved peppering your code with alert() calls that would popup little messages… like print statements in a scripting language, but way more annoying because they would stop the process until you pressed the “okay” button. But now there is a better way. The better way is Firebug. It’s a Firefox extension that lets you peer into your webpage in ways never before possible. It is absolutely essential to doing ExtJS work, so if you don’t have it, you need to get it. If there is a similar tool for IE, I haven’t encountered it, so even if IE is your target browser, use Firefox for development purposes and just be sure to occasionally test in IE for cross-browser issues.

By now I’m assuming you have Firebug installed. You should have a little bug icon in the bottom right of your browser. If you click on it, a panel will expand showing some Firebug options. You want to enable the Console. Script and Net have their uses too, but for today’s lesson, we want the Console. Turn it on for this blog… the page will reload and then you will see four items printed out to the terminal.

The first is a string I sent to the console with the following Javascript code:

console.log('Hello Word');

By calling the log method on the console object I can send pretty much anything I want to the Console you now see below. Turns out you can send nearly anything to the console and Firebug will let you see all sort of internal data. But I’m getting ahead of myself. Before talking about the remaining items in the FireBug Console, I need to talk about some central features of Javascript.

If you were at all like me, you learned about the basic Javascript native types. Chances are that means you learned the following:

var n = 5; // is a Number
var s = 'Hello'; // is a String
var a = new Array('red','blue',green'); // is an Array

You may have even learned a little more advanced stuff, like:

var t = new Time(); // is a Time object
var a['key'] = 'value'; // is an associative array

And, of course, you learned about functions:

function do_stuff( argument ){
  // stuff gets done
}

That was probably good enough to do all sorts of stuff. But if that’s where you stopped you never really learned the fundamental attributes of Javascript that make it possible to do all the cool stuff that ExtJS does (to say nothing of JQuery or Prototype). There are two critical parts of your education that need reenforcement.

Hashes (actually, objects)

Basic computer science teaches us about arrays and hashes, one is ordered data and the other is keyed data. Each have strength and weaknesses. If all you learned was the above, then you probably came to believe — as I did — that Javascript used the Array type for both. Since it was possible to use both integers and strings as Array indexes, it’s not hard to see why.

addresses = new Array();
addresses['alice'] = '123 Fake Street';
addresses['bob'] = '1600 Pennsylvania Ave';

Sure looks like a hash to me. And in a way it is a hash, because it’s keyed data. But in Javascript there is another more powerful way to create a hash. Except, Javascript doesn’t call it a hash, it is called an object. Behold:

addresses = {
  alice: '123 Fake Street',
  bob: '1600 Pennsylvania Ave'
};

Looks like awfully familiar syntax, don’t it? Like, here’s the same object expressed in Ruby:

addresses = {
  :alice => '123 Fake Street',
  :bob => '1600 Pennsylvania Ave'
}

I honestly couldn’t tell you why it’s an object and not a hash, but there it is. The important part is that you can create arbitrarily complex data structures using this syntax in a single assignment. Oh, and for an additional syntactic win, instead of using new Array(), you can just use []. Which means we can do the following:

persona_data = {
  first_name: 'Alice',
  address: {
    street: '123 Fake Street',
    city: 'Springfield',
    zipcode: '12345'
  },
  favorite_colors: ['blue','green']
};

Now that you see how data structures in Javascript can be very sophisticated, let’s see how you can use the Firebug Console to peer inside. Open up the console again and click on the second row that reads Object first_name=Alice address=Object favorite_colors=[2]. In there you will see the different properties of the personal_data object we created above. You can expand the address property to discover it too is an object with its own properties, or expand the favorite_colors property to inspect an array.

Functions as Properties

It turns out that objects, like the ones above, can hold any type of Javascript native type in one of its properties. Arrays, strings, numbers, other objects… you’ve seen examples of all of that by now. The final piece of the puzzle then is to see that objects can also store functions. In Javascript, a function is just another piece of data that can be assigned to a variable, like this:

var my_method = function(){
  // do stuff
}

Now I can run around with the my_method variable, assign it to other variables, and even execute it. And here in lies the third and final lesson of the post. Consider an object like the following:

var refrigerator = {
  contents: ['milk','eggs','cheese'],
  grab_item: function(){
    return this.contents.pop();
  }
}

Here we’ve got our refrigerator object, it’s got some stuff in it, and we’ve got a grab_item method that returns the last item off the contents array. To call that method we have to use just the right syntactic sugar, which means putting parentheses at the end. Consider the following two lines of code:

  snack1 = refrigerator.grab_item // wrong, snack1 now equals the function
  snack2 = refrigerator.grab_item() // right, snack2 now equals 'cheese'

See, we have to tell javascript we want to actually execute the function, not just assign the data. Firebug confirms this in lines three and four on the console.

Okay, with the concepts of objects and methods down, and Firebug installed, we are ready to start diving into ExtJS. Next ExtJS post will have actual ExtJS examples, I promise… I think I’ve nearly got all the bugs worked out for demoing live ExtJS code.

Okay, now that we are just down to the web developers and the wannabe web developers, lets try and get the basics established so that future posts will have a common language we all agree on… or, at least, that I agree on and that you will be forced to understand to extract anything from my ramblings.

ExtJS describes itself as a “Ext JS is a cross-browser JavaScript library for building rich internet applications.” Which is as good a description as any, if not a tad simplistic. I think a more complete description would be, “Ext JS is a GUI framework for building rich internet applications available under either a commercial or open source license.” The emphasis here is that ExtJS:

1. allows for the quick deployment of reusable GUI components
2. is used to build front ends
3. contains a mixture of javascript, CSS, and binary assets
4. has a dual license model

Let’s break those points down to understand what I’m driving at.

Allows for the quick deployment of reusable GUI components

Let’s talk about the sexy stuff first. ExtJS provides a whole ton of Graphical User Interface (GUI) components that you would expect to see in a modern Desktop Environment, but generally don’t see on the web. There is an outstanding ExtJS Example page that shows off most of what the framework can do.

Here’s a quick and dirty list of the various components:

• grids (like in a spreadsheet)
• tabs
• modal windows
• trees
• enhanced form elements
• toolbars
• menus
• buttons
• sliders
• tooltips
• progress bars

Sadly, I haven’t come up with a good way to demo any of these bits of code in WordPress yet (all JS code is sanitized by default to protect against evil), but it’s something I very much plan to work out. In the mean time, let me show you how easy it would be to create an attractive looking button.

  buttonObj = new Ext.Button({
    text:'Press Me',
    renderTo: 'button'
    handler: function(){
      // button action goes here
    },
  })

Then, all we would need is an HTML DIV element with an ID set to “button” and we’d be done. Once the Javascript had executed it would render the button inside of the designated DIV complete with the handler functionality all ready to go. If all of that is Greek to you, don’t worry, I’m going to explain some of the Javascript basics in a future post.

Is used to build front ends

ExtJS’s primary function is to generate HTML for display via a web browser and to attach behaviors to those HTML elements that the user can interact with. This aspect is more important for what it isn’t, than what it is. What ExtJS shouldn’t be used for is application logic. That’s not to say it cannot be used for application logic, just that down that way is madness, so try to avoid it. Here’s some good reasons to keep application logic out of ExtJS.

• ExtJS talks to your webserver via AJAX, which means you will need backend scripts of some kind to process those requests. As those scripts are closer to the database that will back your application, it is those scripts that serve as the more appropriate vessel for your application logic.
• ExtJS uses Javascript for anything functional, which means you would end up writing your application logic in Javascript. Not to dis on Javascript as a language, but most of us don’t have the experience with Javascript to write clean and maintainable application code.
• ExtJS is more like the View part of an MCV application, and the MCV paradigm does not take kindly to embedding logic into the View. For example, if you put application logic into the view and have two views on the same data, you would need two implementations of the same logic. Talk about code duplication nightmares.

If you are really dead set on making a pure ExtJS application, I wish you all the luck in the world, but I don’t think you’re going to find many of my posts very helpful. Consider yourself warned.

Contains a mixture of javascript, CSS, and binary assets

Here’s where I disagree most strongly with the official ExtJS definition. Yes, ExtJS is a “Javascript library,” but it’s so much more than that. In addition to the javascript files that comprise the core of ExtJS, there is a full 2.3 MBs of CSS and image resource files that go along with it. For the most basic uses of ExtJS, you may never look in the resources directory. But as you begin to understand the deeper relationships in the library, you will begin to see how fundamentally important those CSS definitions are, and how tweaking a few images can give you a wide range of flexibility.

Has a dual license model

If ExtJS were to ever be considered controversial, it would be because of this final point. I didn’t come to ExtJS until late 2008, at which point the library had been around for a while. The story goes that ExtJS used to be available under a more permissive open source license, such that commercial developers could use the code without buying a commercial license. At some point in ExtJS’s product development, the company decided to change the open source license to the strictest of all licenses, the GNU General Public License. This engendered quite a bit of bad blood among those commercial developers, who felt like they were tricked into adopting a library and now either had to cough up the dough for a commercial license, GPL their own works, or start all over again.

My opinion is what it generally is involving the GPL… sounds good to me! If a commercial developer wants to benefit from the work, then they are free to pay for future development by buying a license or they can contribute back to the community. The value of a third option is marginal at best, and more likely to induce free-riding than stimulate community.

My company has the good fortune of being able to buy a commercial license outright, so we do all of our development in a closed source environment, so I won’t be showing any examples from that project. What you will see in these posts is using my own personal copy of ExtJS which I have under the terms of the GPL. Which, by my reckoning, makes any example code I throw up here also available under the terms of the GPL. Of course, a lot of the code will be more functional than expressive, in which case you don’t really need to worry about licenses… just use this to study and build your own.

I think that should do it for our introductory post (clocking in at 1133 words already!). Next time I’ll discuss some basic javascript concepts and then get into some of the GUI elements.

Since November, I have taken the lead in our company to build the front-end of the new CMS (which is called the Articulated Man Publishing System, or AMPS for short). The process has been both frustrating and rewarding, but now that I’m at the tail end of the learning curve, I find it to be 100x more rewarding than frustrating and can’t imagine building AMPS in anything else.

But the months between the final decision and feeling like I finally get it have been long and lonely. While there is excellent primary documentation on ExtJS, there is very little secondary documentation, like blog posts on how to do X, or discussions on the merits of different approaches to Y. Other than the sprawling and disorganized forums, ExtJS sort of just expects you to figure it out on your own.

Starting today, I’m going to do my part to remedy that situation. I have created a new subcategory under Technology called — unsurprisingly — ExtJS, and this is the category’s maiden post. My goal here is to build up a set of posts that explain what I consider to be idiomatic ExtJS, in particular the intersection between MVC applications and ExtJS. With any luck, someone venturing out on a project similar to mine will find this information useful, but if nothing else, it will help me clarify my own thinking on how best to solve problems with ExtJS.

Be on the lookout for my first post, probably tonight, where I explain in the most general terms what ExtJS is so that everyone can play along at home. But, if you can’t wait, you can always take a gander at the example pages and learn for yourself.