Typesafe Activator

The Play Angular Seed Project

The Play Angular Seed Project

typesafehub
Source
July 14, 2014
angularjs playframework javascript webjars requirejs meta-template scala

This is a Play version of the official angular-seed project (https://github.com/angular/angular-seed). The project uses Play's requirejs support for WebJars (http://www.webjars.org/).

How to get "The Play Angular Seed Project" on your computer

There are several ways to get this template.

Option 1: Choose angular-seed-play in the Typesafe Activator UI.

Already have Typesafe Activator (get it here)? Launch the UI then search for angular-seed-play in the list of templates.

Option 2: Download the angular-seed-play project as a zip archive

If you haven't installed Activator, you can get the code by downloading the template bundle for angular-seed-play.

  1. Download the Template Bundle for "The Play Angular Seed Project"
  2. Extract the downloaded zip file to your system
  3. The bundle includes a small bootstrap script that can start Activator. To start Typesafe Activator's UI:

    In your File Explorer, navigate into the directory that the template was extracted to, right-click on the file named "activator.bat", then select "Open", and if prompted with a warning, click to continue:

    Or from a command line:

     C:\Users\typesafe\angular-seed-play> activator ui 
    This will start Typesafe Activator and open this template in your browser.

Option 3: Create a angular-seed-play project from the command line

If you have Typesafe Activator, use its command line mode to create a new project from this template. Type activator new PROJECTNAME angular-seed-play on the command line.

Option 4: View the template source

The creator of this template maintains it at https://github.com/typesafehub/angular-seed-play#master.

Option 5: Preview the tutorial below

We've included the text of this template's tutorial below, but it may work better if you view it inside Activator on your computer. Activator tutorials are often designed to be interactive.

Preview the tutorial

AngularJS, WebJars, Play Framework

This tutorial describes the use of AngularJS, RequireJS and WebJars using the Play Framework. An overview will first be provided of each technology. You will then you guided through how to use these technologies with Play.

This tutorial will take you about 10 minutes. You will be pleasantly surprised with how little there is to be done when using Play and AngularJS, or JavaScript in general for that matter!

AngularJS

AngularJS lets you extend HTML vocabulary for your application. The resulting environment is expressive, readable, and quick to develop with. We have based this angular-seed-play project on the angular-seed project which is the official starting point when writing new AngularJS applications.

An advantage of using Play along with its RequireJS integration is that you will see a reduction in the code required when compared with the original angular-seed project. The resulting code should also be easier to maintain given the management of library versions.

RequireJS

RequireJS is a popular implementation of the AMD specification - a means by which JavaScript applications can be modularised. The easiest way of thinking about AMD is that it is JavaScript's equivalent of package and import statements (or namespace and include statements depending on your preferences!).

WebJars

WebJars are zip files containing HTML, CSS, images, JavaScript and other web resources along with a computer-readable description of the library.

Managing the versions and dependencies of JavaScript libraries is just as important as for any other language. Let's say that your favorite library is required and that it has a dependency on jQuery. Ordinarily you would be required to ensure that jQuery is loaded before your library otherwise there will be errors. When using your favorite library's WebJar, jQuery is declared as a dependency such that it will be loaded automatically.

These WebJars are deployed to well known repositories including Maven Central. There are many popular JavaScript libraries already available as WebJars and the number is increasing. WebJars utilize familiar and established repositories instead of relying on newly introduced ones. Many organisations are already using and hosting Maven and Ivy based repositories so it makes sense to leverage them. To further support this, over 8 billion downloads occurred on Maven Central in 2012.

JavaScript and Play

The first thing to state is that we want to make developing web applications in conjunction with Play as familiar as possible when it comes to authoring JavaScript. To use a WebJar the programmer declares its dependency in Play's build.sbt file. This file describes a Play project in a similar way that a Maven pom or NPM's package.json does.

In this application, the only explicit WebJar dependency in our client is AngularJS:

"org.webjars" % "angularjs" % "1.2.13"
WebJars can have transitive dependencies as well, and they will be managed in a familiar way that is similar to Maven, Ivy or Gradle dependencies. In the case of AngularJS there are no transitive dependencies. The webjars-play library does have a transitive dependencies on RequireJS and WebJars Locator, so there's no need to declare them explicitly.

Routes

The next requirement is to tell Play how assets are going to be resolved. Play's routes file is used to do this.

The following route exposes access to the WebJar assets:

GET    /*file    controllers.Assets.versioned(path="/public", file: Asset)

Setup

While not required, the easiest way to setup a webpage to use WebJars, RequireJS, and AngularJS is with Play's server-side templating.

The app.js file uses RequireJS to load AngularJS and setup the different parts of the application:

require(['angular', './controllers', './directives', './filters', './services', 'angular-route'],
  function(angular, controllers) {
The angular and angular-route references use the modules defined by the WebJars setup done in the previous sections. (angular-route is part of the angular WebJar). The other references that are prefixed with ./ are relative to the app.js file. If you add other WebJars to your dependency list in build.sbt, this generated setup script will have configuration entries for their contents as well.

JsLint Happiness

You'll notice a comment, /*global ... in the app.js file that tells JsLint what globals are assigned from other JavaScript files. Not having this declaration would result in warnings in our code.

Conclusion

This tutorial has taken you through the requirements of a Play application in order to use AngularJS, RequireJS and WebJars in the context of the Play Framework.

We intend to enhance the JavaScript development experience further with the goal of making Play the #1 choice for web development.

Happy Play-ing with AngularJS!

comments powered by Disqus