Tuesday, 8 September 2009

The trouble with new

We have a simple JavaScript class:


function User(firstName, lastName) {
this.name = firstName + " " + lastName;
}

We create a new User:


var ed = new User("Ed", "Spencer");
alert(ed.name); //alerts 'Ed Spencer'
alert(window.name); //undefined

All is well. Unless we forgot the 'new':


var ed = User("Ed", "Spencer");
alert(ed.name); //ed is undefined
alert(window.name); //alerts 'Ed Spencer'

Curses! That's not what we want at all. By omitting the 'new' keyword, the JavaScript engine executes our 'User' constructor in the current scope, which in this case is the global window object. With the scope ('this') set to window, setting 'this.name' is now the same as setting 'window.name', which is not what we're trying to do.

Here's the problem though, omitting the 'new' keyword is still perfectly valid syntax. We know at design time if 'new' must be used or not, and can use a little trick to make it act as though 'new' was indeed used:


function User(firstName, lastName) {
if (!(this instanceof User)) {
return new User(firstName, lastName);
}

this.name = firstName + " " + lastName;
}

Because the 'new' keyword sets up a new context, we can just test to see if 'this' is now an instance of our class. If it's not, it means the user has omitted the 'new' keyword, so we do it for them. John Resig has an example of this over on his blog.

This is all very well and good, but I don't think we should use it. The reason is that we're hiding a pseudo syntax error from the developer, instead of educating them with its correct usage. If we hide this mistake in each class we write, our unknowing developer will remain unknowing, and run into a wall when they repeat their mistake on classes that don't fix it for them.

Instead, I suggest the following:


function User(firstName, lastName) {
if (!(this instanceof User)) {
throw new Error("You must use the 'new' keyword to instantiate a new User");
}

this.name = firstName + " " + lastName;
}

The only difference of course is that we're throwing an Error instead of fixing the developer's mistake. The benefit is that their syntax won't actually work unless they write it correctly. This is good because our erstwhile developer is prompted to fix their code and understand why it was wrong. Better informed developers leads to better code.

Well, hopefully.

Sunday, 30 August 2009

Ext.decorate

Sometimes you want to override one of the methods in ExtJS that return a configuration object - let's use Ext.direct.RemotingProvider's getCallData as an example, which looks like this:


getCallData: function(t){
return {
action: t.action,
method: t.method,
data : t.data,
type : 'rpc',
tid : t.tid
};
}

Our aim is to add an 'authentication_token' property to the returned object. You could provide the full config object again in an override, but usually you're overriding to add, remove or change one or two properties and want to leave the rest unmolested. I used to find myself writing a lot of code with this pattern:


//just adds an authentication token to the call data, for context see this forum thread
(function() {
var originalGetCallData = Ext.direct.RemotingProvider.prototype.getCallData;

Ext.override(Ext.direct.RemotingProvider, {
getCallData: function(t) {
var defaults = originalGetCallData.apply(this, arguments);

return Ext.apply(defaults, {
authenticity_token: '<%= form_authenticity_token %>'
});
}
})
})();

All we're really doing here is adding 1 config item - an authenticity_token, but it takes a lot of setup code to make that happen. Check out Ext.decorate:


/**
* @param {Function} klass The constructor function of the class to override (e.g. Ext.direct.RemotingProvider)
* @param {String} property The name of the property the function to override is tied to on the klass' prototype
* @param {Object} config An object that is Ext.apply'd to the usual return value of the function before returning
*/
Ext.decorate = function(klass, property, config) {
var original = klass.prototype[property];
override = {};

override[property] = function() {
var value = original.apply(this, arguments);

return Ext.apply(value, config);
};

Ext.override(klass, override);
}

This lets us write the same override like this:


Ext.decorate(Ext.direct.RemotingProvider, 'getCallData', {
authenticity_token: '<%= form_authenticity_token %>'
});

Much nicer, we just tell it what we want with no need for unwieldy boilerplate code. This method doesn't actually exist in Ext (though it would be good if something similar did), but you could define it yourself as above to keep such code nice and dry.

Tuesday, 28 July 2009

Ext.ux.Printer - printing for any ExtJS Component

After my recent foray into printing grids with ExtJS, I realised I needed to print some trees too. Seeing as some of the work was already done for the Grid example, it made sense to create a common API for printing any Ext.Component. And thus Ext.ux.Printer was born:


var grid = new Ext.grid.GridPanel({ // just a normal grid });
var tree = new Ext.tree.ColumnTree({ // just a normal column tree });

Ext.ux.Printer.print(grid);
Ext.ux.Printer.print(tree);


Each of the above opens a new window, renders some HTML (just a big table really), prints it and closes the window - all client side with no server side code required. Although trees and grids represent data quite differently internally, we can use the same API on Ext.ux.Printer to print them both.

Ext.ux.Printer uses Renderer classes to cope with a specific xtype, and adding Renderers for other components is easy. At the moment Ext.grid.GridPanel and Ext.tree.ColumnTree are supported out of the box, but let's see how we'd add support for printing the contents of an Ext.Panel:


/**
* Prints the contents of an Ext.Panel
*/
Ext.ux.Printer.PanelRenderer = Ext.extend(Ext.ux.Printer.BaseRenderer, {

/**
* Generates the HTML fragment that will be rendered inside the <html> element of the printing window
*/
generateBody: function(panel) {
return String.format("<div class='panel-print'>{0}</div>", panel.body.dom.innerHTML);
}
});

Ext.ux.Printer.registerRenderer('panel', Ext.ux.Printer.PanelRenderer);

This is probably the simplest print renderer of all - we're simply grabbing the HTML from inside a the panel's body and returning it inside our own div. We subclassed Ext.ux.Printer.BaseRenderer, and in this case all we needed to do was provide an implementation for generateBody. Whatever this function returns is rendered inside the <body> tag of the newly-opened printing window.

Notice that we registered this renderer for all components with the xtype of 'panel'. Internally, Ext.ux.Printer examines the xtype chain of the component you pass it to print, and uses the first renderer that matches. As many Ext components inherit from Ext.Panel this can function as a catch-all renderer.

Here's how we'd use our new renderer:


var panel = new Ext.Panel({
html: {
tag: 'ul',
chidren: [
{tag: 'li', text: 'Item 1'},
{tag: 'li', text: 'Item 2'},
{tag: 'li', text: 'Item 3'}
]
}
});

Ext.ux.Printer.print(panel);

Pretty straightforward. You can now print Ext.Panels the same way you'd print a Grid or a Tree. Take a look at the Grid Renderer and the ColumnTree Renderer for examples of rendering more advanced components.

As usual, all of the Ext.ux.Printer source is available on Github, and the README file there contains instructions for installation and usage.

Finally, when the printing window is opened it includes a stylesheet that it expects to find at "/stylesheets/print.css". There is a default print.css stylesheet included with the extension to get you started, and you can specify where to find this stylesheet like this:


Ext.ux.Printer.BaseRenderer.prototype.stylesheetPath = '/path/to/print/stylesheet.css';

ExtJS grid page size - letting the user decide

Sometimes you'll be using a Paging Toolbar on a grid and need to give the user the ability to change the number of records per page. One way of doing this is by adding a combobox to the toolbar:


var combo = new Ext.form.ComboBox({
name : 'perpage',
width: 40,
store: new Ext.data.ArrayStore({
fields: ['id'],
data : [
['15'],
['25'],
['50']
]
}),
mode : 'local',
value: '15',

listWidth : 40,
triggerAction : 'all',
displayField : 'id',
valueField : 'id',
editable : false,
forceSelection: true
});


We've set up a simple combo box which allows the user to choose between 15, 25 and 50 records per page. Now let's set up a Paging Toolbar, and a listener to take action when the user changes the selection in the combo box:


var bbar = new Ext.PagingToolbar({
store: store, //the store you use in your grid
displayInfo: true,
items : [
'-',
'Per Page: ',
combo
]
});

combo.on('select', function(combo, record) {
bbar.pageSize = parseInt(record.get('id'), 10);
bbar.doLoad(bbar.cursor);
}, this);


Finally we'll roll it all together into a Grid:


var grid = new Ext.grid.GridPanel({
//your grid setup here...

bbar: bbar
});


If the user needs to be able to enter her own page size, replace the ComboBox with an Ext.form.NumberField, and attach the event listener to the field's 'keypress' event.

Sunday, 26 July 2009

Printing grids with Ext JS

Grids are one of the most widely used components in Ext JS, and often represent data that the user would like to print. As the grid is usually part of a wider application, simply printing the page isn't often a good solution.

You could attach a stylesheet with media="print", which hides all of the other items on the page, though this is rather application-specific, and a pain to update. It would be far better to have a reusable way of printing the data from any grid.

The way I went about this was to open up a new window, build a table containing the grid data into the new window, then print it and close. It's actually pretty simple, and with a bit of CSS we can even get the printable view looking like it does in the grid.

Here's how you use it (this is a slightly modified version of the Array Grid Example):


var grid = new Ext.grid.GridPanel({
store : store,
columns: [
{header: "Company", width: 160, dataIndex: 'company'},
{header: "Price", width: 75, dataIndex: 'price', renderer: 'usMoney'},
{header: "Change", width: 75, dataIndex: 'change'},
{header: "% Change", width: 75, dataIndex: 'pctChange'}
{header: "Last Updated", width: 85, dataIndex: 'lastChange', renderer: Ext.util.Format.dateRenderer('m/d/Y')}
],
title:'Array Grid',
tbar : [
{
text : 'Print',
iconCls: 'print',
handler: function() {
Ext.ux.GridPrinter.print(grid);
}
}
]
});


So we've just set up a simple grid with a print button in the top toolbar. The button just calls Ext.ux.GridPrinter.print, which does all the rest. The full source code that this example was based upon can be found at http://extjs.com/deploy/dev/examples/grid/array-grid.js.

The source for the extension itself is pretty simple (download it here):



If you look at the source above you'll see it includes a 'print.css' stylesheet, which can be used to style the printable markup. The GridPrinter expects this stylesheet to be available at /stylesheets/print.css, but this is easy to change:


//add this before you call Ext.ux.GridPrinter.print
Ext.ux.GridPrinter.stylesheetPath = '/some/other/path/gridPrint.css';

Finally, here is some CSS I've used to achieve a grid-like display on the printable page:


html,body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,form,fieldset,input,p,blockquote,th,td{margin:0;padding:0;}img,body,html{border:0;}address,caption,cite,code,dfn,em,strong,th,var{font-style:normal;font-weight:normal;}ol,ul {list-style:none;}caption,th {text-align:left;}h1,h2,h3,h4,h5,h6{font-size:100%;}q:before,q:after{content:'';}

table {
width: 100%;
text-align: left;
font-size: 11px;
font-family: arial;
border-collapse: collapse;
}

table th {
padding: 4px 3px 4px 5px;
border: 1px solid #d0d0d0;
border-left-color: #eee;
background-color: #ededed;
}

table td {
padding: 4px 3px 4px 5px;
border-style: none solid solid;
border-width: 1px;
border-color: #ededed;
}

This technique could easily be adapted to print any component that uses a store - DataViews, ComboBoxes, Charts - whatever. It just requires changing the generated markup and stylesheet.

Friday, 24 July 2009

Ext.override - Monkey Patching Ext JS

Ext JS contains a function called Ext.override. Using this function allows you to add functionality to existing classes, as well as override properties of the class. For example, let's say we want to override how Ext.Windows are hidden:


Ext.override(Ext.Window, {
hide: function() {
//the contents of this function are now called instead of the default window hide function
}
});

Using Ext.override changes the prototype of the class you are overriding - all instances of Ext.Window will now use the new hide function in the example above.

Overriding other classes can be dangerous, especially when they are classes from a library not under your control. For example, if the Ext.Window class was refactored in a later version, your overrides may no longer work. In some situations you might choose to go down the safer route of augmenting the existing functionality without overriding it. Here's one way we can achieve this using a closure:


(function() {
var originalHide = Ext.Window.prototype.hide;

Ext.override(Ext.Window, {
hide: function() {
//perform pre-processing
alert("The window is about to close!");

//call the original hide function
originalHide.apply(this, arguments);

//perform post-processing.
alert("The window closed!!1");
}
});
})();

In the example above we set up a closure via an anonymous function which is executed immediately. This lets us keep a reference to the original hide function on Ext.Window. Underneath we perform the override itself, in which we provide our own logic.

The originalHide.apply(this, arguments) line is key to maintaining Ext.Window's original functionality. By using the apply keyword with the Window's usual scope ('this') and the function's arguments 'array', we can wrap our functionality before or after the original method.

Augmenting in this way is safer than simply overwriting the function, or copy & pasting Ext.Window's original hide function into your own, as you don't have to worry about breaking what Ext JS itself does (you're still responsible for making sure your own additions work after upgrading Ext though).

Be aware that this will affect all instances of Ext.Window (or whatever class you are overriding). If that isn't what you want, use Ext.extend to create your own subclasses instead.

Finally, note that you can use Ext.override on any class, not just the built-in Ext ones - all it does internally is call Ext.apply on the constructor function's prototype.

Thursday, 23 July 2009

Ext JS iterator functions

Ext JS has a number of handy iterator functions. Some, like Ext.each, you probably already know about, but there are a few others lurking around which can be useful in saving yourself a few lines of code. First, let's recap Ext.each:

Ext.each


Ext.each applies a function to each member of an array. It's basically a more convenient form of a for loop:

var people = ['Bill', 'Saul', 'Gaius'];

//using each to detect Cylons:
Ext.each(people, function(person, index) {
var cylon = (index + 1) % 2 == 0; //every second man is a toaster
alert(person + (cylon ? ' is ' : ' is not ') + 'a fraking cylon');
});

//is the same as
for (var i=0; i < people.length; i++) {
var person = people[i];
var cylon = (index + 1) % 2 == 0; //every second man is a toaster

alert(person + (cylon ? ' is ' : ' is not ') + 'a frakin cylon');
};

Ext.iterate


Ext.iterate is like Ext.each for non-array objects. Use it wherever you would normally use a for .. in loop:

var ships = {'Bill': 'Galactica', 'Laura': 'Colonial One'};

Ext.iterate(ships, function(key, value) {
alert(key + "'s ship is the " + value);
});

//is the same as
for (key in ships) {
var value = ships[key];
alert(key + "'s ship is the " + value);
}

Using Ext.iterate with an array is the same as calling Ext.each. Each and Iterate both take an optional third parameter, which is the scope to run the function in. Another advantage over using the for construct is that you can easily reuse the same function:


var myFunction = function(item, index) {
//does some clever thing
}

Ext.each(people, myFunction);
Ext.each(['another', 'array'], myFunction);

Ext.pluck


Ext.pluck grabs the specified property from an array of objects:


var animals = [
{name: 'Ed', species: 'Unknown'},
{name: 'Bumble', species: 'Cat'},
{name: 'Triumph', species: 'Insult Dog'}
];

Ext.pluck(animals, 'species'); //returns ['Unknown', 'Cat', 'Insult Dog']
Ext.pluck(animals, 'name'); //returns ['Ed', 'Bumble', 'Triumph']

Ext.invoke


Invoke allows a function to be applied to all members of an array, and returns the results. Using our animals object from above:


var describeAnimal = function(animal) {
return String.format("{0} is a {1}", animal.name, animal.species);
}

var describedAnimals = Ext.invoke(animals, describeAnimal);
console.log(describedAnimals); // ['Ed is a Unknown', 'Bumble is a Cat', 'Triumph is a Insult Dog'];

Ext.invoke performs a similar job to Ruby's collect method in making it easy to transform arrays. Any additional arguments passed to the Ext.invoke call will be passed as arguments to your function, in this case the describeAnimal function. Obviously your functions will be much more grammatically accurate than mine.

Ext.partition


Ext.Partition splits an array into two sets based on a function you provide:

var trees = [
{name: 'Oak', height: 20},
{name: 'Willow', height: 10},
{name: 'Cactus', height: 5}
];

var isTall = function(tree) {return tree.height > 15};

Ext.partition(trees, isTall);

//returns:
[
[{name: 'Oak', height: 20}],
[{name: 'Willow', height: 10}, {name: 'Cactus', height: 5}]
]

The partition call above returns a 2-dimensional array with the first element containing all of the items for which the function returned true (tall trees in this case), and the second containing items for which the function return false.

Math functions


Finally, we have some simple math-related functions:

var numbers = [1, 2, 3, 4, 5];
Ext.min(numbers); //1
Ext.max(numbers); //5
Ext.sum(numbers); //15
Ext.mean(numbers); //3

While the built in functions don't cater for all situations, they're useful to have and to know about, and usually offer a more elegant approach than using the 'for' keyword.