JavaScript Framework Evaluation (Proposal.JavaScriptFrameworkEvaluation)

Also note that ShadowDOM (part of "Web Components") which allows creating new HTML elements) is a competitor to AngularJS's directives but [[they are actually compatible>>http://www.binpress.com/blog/2014/06/26/polymer-vs-angular/]]. Thus in a near future we'll be able to use AngularJS which Web Components which is very nice.

17

18

Discussions found on the web comparing them:

19

20

* http://eviltrout.com/2013/06/15/ember-vs-angular.html

21

* http://www.quora.com/Client-side-MVC/Is-Angular-js-or-Ember-js-the-better-choice-for-Javascript-frameworks

22

* http://readwrite.com/2014/02/06/angular-backbone-ember-best-javascript-framework-for-you

23

24

Experiments inside XWiki:

25

26

* With EmberJS: [[http:~~/~~/extensions.xwiki.org/xwiki/bin/view/Extension/AngularJSDemo>>doc:extensions:Extension.AngularJSDemo]] (source: https://github.com/xwiki-contrib/application-emberjs-todolist and mail thread with explanations: http://markmail.org/message/ihg5t5qtbp5yfe6f)

27

* With AngularJS:

28

** https://github.com/xwiki-contrib/angular-rendering

29

** https://github.com/xwiki-contrib/application-angular-todo

30

** https://github.com/xwiki-contrib/application-angularjsdemo

== Github Stats ==

Angular comes out here as the clear winner, although backbone and ember should not be considered "risky" choices.

35

36

|=Framework|=Forks|=Contributors

|Angular|9627|916

|Backbone|4200|230

|Ember|2335|380

|Knockout|882|40

|Durandel|321|61

== AngularJS (1.x) ==

44

45

Can be loaded with RequireJS.

require.config({

paths: {

angular: '//ajax.googleapis.com/ajax/libs/angularjs/1.2.16/angular.min',

51

'angular-route': '//ajax.googleapis.com/ajax/libs/angularjs/1.2.16/angular-route.min',

52

'angular-resource': '//ajax.googleapis.com/ajax/libs/angularjs/1.2.16/angular-resource.min',

53

'angular-animate': '//ajax.googleapis.com/ajax/libs/angularjs/1.2.16/angular-animate.min'

},

shim: {

angular: {

exports: 'angular'

},

'angular-route': {

deps: ['angular'],

exports: 'angular'

},

'angular-resource': {

deps: ['angular'],

exports: 'angular'

},

'angular-animate': {

deps: ['angular'],

exports: 'angular'

}

}

});

require(['angular', 'angular-route', 'angular-resource', 'angular-animate'], function(angular) {

75

// Define a new module and specify its dependencies.

76

var myApp = angular.module('myApp', [

'ngRoute',

'myAppControllers',

'myAppFilters',

'myAppServices',

'myAppAnimations']);

...

});

We can load it also from a WebJar.

87

88

89

require(["$services.webjars.url('angularjs/1.2.16/angular.js')"], function() {

90

var myApp = angular.module('myApp', []);

...

});

It can initialize itself automatically on page load if it finds an element marked with the ##ng-app## attribute (the element that wraps the application UI):

...

</div>

but it can also be lazy loaded:

104

105

106

angular.bootstrap($('#myAppContainer')[0], ['myApp']);

107

108

109

It has its own **Dependency Injection** mechanism but it injects dependencies that have already been loaded on the client. So it doesn't fetch scripts dynamically. This means we can use RequireJS to fetch Angular modules from the server dynamically and then use Angular's DI to inject them in our application.

110

111

Angular was designed for single-page applications. You have a layout template with an area (the view) that changes with the URL. Since the page is never reloaded, when the view is changed only the document fragment part of the URL is changed. This means the views are still bookmarkable (and Back/Forward buttons work). We can map URLs (actually document fragments) to views.

112

113

114

phoneApp.config(['$routeProvider', function($routeProvider) {

115

$routeProvider.when('/phones', {

116

templateUrl: new XWiki.Document('ListView', 'Phone').getURL('get'),

117

controller: 'PhoneListCtrl'

118

}).when('/phones/:phoneId', {

119

templateUrl: new XWiki.Document('DetailView', 'Phone').getURL('get'),

120

controller: 'PhoneDetailCtrl'

121

}).otherwise({

122

redirectTo: '/phones'

});

}]);

The '/phone' part actually translates to ##xwiki/bin/view/Space/Page#/phones##. A small issue is that the usage of '$' (in ##$routeProvider##) can lead to problems if the JavaScript code is parsed for Velocity. An important limitation is that you can have only one view currently displayed (this may change in Angular 2.x). So we can't have sibling or nested views. The view is marked with the ##ng-view## empty attribute:

128

129

130

131

132

133

134

</div>

135

136

137

138

Views are defined by 'templates' that are evaluated on the client. The syntax used is HTML with custom ##ng*## attributes and a [[handle-bars ##~~{~~{value}}##>>http://handlebarsjs.com/]]-like syntax. We can write the Angular templates in wiki pages but the handle-bars notation clearly prevents us from using the wiki syntax. We have to use the HTML macro:

<li ng-repeat="phone in phones | filter:query | orderBy:fieldToOrderBy:reverse"

144

class="thumbnail phone-listing">

</a>

<a href="#/phones/{{phone.id}}">{{phone.name}}</a>

149

<p>{{phone.snippet}}</p>

</li>

</ul>

Note that we can ensure strict (X)HTML5 validity by prefixing the custom Angular attributes with ##data-## (e.g. ##data-ng-src##). In a template we can display or interact with data from the **scope**. The scope is very similar to the Velocity context. Think how we can put all kinds of objects on the Velocity context and then access them from the Velocity templates. One difference is that in Angular we can have nested scopes which inherit from one another. Everything that is put on the scope is considered to be the **model**. So the model can be any type of data, from primitive types to complex objects. The JavaScript code that puts data on the scope is the **controller**. Each view has a controller for instance that decides what data is displayed by that view.

156

157

158

myApp.controller('todoCtrl', ['$scope', function($scope) {

159

$scope.todos = [

160

{

161

text: 'Learn the XWiki API',

162

done: true

163

}, {

164

text: 'Create an XWiki application',

done: false

}

];

}]);

There is a two-way binding between the model and the view. Angular listens to DOM events and updates the model whenever needed. Changes to the model done from within the Angular code (e.g. from the controller) are reflected automatically in the view. Angular detects which objects have been modified using what is called 'dirty-checking'. This aproach has some performance limitations when the model is big (lots of complex objects) but the Angular team has some fixes planed for 2.x.

172

173

There is a simple way to store the view state in the URL. In other words we can have bookmarkable views. This is needed for instance if we want to implement the live table using Angular. The live table state (filter values, sort column, sort order) is currently saved in the URL hash (document fragment). We can achieve the same with Angular, without interfering with the route path.

<option value="name">Alphabetical</option>

179

<option value="age">Newest</option>

</select>

myApp.controller('MyAppCtrl', ['$scope', '$location', function ($scope, $location) {

185

$scope.sortColumn = $location.search().sortColumn || 'age';

186

$scope.saveSortColumn = function() {

187

$location.search('sortColumn', $scope.sortColumn);

};

}]);

/xwiki/bin/view/Space/Page#/phones?sortColumn=name

194

195

196

The declaration of behaviour directly in HTML (##ng-click##, ##ng-change##) doesn't look very good though. Our practice has been to avoid in-line JavaScript code and to use behavioural CSS classes (e.g. ##withTip##). Fortunately we can implement them using directives (e.g. a custom attribute that adds behaviour to an element).

197

198

Angular offers a nice mechanism to control how data is displayed, called **filters**. This is in some ways similar to our property displayers.

199

200

201

<dd>{{phone.connectivity.gps | checkmark}}</dd>

myApp.filter('checkmark', function() {

206

return function(input) {

207

return input ? '\u2713' : '\u2718';

};

});

We can package and expose business logic as **services**. Angular comes with a bunch of useful services, like ##$http## which can be used to make AJAX requests. We can use the ##$resource## service to wrap (query/post) REST resources or anything that generates JSON on the server (a wiki page for instance).

213

214

215

myApp.factory('Page', ['$resource', function($resource) {

216

// The colon ':' is URL-encoded so we must decode it otherwise Angular won't find the parameters.

217

var url = new XWiki.Document(':page', ':space', ':wiki').getRestURL().replace('/%3A', '/:');

218

return $resource(url);

219

}]);

220

...

221

myApp.controller('MyAppCtrl', ['$scope', 'Page', function ($scope, Page) {

222

$scope.page = Page.get({

wiki: 'xwiki',

space: 'Sandbox',

page: 'WebHome'

});

}]);

Angular offers a way to reuse UI elements (widgets) or to enhance DOM elements with reusable behaviour by packaging them as **directives**. Directives can be used as custom HTML elements, custom HTML attributes, CSS class as well as comments.

<my-dir></my-dir>

We can create for instance a custom ##livetable## HTML element using directives.