Wijmo 5 Control Architecture

August 28 2014

Wijmo 5 is a set of JavaScript Controls, not to be confused with Widgets. Previously, we were able to utilize Widget frameworks like jQuery UI and jQuery Mobile. This saved us time in building a foundation and gave us what we needed at the time. But when we wanted to build a more modern Wijmo, we decided it was time to rethink JavaScript UI components, especially the syntax and API. After a lot of research and debate, we came to what we call "true JavaScript Controls." What do I mean by "true JavaScript Controls?" I mean UI components nearly identical to what you would find in .NET.aspx) with common API for Properties, Methods and Events. We chose IE9 as our baseline for browser support in Wijmo 5, and that opened up the ability for us to create our new Control architecture. IE9 supports ECMAScript 5, and that is the key to our architecture.

ECMAScript 5 Controls

Our architecture is fairly straight forward for Controls that use ECMAScript 5. We are using TypeScript for our source, which has made things very easy. We created a Base Control Class using TypeScript and all of our Controls inherit from the Base Control. Controls are also class-like in JS. They are capitalized and offer constructors for initialization as well as Properties, Methods and Events. Controls can be initialized like so:

 //Initialize a FlexGrid instance for a single DOM element  
 var myFlexGrid = new wijmo.grid.FlexGrid('#FlexGrid1');

Properties

We utilize [Object.defineProperty()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) in our ES5 Controls. This is really the key to making .NET-like Controls in JS. It allows us to define getters and setters for properties. So our Controls support direct property assignment while allowing us to handle the value change and apply logic as needed. Setting properties on a Control is as simple as assigning it a value. No function call or strings used here! Setting a property on a Control can be done like so:

//Enable editing in FlexGrid  
myFlexGrid.isReadOnly = false;

While this is a simple property assignment, we still get to do things in the Control when you set it (thanks to Object.defineProperty). For example, we know to attach event handlers to cells for editing when you set the above property. We can also check to ensure the property exists and assert that a valid value has been assigned. If you are using an IDE that supports it, you will also get auto-completion (IntelliSense) for our Control properties. This is a huge benefit when using and learning Controls. For convenience, we also offer some Enums for properties that have enumerated options. These just map to index values. The index value can also be assigned to the property. Set an enumerated property like so:

//Set the selection mode in the FlexGrid  
myFlexGrid.selectionMode = wijmo.grid.SelectionMode.CellRange;

Properties can also be accessed just like on standard JS Objects. You can get property values on Controls like so:

//Check if FlexGrid is editable  
var readOnly = myFlexGrid.isReadOnly;

If you are a .NET developer, I assume things are looking pretty familiar to you. Even as a JS developer, I am really happy to see such a nice API for working with Controls. Let's also take a quick look at how properties are assigned in Widgets for comparison. Here is how you enabled editing in the Wijmo Grid Widget:

//Enable editing in Wijmo Grid Widget  
$('#WijmoGrid1').wijgrid('option', 'allowEditing', true);

We jokingly refer to this syntax as "stringly typed programming." Don't get me wrong, this pattern works and has helped us a lot. But it is terrible syntax and very error prone. Using case-sensitive strings to set properties is likely to cause mistakes. Also, if you mistype a named option, you will not get an error. It will just add it to the option object in the widget and you will never know the error occurred.

Methods

Methods are very straightforward in Wijmo 5 and are simply called as functions from the Control. Call a method on a Control like so:

//Refresh the FlexGrid, causing a re-layout and redraw  
myFlexGrid.refresh();

Compare this to the JS Widget syntax for calling methods.

//Refresh the Wijmo Grid Widget  
$('#WijmoGrid1').wijgrid('doRefresh');

Again, working with strings instead of calling functions directly is asking for error.

Events

Events in Wijmo 5 Controls are also modeled after .NET Controls. You simply call addHandler on the event property of the Control. You can attach an event to a Control like so:

//Handle cell edit completion in FlexGrid  
myFlexGrid.cellEditEnded.addHandler(function (sender, args) {  
//Do something  
});

Similarly, you can call removeHandler to unsubscribe from the event. Compare this to the JS Widget syntax for attaching events.

//Handle cell edit completion in Wijmo Grid Widget  
$('#WijmoGrid1').bind('wijgridaftercelledit', function (e, args) {  
//Do something  
});

Again, we are working with strings and a very specific pattern. This is also error prone, but it is more comfortable to JavaScript developers since bind has become so commonly used in jQuery. Of all of the quirks in JS Widgets, this one is least offensive. I hope you can see how nice the API and syntax are for the Wijmo 5 Controls. We believe they are a major improvement over classic JS Widget syntax. Widgets are great and have had their day. But now it's time to start building true Controls in JavaScript. Luckily, ECMAScript 5 makes this possible.