collective.angularstarter (Plone + AngularJS + Yeoman kickstarter project)

Get started with Plone + AngularJS without any of the normal headaches associated with a manual setup of useful tools that let you improve your development experience and the deploy of your application.

Since I have been using AngularJS on Plone, I decided to create a reusable starter scaffold (or something or similar) based on Yeoman that let me save precious time.

That's why I created:

• https://github.com/collective/collective.angularstarter

This is a plugin that let you bootstrap single page web applications (or heavy Javascript logics) based on Plone+AngularJS+Yeoman.

Yeoman workflow benefits

collective.angularstarter is powered by the Yeoman workflow. If you want to see what are the Yeoman benefits due to an integration with a framework you might have a look at:

• Pyramid, Yeoman. On this link I deeply described the Yeoman benefits and its main components and tools (bower, grunt, etc)
• NodeJS, Express, AngularJS, Yeoman. A NodeJS + Express experiment with Yeoman and AngularJS

Next sections will talk about what you can build with Plone if you are not familiar with it, in particular heavily dynamic Javascript based verticalizations built with collective.angularstarter or similar techniques.

Plone

Plone is not only a CMS but a framework built with the Python programming language that let you build complex web applications, intranet, websites with strong focus on:

• contents
• security and sharing
• workflow
• searchability

You can extend the features provided by default by Plone thanks to a considerable number third party plugins.

You can see a couple of examples about you can build with Plone verticalizations with collective.angularstarter.

Coworking application

You can create custom content types for meeting rooms, private desks or common desks seats.

Basically the main object you are sharing is a folderish with metadata that let you configure the resource, for example:

• image, title, description and rich text widget. You can describe the resource you are sharing
• configure time slots configuration and hourly costs
• configure time slots for group of hours with costs (ex: morning, afternoon)
• daily cost or month cost, depending on the type of resource
• number of available seats available in parallel

Once the resource has been published, users can buy the suitable time slots depending on the type of resource and availability.

For private or common desks you can choose to search for multiple seats for multiple days or months. For meeting rooms you can buy just one unit time slot, multiple hours, group of hours (ex: morning) or the full day.

For example if you are searching for a meeting room you can choose partial days mode and select the available day you want to select:

The infinite scrolling shows you only the days that fits what you are searching for (2 private desks)

One selected the day, you can choose one or more available slots (for example morning):

And then: buy it!

The reservation objects are based on event types, since the reservation has a start and end datetime. So you can easily perform non-expensive catalog queries in order to search for slots available.

The project itself it is more complex because Plone it is integrated with an external invoice management software, a Paypal interface that let you buy more credits and a personal user box that let the users to see invoice PDF files and other notifications.

Advanced search forms

You can also use plone as a backend for a highly dynamic single page web application.
 
You can mix Plone data with external resources provided by third party server in order to build a complex search form.

For example the main search prompt to the user a master-slave AJAX widget

where the vocabulary of slave selects depend on the value of the previous one): 

or search for different criteria:

In this particular case results will appear after you fill all the needed information, but it is quite easy to implement a live search.

If you need more info about how to create a master-select widget component with Angular you may have a look at this article http://davidemoro.blogspot.com/2014/09/angularjs-master-slave-select-with.html.

What collective.angularstarter is

The collective.angularstarter plugin is:

1. a Plone + AngularJS kickstarter project. You can use this package when you want to develop a single page web applications powered by Angular using Plone as backend. With all the benefits of the Yeoman workflow
2. scaffolding tool that let you extend this package, add more features and then clone it creating a more sophisticated application. You can redistribute it with another name. Or you can develop a rapid prototype of your reusable application and after create a new zopeskel or yo package generator with one or more options. The clone hack might fail in some corner case but it should help you to convert an existing package to another. Anyway if something goes wrong you can easily correct the problems by hand. I get used to apply a similar script when me or other colleagues chose a very ugly package name and then you have to rename it. Maurizio, remember?! How many days we saved with this script? 

Anyway when you install collective.angularstarter and visit the @@angularstarter browser view it shows an example of AngularJS app with enabled by default:

• i18n support (http://angular-translate.github.io/)
• the AngularJS default routing support (but you can swith to more powerful alternatives. See https://github.com/angular-ui/ui-router)
• a test example
• assets management like image optimization, concat, minification/uglification of assets, unused css rules removal (see Addi Osmani's https://github.com/addyosmani/grunt-uncss) and so on
• support for production vs development mode based on two different installation mode
• Twitter Bootstrap ready

Here you can see how the @@angularstarter view looks like:

collective.angularstarter screenshot. Fill the input text and you'll see the page instantly updated

After that it's up to you coding with AngularJS and Plone!

Results

The following screenshot show you what happens if you analyze the network section of Firebug when you are in development mode:

or in production more:

Wait a moment! The resulting resultim bootstrap.css weights in at only 3,2 KB?! That's the power of minification and uncss tasks

A you can see you'll get (see the part 1 article of Pyramid starter seed project for further details about uncss and other tips explained):

• html minified (experimental, disable for real project)
• lighter images (no asset images in collective.angularstarter)
• most popular Javascript resources automatically cdn-ified
• css files concatenated, uncssed and minified
• javascript concatenated and uglified
• [update 20140926] assets automatically revved (avoid nasty caching problems)
• ... you can do more installing additional grunt tasks

How did I did it? Basically I played with Plone's resource registrations and layers.  See https://github.com/collective/collective.angularstarter/blob/master/collective/angularstarter/browser/configure.zcml

collective.angularstarter wraps a modified Yeoman AngularJS project (browser/angular): asset paths modified, bower_components folder renamed and a couple and other local changes to the Gruntfile.js file.

Hope you'll find collective.angularstarter useful. Feedback will be very appreciated!

UPDATE 20150303: I forgot to mention that collective.angularstarter plays well with Diazo (http://docs.diazo.org/en/latest/). This way you can write a pure static mocks with lots of javascripts and then using the html as the diazo theme with a bunch xml rules, with the backend decoupled with the frontend. Easy and tested on production! Probably I'll write a new write up.