Wijmo Officially Supports AngularJS

July 25 2013

I am happy to announce that we have released official support for AngularJS in Wijmo. We have spent the recent months taking feedback on our preview and polishing our AngularJS Integration Library. As of Wijmo 2013 v2, we have shipped official support for AngularJS.

Using Wijmo’s AngularJS Components

To use our AngularJS directives, you will need to reference wijmo and include our Angular Integration Library (angular.wijmo.js).

<!-- jQuery -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js" type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
<!-- Wijmo CSS and script -->
<link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" title="metro-jqueryui" type="text/css" />
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20132.8.min.css" rel="stylesheet" type="text/css" />

<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20132.8.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20132.8.min.js" type="text/javascript"></script>

<!-- Angular -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.2/angular.min.js"></script>
<script src="http://cdn.wijmo.com/interop/angular.wijmo.3.20132.8.min.js"></script>

Now that you have the scripts loaded, you need to include the "wijmo" module. Here is an example:

var app = angular.module("my-app", ["wijmo"]);

After that, you can start using our AngularJS components.

Component Markup

One of the coolest parts of AngularJS is the custom markup used in Directives. If you have ever used custom Controls in other platforms (like ASP.NET, Silverlight, etc) then this markup will look very familiar to you. To use our components, you just need to map our existing JavaScript API to custom HTML markup.

Declaring Widgets

To create a widget, you can simply make an HTML element matching the widget name, and add a "-" after "wij". So if you want to use wijgrid, you would create a <wij-grid> element. Here is how grid would look:

<wij-grid>
</wij-grid>

This is the equivalent of:

<table id="grid"></table>

<script type="text/javascript">
$("#grid").wijgrid();
</script>

The beauty of the Angular approach is that you do not need to initialize the widget using JavaScript. You simply declare them in markup and they will automatically be initialized.

To set options on widgets, simply add attributes to the widget element you created. If the option is camel-cased, add a "-" right before the capitalized letter. So if we wanted to add sorting to our grid we would do the follow:

<wij-grid allow-sorting="true">
</wij-grid>

This is the equivalent of:

<table id="grid"></table>

<script type="text/javascript">
$("#grid").wijgrid({ allowSorting: true });
</script>

DataBound Options

Options can be bound to parts of the Model in your AngularJS application. Let's add a data source to our Grid and bind it to an array of airports in our Model.

<wij-grid allow-sorting="true" data="airports">
</wij-grid>

We could also apply a filter in this binding too. You can use binding expressions like this when binding our Components. The following will only take 10 items in the airports array when binding to the Grid.

<wij-grid allow-sorting="true" data="airports | limitTo:10">
</wij-grid>

Compound Options

If you need to set a compound option such as columns in Grid or seriesList in Chart, you simply add child elements that match the name of the nested option object. Let's look at how we can configure columns in our Grid.

<wij-grid allow-sorting="true" data="airports" columns-autogeneration-mode="none">
   <columns>
      <column data-key="code" header-text="Code"></column>
      <column data-key="city" header-text="City" width="180"></column>
      <column data-key="state" header-text="State" width="80"></column>
      <column data-key="name" header-text="Name" width="300"></column>
      <column data-key="pop2011" header-text="Population" format="n0" width="100"></column>
      <column data-key="vol2011" header-text="Traffic" format="n0" width="100"></column>
   </columns>
</wij-grid>

Here are the results of our Grid markup. You can follow this same pattern with all of our widgets. I recommend downloading Wijmo-Pro and looking at all of our Angular samples to get a feel for the markup. You can also see a live demo of this sample online in our AngularExplorer.

Breaking Changes from the Preview

We do have some small breaking changes from the Preview. These changes were all based on feedback we got during the Beta testing period.

Widget names now require the "-". So <wijgrid> is now <wij-grid>
Widget options should now use "-" to separate words in camelCase options. So allowSorting="true" is now allow-sorting="true".
Bracket bindings are only needed for one-way binding. Eg: {{airports}} is now just airports if you want two-way binding