Introducing Wijmo, A Feature-Packed jQueryUI Based Widget Library

Lately I have been evaluating a few JavaScript based UI libraries for both my projects at work and to use for a new version of the bike climbs site called 39x27.com:  it was quite nice to see that almost all component vendors are now embracing, some more than others, JavaScript together with the more traditional Web Controls for ASP.NET Web Forms.

In this post I’m going to briefly cover the reasons why I ended up choosing Wijmo, and then I’m giving a quick introduction on the set of widgets available.

Why Wijmo?

My first, and only strict requirement was that it had to be based on jQuery: everybody in my team knows it, it is the more used JavaScript library, so new developers and contractors coming are likely to know it, and ASP.NET MVC and the ASP.NET Single Page Application depends on it (see, ASP.NET MVC validation, Knockout.js, upshot.js). That excluded libraries like ExtJS.

All the buzz lately is about KendoUI, a jQuery-based UI widget library developed by Telerik, so it was the first library I looked at: it’s based on jQuery, and is available also with a OSS license (GPLv3). It has lots of widgets, both for web UI element and for drawing charts and they are developing also some mobile UI controls. And it’s use feels natural, looks like jQueryUI: you create a HTML element, you select it via jQuery and then enhance it via a KendoUI specific JavaScript  function.

What I didn’t like is that they reinvented the wheel: one line above I wrote "looks like jQueryUI" because it is not built on jQueryUI; Telerik wrote its own widget core library. This might be ok for people that are using other Telerik controls or are ok with vendor lock-in, but I didn’t like this approach that much: what if I need a widget that is not available? Either I write mine from scratch using the KendoUI core library, or I look on the internet, and include also jQueryUI in the mix, since most likely the OSS widget I find is built on it.

I looked for something else, and my second option was Infragistics jQuery controls: apart from having less controls, costing more money and not having the double commercial/OSS license, it is also built on top of their own core widgeting framework. So, another no-go.

Finally, while discussing my findings on twitter, I received a message from Richard Dudley, a developer evangelist from ComponentOne, which suggested I take a look at their jQuery widget library, named Wijmo. After a quick look at the site I realized this was exactly what I was looking for: a JS control library built on top of jQueryUI. Not only that, but also it has a lot of widgets, including the editable grid, a Google Calendar like planner calendar, a WYSIWYG editor, and also some multimedia elements more suited for frontends rather than backend apps, like image gallery, lightbox and also a HTML5 video player.

The great thing of being based on jQueryUI is that you can use all the jQueryUI themes, and if you need something not included in the library you can include any other jQueryUI widget without the risk incompatibilities between widgeting frameworks.

From the license stand point it is similar to KendoUI: it is available both with GPLv3 license and a commercial license. And a "light" version of Wijmo, including only the basic controls, is also available with a MIT/GPLv2 license, making it usable also in OSS projects that are not GPLv3.

I also wrote a features comparison table between the widgets you get with Wijmo Open, Wijmo Complete, KendoUI and with jQueryUI. (based on Wijmo v2 and Kendo UI as available in February 2012)

See it in external window here.

Getting started with Wijmo

Let’s now quickly see how it looks like developing with Wijmo.

Download the bits

Hit the Wijmo website, and download the JavaScript library: it comes bundled with samples for every widget, complete sample apps, normal and minified version of all the JavaScript files, and all the premium themes. This is the best way to start playing with Wijmo. If you want you can also use ComponentOne CDN and reference all JavaScript files from there.

Referencing the libraries

As said above, Wijmo is based on jQueryUI, which is based on jQuery, so in order to include Wijmo you have to reference all of them.

The easiest approach is using ComponentOne CDN, which provides a minified version of the JS libraries and their CSS.

<!--jQuery References-->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"
     type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.17/jquery-ui.min.js"
     type="text/javascript"></script>

<!--Theme-->
<link href="http://cdn.wijmo.com/themes/midnight/jquery-wijmo.css"
     rel="stylesheet" type="text/css" title="midnight-jqueryui" />

<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.css"
     rel="stylesheet" type="text/css" />

<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.2.0.0.min.js"
     type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.js"
     type="text/javascript"></script>

Or, if you want to host the script files locally on your server you can also select the files you just need for your application: you can do that by checking the dependencies of each widget (for example the dependencies of the Rating control)

Adding a Rating Control

Let’s see now how add a Wijmo widget to a page: I’ll use a rating control, but the process is the same also for most of the other widgets.

After having added the references, let’s add the HTML element we want to use for the widget: it this case, we can use either a list of radio button, a select, or just an empty div. Choosing a form element makes it easy to store the rating value directly, while if you choose an empty div you have store the value yourself. In this case I’m going to use a select list.

<select id="climbRating">
    <option value="1">Easy</option>
    <option value="2">Average</option>
    <option selected="selected" value="3">Tough</option>
    <option value="4">Very Tough</option>
    <option value="5">Hors Categorie</option>
</select>

Finally, inside a script tag, initialize the rating widget like you would do with any other jQueryUI widget:

<script>
    $(document).ready(function () {
        $('#climbRating').wijrating();
    });
</script>

And you’ll have nice rating control with a reset button to clean the value and tooltips.

Fine-Tuning the Appearance of The Widget

Probably you might want to customize the appearance of the rating widget, like removing the reset button, or maybe enabling multiple values per star, or changing the icons  instead of using the stars. To do that just specify the properties when you call the wijrating method:

<script>
    $(document).ready(function () {
        $('#climbRating').wijrating({
            resetButton: {disabled: true},
            icons: {iconsUrl:
                        ["flat.jpg", "hilly.jpg", "steep.jpg",
                        "steeper.jpg", "vertical.jpg"]
                    }
        });
    });
</script>

The Editable Grid

Let’s see now a more complicate widget: the editable/sortable/pageable grid.

The hook in HTML is simple: just add an empty table if you want to load the data from a JavaScript datasource, either local or remote via JSON, or a normal table with all the data already in tabular form.

<table id="climbsTable"></table>

Then, as usual, via jQuery, you enhance the table by calling the wijgrid method. In this post I’m just going to show the basic features, how to pass local data, and how to enable sorting and some other basic formatting options. In a future article I’ll show how to use it in a ASP.NET MVC application with Web API. This code is taken from a prototype of the new version of a bike climbing web site I’m building with my friend Davide Vosti, called 39x27.com.

$(document).ready(function () {
    $("#climbsTable").wijgrid({
         data: [
            { 
                Name: "Passo dello Stelvio",
                Location: "Prato dello Stelvio (IT)",
                Rating: "Hors Categorie",
                Rate: 0.074,
                Length: 24.3,
                Elevation: 1808
            },
            ...
          ],
          allowSorting: true,
          columns: [
                {},
                {},
                {},
                { dataType: "number", dataFormatString: "p1" },
                { dataType: "number" },
                { dataType: "number", dataFormatString: "n0" }
            ]
    });
});

The first property is called data and is the one that defines how the grid is populated: it could be an array of array, an array of objects (like I did in the sample above) or wijmo datasource if you wanted to get the data from a server.

In the sample I then enabled sorting, and later provided an array of columns: the first 3 are empty because I want to use the default values (header is the property name of the JSON object provided and the data type is string), but in the next 3 I specified the data type and the format of the string: the data formats us the same format of jQuery Globalize, so p1 means percentage with 1 decimal while n0 means generic number with no decimals.

Here is the table with the list of the bike climbs.

All the details can be found in the API documentation available online: Wijmo Grid documentation.

In Conclusion

In a few words, what I liked the most about Wijmo is its philosophy of embracing what is already available (jQueryUI) and most likely already well know by developers rather than reinventing the wheel and bringing yet another library in the mix like the other component vendors are doing.

In second instance, what is great is that they provide not just web-apps oriented components like the editable grid or the event calendar or the datepicker, but they also have some great charting widgets and  widgets that can be used also in "web sites", like the carousel, the lightbox and the HTML5 video player.

Disclosure of Material Connection: I received one or more of the products or services mentioned above for free in the hope that I would mention it on my blog. Regardless, I only recommend products or services I use personally and believe my readers will enjoy. I am disclosing this in accordance with the Federal Trade Commission’s 16 CFR, Part 255: "Guides Concerning the Use of Endorsements and Testimonials in Advertising."