Warning: This preview has breaking changes from our released version. Make sure to use our new Angular JS Integration API.
We have been getting quite a few requests lately to add AngularJS support to Wijmo. As you may know, we recently added Knockout support to wijmo and have had great success with this new coupling. We took a very similar approach with AngularJS. We have created an optional library that exposes all of wijmo's widgets as AngularJS components. The AngularJS Integration Library creates a declarative for each widget and parses the component markup to create the options. It turned out to be quite a clean solution. We wanted to get feedback on our component concept, so we are making a Preview version available for download. The preview is included in Wijmo 2.3.2 and you can access the demo apps inside this folder location: Wijmo-Complete/development-bundle/demo-apps/using-angular/ and the library here: Wijmo-Complete/development-bundle/external/angular.wijmo.js. We have also published our demos online: basic usage & collections.
Using Wijmo's AngularJS Components
Before we begin, I highly recommend that you take a look at Angular's documentation to learn a little more about it. It takes a bit of reading to fully understand how everything works.
Add References
First, you will need to reference the necessary scripts.
<!-- jQuery -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js" type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.9.1/jquery-ui.min.js" type="text/javascript"></script>
<!-- Wijmo CSS and script -->
<link href="http://cdn.wijmo.com/themes/metro/jquery-wijmo.css" rel="stylesheet" title="metro-jqueryui" type="text/css" />
<link href="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.3.1.min.css" rel="stylesheet" type="text/css" />
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.2.3.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.3.1.min.js" type="text/javascript"></script>
<!-- Angular (after jQuery) -->
<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/external/angular.wijmo.js"></script>
Create a Model & Controller
Now we need to create a Model & Controller. This is not a real world Controller, but you can see the basic usage here. The Controller provides data context to the Model via the $scope and $local params. We also need to declare our app and add a dependency on the wijmo directives.
var app = angular.module("my-app", ["wijmo"]);
function ViewModel($scope, $locale) {
$scope.val = 50;
$scope.min = 0;
$scope.max = 100;
}
Create the Markup
Next we add some custom markup to our document. We need to define this document as an Angular app like so:
<html ng-app="my-app">
And then scope our Controller to a DOM element. In this case we will use the body so that anything inside of it will have access to the Model.
<body ng-controller="ViewModel">
Lastly, we create our component markup. If you have ever used a server control (like in ASP.NET for example) this will look very familiar to you. We actually have a method that looks at all of the markup's elements and attributes and parses them as a widget and options. Here is our page that has plain old input and span elements as well as a Wijmo Slider and a Wijmo Linear Gauge Component.
<h2>Textbox</h2>
<input ng-model="val" style="width: 200px;" />
<span>{{val}}</span>
<h2>Slider</h2>
<wijslider value="{{val}}" min="{{min}}" max="{{max}}" style="width: 200px;">
</wijslider>
<h2>Gauge</h2>
<wijlineargauge value="{{val}}" min="{{min}}" max="{{max}}">
</wijlineargauge>
Notice that the Input uses an ng-model attribute that binds it to our Model. While the span and Wijmo Components use {{model}} binding syntax. Any of Wijmo's widgets can be used with this syntax. Our library just expects you to name the HTML elements using the widget name. Then you can just set attributes and child elements to define options and event handlers for the widget. Now run the app (or look at it online) and change the input value or slider value and notice that all of the UI bound to our Model automatically updates. The beauty is that (similar to Knockout) we did not have to write any code specific to change event handling! If you want, you can play around with our samples on JSBin too. Here are the JSBin samples for basic usage (slider and gauge) and collections (grid and chart)
Summary
AngularJS is definitely a powerful framework for building applications. It also has a really nice directive model for creating reusable Components. Another thing that is really cool about this techniqie is that it will be have native browser support soon. For more on this subject see the Web Components specification. AngularJS certainly is nice, but my heart still lies with Knockout. I personally feel that Knockout is an easier way of structuring and binding inside applications. It definitely has an simpler learning curve than Angular. But as I said, AngularJS is more powerful and forward thinking. I recommend you download Wijmo and try both out! We have these same demos both using Knockout and Angular. See this folder in our download to try the demos: Wijmo-Complete/development-bundle/demo-apps/using-angluar.
Chris Bannon