Getting started

The most simple way to use AngularFaces is to simply include the jar file in your project. Sometimes this is all you need to do: for instance, the automatic creation of labels and messages works without further configuration. In most cases you should add a context parameter to the web.xml file.

<context-param>
    <param-name>javax.faces.FACELETS_DECORATORS</param-name>
    <param-value>
    de.beyondjava.angularFaces.core.tagTransformer.AngularTagDecorator
 </param-value>
</context-param>

If you forget the context parameter, AngularFaces reminds you. An error message is printed to the error log, and in developer mode a global error message is shown on every JSF page.

AngularFaces uses AngularJS 1.2.22 and jQuery 1.11.1. In the current version there's no way to configure AngularFaces to load different versions of the libraries. In production mode (i. e. web.xml context parameter javax.faces.PROJECT_STAGE set to "Production"), the minified versions are loaded. Otherwise, the debugger-friendly version is used.

Prerequisites

AngularFaces 2.0 currently requires Java 6 or above. As for the client side it supports Javascript and AngularJS.

A future version of AngularFaces will support Dart and AngularDart, but I've postponed Dart support because I'm waiting for a couple of announced breaking changes in AngularDart.

AngularFaces supports PrimeFaces 5.0 and above (and probably earlier versions, too). That doesn't mean PrimeFaces is required: PrimeFaces is an optional (but highly welcome) library.

Most of the examples are based on Maven. Some of the examples are based on Spring Boot and Gradle. Actually AngularFaces doesn't require any of them - Maven and Gradle are just nice tools to compile and package the jar and war files.

Brief introduction for the experts

There are two ways to use AngularFaces: download it from Maven Central, or build it from source.

Download AngularFaces from Maven Central

Maven users simply add the dependency to your pom.xml file (see below).

Build AngularFaces from source

Maven and Gradle users might want to "git clone" the AngularFaces 2.0 core project and run "maven install".

The pom.xml

After installing the jar (no matter wether you've built it from source or use the pre-packaged file), AngularFaces 2.0 can be used in your pom.xml like this:

<dependencies>
  <dependency>
    <groupId>de.beyondjava</groupId>
    <artifactId>angularFaces-core</artifactId>
    <version>2.0.0</version>
  </dependency>
  <dependency>
    <groupId>com.sun.faces</groupId>
    <artifactId>jsf-api</artifactId>
    <version>2.2.7</version>
    <scope>compile</scope>
  </dependency>
  <dependency>
    <groupId>com.sun.faces</groupId>
    <artifactId>jsf-impl</artifactId>
    <version>2.2.7</version>
    <scope>compile</scope>
  </dependency>
</dependencies>
          

Of course you'll may have to adjust the version number of AngularFaces. It won't remain version 2.0.0 forever :).

Verbose explanation for the rest of us

I've prepared a couple of tutorial projects for you. The first tutorial project doesn't do much: it's simply there to lay the ground to build on later.

You find the first tutorial project at my GitHub repository. The following steps describe how to download the entire repository. That's more than you really need (among other things, it includes the source code of AngularFaces itself), it it doesn't hurt, either. Quite the contrary, having the source code of AngularFaces at hand may help you to understand things more quickly.

Downloading AngularFaces with Git

GitHub is build around Git, so probably the easiest way to get started is to clone the AngularFaces repository to your local hard disk. In order to clone it to - say - C:\AngularFaces, proceed as follows. Open the command shell. In the case of Windows, you do it by hitting the keys "Windows" and "R" simulaniously, typing "CMD" and hitting the "return" key. Now a black window (the "command shell") opens. As for Unix users - well, I suppose you're more familiar with the shell than I am, so I'll omit the description. Now that the shell is open, enter these commands:

C:\
md \AngularFaces
cd \AngularFaces
git clone git@github.com:stephanrauh/AngularFaces.git
          

Again, the commands are slightly different in the UNIX world, but I'd rather stick with the Windows version for the rest of the tutorial.

Downloading AngularFaces using Subversion

You can also download AngularFaces using Subversion. The corresponding URL is https://github.com/stephanrauh/AngularFaces.

Downloading AngularFaces as a ZIP file

Of course, you can also download the ZIP file from GitHub. The disadvantage is it's more difficult to update your project. If you don't mind, download the master zip file from GitHub. There's also a "Download Zip" button at https://github.com/stephanrauh/AngularFaces.

Compile the projects using Maven

The next step is to import the projects into your IDE. Alternatively, you can compile the projects from the command line using Maven.
Eclipse users click "Import... --> Existing Maven Projects" and select these two projects:

The next step is to set up an Apache Tomcat server and to deploy the AngularFaces tutorial project. After starting Tomcat open the URL http://127.0.0.1:8080/angularfaces-tutorial-step-00/index.jsf. As mentioned above, the first tutorial page isn't really exciting: just a few texts and an image. I reduced the first example as much as possible because its only purpose is to check the installation. The only AngularFaces feature it uses is the relaxed declaration of the head and body tags:

<f:view xmlns="http://www.w3.org/1999/xhtml"
        xmlns:f="http://java.sun.com/jsf/core"
        xmlns:h="http://java.sun.com/jsf/html">
  <head>
    <title>AngularFaces 2.0 tutorial step 00 - Introducing AngularTetris>/title>
  </head>
  <body style="width:1000px">
    <h:graphicImage library="images" name="AngularTetris.png" />
  </body>
</f:view>

Beginning with JSF 2.2 you can simply write <body> instead of <h:body> - under certain circumstances. AngularFaces allows you to always use the short-hand version.

Project setup

This isn't as trivial as it sounds. The default project setup includes AngularFaces to your libraries - and that means AngularFaces starts up and tries to improve your JSF files. The first tutorial is designed in a way that AngularFaces can't improve anything, but you should find a few messages in the console window (or the catalina.out file).

The folder angularfaces-tutorial-step-00//WEB-INF/lib of the Tomcat webapps folder should contain these libraries:

Gson, classmate, commons-beanutils, commons-logging and the two validation API jars are added by AngularFaces 2.0 core.