REST API

Developing with AngularJS

AngularJS by Google has been built to offer front-end developers all the tools they may need to turn a website into a modern web application. AngularJS is a great JavaScript framework that provides many features (directives, routes, modules, etc.) to turn your HTML pages into dynamic views. This answers your front-end needs. But your application also needs a serious back end that will allow you to build your application quickly and concentrate on features without reinventing the wheel. This is what the Nuxeo Platform will provide you with. When users browse your web application, it will actually call the Nuxeo Platform through its REST API in order to handle and retrieve content.

AngularJS has some specific needs that need to be taken care of. This motivated us to write a specific client, in order to get a clean implementation. A wrapper around the existing Nuxeo JavaScript client has therefore been developed. This is the angular-nuxeo project.

The angular-nuxeo project brings some AngularJS-related improvements over the regular Nuxeo JavaScript client:

  • The client can be installed as an AngularJS module, that can easily be installed through bower.
  • Ajax calls are handled through AngularJS's promises mechanism. Any call you do will therefore let you use a callback function when it succeeds, and a separate one when an error occurs.

Bootstrapping an AngularJS Project With Nuxeo

This section will help you getting started with an AngularJS project. This will be covered in three steps:

  1. Installing prerequisites
  2. Using Yeoman's generator and Nuxeo Angular sample to get an AngularJS application running
  3. Building a Nuxeo Package that can be deployed on a Nuxeo Platform instance

Step 1 - Installing Prerequisites

In order to get a clean installation, we will make use of Yeoman's angular generator. So let's install it along with its prerequisites:

  1. Install Git.
  2. Install node.js.
  3. In a terminal, use npm to install the generator:

    npm install -g grunt-cli bower yo generator-karma generator-angular
    
    

Step 2 - Building an AngularJS Application from the Nuxeo Angular Sample Project

  1. Clone the Nuxeo Angular Sample project.
  2. Using a terminal cd to the project's nuxeo-angular-sample-front/src/main/yo folder.
  3. Run the following command:

    yo angular [yourAppName]
    

    When prompted, answer:

    • Would you like to use Sass (with Compass)? (Y/n) You decide
    • Would you like to include Bootstrap? (Y/n) You decide
    • Which modules would you like to include? You decide
    • Overwrite package.json? (Y/n) Y At that point, you get a ready to use AngularJS application. It is time to add the nuxeo module.
  4. Add the angular-nuxeo dependency by running the following:

    bower install https://github.com/nuxeo-sandbox/angular-nuxeo.git --save
    
  5. Edit the app/scripts/app.js file to add the nuxeo module. The file should look somewhat like this:

    angular
      .module('someModule',
        '...',
        'nuxeo'
      ])
    
  6. Adapt the project to your needs:

    1. Go to the nuxeo-angular-sample-front/src/main/yo folder.
    2. Edit the Grunfile.js file to configure the dist folder as below. Replace myapp with the folder name you want to put your application into:

      // Configurable paths for the application
        var appConfig = {
          app: require('./bower.json').appPath || 'app',
          // Replace dist: 'dist' by the line below. Put your app folder name instead of myapp.
          dist: '../../../target/classes/web/nuxeo.war/myapp'
        };
      
      ...
      
    3. Go to the nuxeo-angular-sample-front/src/main/resources/OSGI-INF folder.

    4. In the authentication-contrib.xml and deployment-fragment.xml files, replace myapp with your application's folder name. The goal of this step is to make sure that when requesting a URL which is part of your application, people will be asked for authentication, then redirected to your application once logged in.
  7. Go to the nuxeo-angular-sample-front/src/main/yo folder.
  8. Init your app

    bower install
    npm install
    

    You are now free to reference the nuxeo module into your controllers.

  9. Run grunt serve from your terminal and enjoy the result!

For detailed usage of the nuxeo angular client, take a look at its GitHub documentation. Note that as your application will be deployed in an existing instance, users will be asked for authentication by the Nuxeo Platform. Therefore, you do not need the client to send any authentication and actual testing can be done by installing a Nuxeo Platform locally on your machine. You can use grunt to preview your application by running grunt serve from a terminal.

Step 3 - Deploying the AngularJS Application in a Nuxeo Instance

Deploying an embedded application consists in putting your AngularJS application into the Nuxeo Platform's nuxeo.war folder. By doing so, people will be able to access it using a URL like http://mynuxeoinstanceurl/nuxeo/myapp. See the section Deployment options.

The good news is the Nuxeo Angular Sample project already provides you with everything you need to deploy the application in a clean fashion, through a Nuxeo Package. Quick reminder: Nuxeo Packages allow you to deploy bundles, resources, libraries and much more on your server easily. They are versioned and can be installed, upgraded, uninstalled either from the graphical interface or the command line. All of this makes life easier for developers and sysadmins alike. See the page Installing a New Package on Your Instance.

Build the Nuxeo Package by following these instructions:

  1. Using a terminal, cd to the nuxeo-angular-sample folder.
  2. Run:

    mvn clean install
    

    The Nuxeo Package is now built and available into the nuxeo-angular-sample/marketplace-nuxeo-angular-sample/marketplace/target folder. if you did not change its configuration, it will be called marketplace-nuxeo-angular-sample-0.1-SNAPSHOT.zip by default.

  3. Install the Nuxeo Package in your Nuxeo Platform instance.

  4. Go to http://mynuxeoinstanceurl/nuxeo/myapp and enjoy your brand new AngularJS application.

Deployment Options

There are two possible ways to deploy your application.

  1. Embedded mode: having your AngularJS application into your Nuxeo Platform instance.
    This setup is particularly interesting when using a Nuxeo Cloud instance. No setup, no administration needed, and full scalability. By configuring your Nuxeo Platform instance, people will be redirected to your custom interface and the overall setup is transparent. This solution is used by us for projects such as Nuxeo University. This deployment mode is the one used in third step of the example above.
  2. Isolated mode: keep your AngularJS web application separated from your Nuxeo Platform instance.
    By doing so, you can put your web application where you want it to be; this can be on a totally separate server if need be.

We are always eager to receive feedback on our projects. Please report bugs, wishes or anything related to the nuxeo-angular-sample project at answers.nuxeo.com


Related Documentation
4 months ago manonlumeau Relocated assets to fit new URL structure for 710 - fix
4 years ago Solen Guitter 28 | XDOC-658: Marketplace packages are now called Nuxeo Package
4 years ago Solen Guitter 27
4 years ago Thibaud Arguillere 26
4 years ago Bertrand Chauvin 25
4 years ago Bertrand Chauvin 24 | Fixed tutorial
4 years ago Bertrand Chauvin 23
4 years ago Solen Guitter 22
4 years ago Bertrand Chauvin 21 | Added bower install npm install
4 years ago Solen Guitter 20 | Reorganize content
4 years ago Solen Guitter 19 | Format and typos
4 years ago Bertrand Chauvin 18 | Added tags and related doc
4 years ago Bertrand Chauvin 16 | Formatting
4 years ago Bertrand Chauvin 17 | Formatting
4 years ago Bertrand Chauvin 15 | Added reporting info
4 years ago Bertrand Chauvin 14 | Removed todo and restriction warning
4 years ago Bertrand Chauvin 13 | Formatting
4 years ago Bertrand Chauvin 12 | Formatting
4 years ago Bertrand Chauvin 11 | Formatting
4 years ago Bertrand Chauvin 10 | Added app bootstrapping details
4 years ago Bertrand Chauvin 9
4 years ago Bertrand Chauvin 8 | Added embedded deployment first details
4 years ago Bertrand Chauvin 7 | Added dev environment setup
4 years ago Bertrand Chauvin 6 | angular-nuxeo introduction
4 years ago Bertrand Chauvin 5
4 years ago Bertrand Chauvin 4
4 years ago Bertrand Chauvin 3 | Started adding deployment options
4 years ago Bertrand Chauvin 2
4 years ago Bertrand Chauvin 1
History: Created by Bertrand Chauvin

We'd love to hear your thoughts!

All fields required