Now we will improve our application by exploring a bit the templating engine. We will show a quick overview of Juzu templating system. Templates are essentially made of static part (usually markup) and dynamic parts. In this section we will focus on explaining the use of dynamic expression in a template.

The application shows how a view can provide variable input for a dynamic template with parameters. Our application has a view controller and a template, but now the template contains the ${ } expression that makes it dynamic.

The weather temperature in ${location} is ${temperature} degrees.

Like before the template is used in the view controller but now we use a Map containing the location and temperature parameters.

  @View
  public void index() {
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("location", "marseille");
    parameters.put("temperature", "20");
    index.render(parameters);
  }

During the template rendering, the location and temperature expressions are resolved to the value provided by the view controller. When a template is rendered, an optional map can be provided, this map will be available during the rendering of the template for resolving expression.

The next step is to make our application obtain real data instead of the hardcoded values we used in the previous section. For this matter we use a remote service that we encapsulate into the WeatherService.

public class WeatherService {

  /** A cache for temperatures. */
  private final HashMap<String, String> cache = new HashMap<String, String>();

  /**
   * Returns the temperature for the specifed location in celsius degrees.
   *
   * @param location the location
   * @return the temperature
   */
  public String getTemperature(String location) {
    String temperature = cache.get(location);
    if (temperature == null) {
      cache.put(location, temperature = retrieveTemperature(location));
    }
    return temperature;
  }

  private String getValue(String url, String xpath) throws Exception {
    XPathExpression expr = XPathFactory.
        newInstance().newXPath().compile(xpath);
    InputSource src = new InputSource(url);
    return expr.evaluate(src);
  }

  /**
   * Retrieve the temperature.
   *
   * @param location the location
   * @return the temperature
   */
  protected String retrieveTemperature(String location) {
    try {
      // First we get the location WOEID
      String woeidURL =
          "http://query.yahooapis.com/v1/public/yql" +
              "?q=select%20*%20from%20geo.places%20where%20text%3D%22" +
              URLEncoder.encode(location, "UTF-8") +
              "%22&format=xml";
      String woeid = getValue(woeidURL, "//*[local-name()='woeid']/text()");

      // Now get weather temperature
      String weatherURL =
          "http://weather.yahooapis.com/forecastrss?w=" +
              URLEncoder.encode(woeid, "UTF-8") +
              "&u=c";
      return getValue(weatherURL, "//*[local-name()='condition']/@temp");
    }
    catch (Exception e) {
      // Unavailable
      return "?";
    }
  }
}

Juzu uses dependency injection to interact with a service layer. The JSR-330, also knowns as @Inject, defines an API for dependency injection. The WeatherService is injected in the controller with the weatherService field annotated with the @Inject annotation:

  @Inject
  WeatherService weatherService;

This service is then simply used into our controller index() method:

  @View
  public void index() {
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("location", "marseille");
    parameters.put("temperature", weatherService.getTemperature("marseille"));
    index.render(parameters);
  }

As we can see, Juzu relies on the portable @Inject annotation to declare sinjections. Injection is performed by the dependency injection container. At the moment the following containers are supported:

There is a preliminary support for Google Guice 3.0, but it is not yet available. In the future more container support could be achieved.

By default it uses the Weld container, if you want instead to use Spring container instead the configuration is done by a init param defined in the deployment descriptor:

<init-param>
  <param-name>juzu.inject</param-name>
  <param-value>spring</param-value>
</init-param>

The same can be achieved for a portlet of course:

<init-param>
  <name>juzu.inject</name>
  <value>spring</value>
</init-param>

In the case of Spring injection, the file spring.xml file is needed, it contains the service declarations for the Spring container.

Juzu provides more advanced dependency injection, in particular it uses the Qualifier and Scope features defined by the JSR-330 specification, however they are not covered in this tutorial.

So far we seen a basic view controller, in this section we will study more in depth view controllers. A view controller is invoked by Juzu when the application needs to be rendered, which can happen anytime during the lifecycle of an application.

This version has still the index() view controller, but now it has also an overloaded index(String location) method that accept a location argument as a view parameter.

  @View
  @Route("/show/{location}")
  public void index(String location) {
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("location", location);
    parameters.put("temperature", weatherService.getTemperature(location));
    index.render(parameters);
  }

The @Route("/show/{location}") annotation binds the the index controller method to the /show/* route. Since our our application package is annotated with the @Route("/weather4") annotation, an URL like /weather4/show/marseille invokes this controller method with the marseille location.

View parameters are bound to the current navigation of the application and their value are managed by the framework. At this point it is normal to wonder how a view parameter value can change. Let's have a closer look at the index.gtmpl application template.

The weather temperature in ${location} is ${temperature} degrees.
<a href="@{index(location = 'marseille')}">Marseille</a>
<a href="@{index(location = 'paris')}">Paris</a>

The template now has two links changing view parameters when they are processed. Such links are created by a special syntax that references the view method, for instance the script fragment @{index(location = 'paris')} generates an url that updates the location view parameter to the paris value when it is processed.

The initial controller method index() is still there but now it simply invokes the index(String location) controller with a predefined value.

  @View
  public void index() {
    index("marseille");
  }

We could't close this section without talking a bit about safe urls. Juzu is deeply integrated at the heart of the Java compiler and performs many checks to detect applications bugs during the application compilation. Among those checks, templates are validated and the url syntax @{ } is checked against the application controllers. In fact Juzu will resolve an url syntax until it finds one controller that resolves the specified name and parameters. If not Juzu will make the compilation fail and give detailled information about the error. This kind of feature makes Juzu really unique among all other web frameworks, we will see some other later.

Now it's time to introduce action controllers, actions are method annotated by the @Action annotation.

The role of an action controller is to process actions parameters. Each parameter of an action controller method is mapped to the incoming request processed by Juzu, such parameters can be encoded directly in the URL or be present in the form that triggers the action.

The weather temperature in ${location} is ${temperature} degrees.

<ul><% locations.each() { location -> %>
<li><a href="@{index(location = location)}">${location}</a></li>
<% } %>
</ul>

<form action="@{add()}" method="post">
   <input type="text" name="location" value=""/>
   <input type="submit"/>
</form>

In this example, we use a form which contains the the location action parameters. In order to create an action url we use the same syntax than view url @{add()} but this time we don't need to set any parameter, instead the form parameters will be used when the form is submitted. However this is not mandatory and instead we could have url parameters such as @{add(location = 'washington'}, such syntax is valid specially when it is used without a form. Obviously there is the possibility to mix form and action parameters.

When the url is processed, the following action controller method will be invoked:

  @Action
  @Route("/add")
  public Response.View add(String location) {
    locations.add(location);
    return Weather_.index(location);
  }

The method is annotated with two annotations:

The location parameter is not declared in the route because it can be invoked by a form and the location parameter is part of it.

The method returns a Response.View object. This object instructs Juzu to use the index(String location) controller view after the action. The Weather_ controller compagnion provides a type safe way for generating the response: Weather_.index(location). Our action just needs to return it, Juzu will take care of showing the corresponding view after invoking the action.

We have seen previously how to render templates from a controller and how we can pass parameters for rendering a template. Templates use ${ } expressions that often refers to parameters passed by the controller. For this purpose we used an HashMap for storing the various parameters used during rendering.

This syntax is a generic way and uses an untyped syntax, indeed if a template parameter name changes the controller will continue to compile because of the generic parameter map. To improve this situation, parameters can be declared thanks to a param tag inside the template:

#{param name=location/}
#{param name=temperature/}
#{param name=locations/}

The weather temperature in ${location} is ${temperature} degrees.

<ul><% locations.each() { location -> %>
<li><a href="@{index(location = location)}">${location}</a></li>
<% } %>
</ul>

<form action="@{add()}" method="post">
   <input type="text" name="location" value=""/>
   <input type="submit"/>
</form>

For example the location parameter is declared by the #{param name=location/} tag. During the Java compilation, Juzu leverage such parameter declarations to provide a more convenient way to render a template.

The tight integration with the Java compiler allows Juzu to generate a template class for each template of the application, those template classes inherits the Template class and adds specific methods for passing them parameters in a safe manner.

  @View
  public void index(String location) {
    index.
      with().
      location(location).
      temperature(weatherService.getTemperature(location)).
      locations(locations).
      render();
  }

As we can see, the HashMap is not used anymore and now we use a type safe and compact expression for rendering the template. Each declared parameter generates a method named by the parameter name, for the location parameter, we do have now a location(String location) method that can be used.

To make the syntax fluent, the parameter methods can be chained, finally the render() method is invoked to render the template, however it does not require any parameter since all parameters where passed thanks to the parameter methods.

The Java name of the generated template class is the name of the template in the templates package of the application. In our case we do obtain the examples.tutorial.weather6.templates.index class name. It is very easy to use our subclass by injecting the template subclass instead of the generic Template class.

  @Inject
  @Path("index.gtmpl")
  examples.tutorial.weather6.templates.index index;

Of course it is possible to import this value and use directly the index class name. We used directly the full qualified name of the class for the sake of the clarity.

Our application is almost complete, in this section we will work on the look and feel to make the application appealing. We will use the famous Twitter Bootstrap framework and show how it integrates well in Juzu applications.

/*!
 * Bootstrap v2.0.3
 *
 * Copyright 2012 Twitter, Inc
 * Licensed under the Apache License v2.0
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Designed and built with all the love in the world @twitter by @mdo and @fat.
 */

// CSS Reset
@import "reset.less";

// Core variables and mixins
@import "variables.less"; // Modify this for custom colors, font-sizes, etc
@import "mixins.less";

// Grid system and page structure
@import "scaffolding.less";

// Base CSS
@import "type.less";
@import "forms.less";

// Components: common
@import "component-animations.less";

// Components: Buttons & Alerts
@import "buttons.less";
@import "button-groups.less";

// Components: Misc
@import "accordion.less";

Plugins in action

Juzu can be extended with plugins, in this section we will use two of them

• The Less plugin compiles less files into css files

• The Asset plugin inject asset such as stylesheet or javascript in the application page

Less compilation

Juzu provides native support for the Less language via the Less plugin and the @Less annotation. It allows a set of less files to be transformed into the corresponding css files during the java compilation, achieving two important steps during the compilation phase:

• The less files are transformed into ready to use css files

• It ensures a maximum of safety: the Less parser will report any error in the source

Our first step is to create the examples.tutorial.assets package, we copy the Bootstrap Less files into this package and annotate the examples.tutorial package with the @Less annotation to trigger the compilation of the stylesheet in the assets package:

@Less(value = "bootstrap.less", minify = true)
package examples.tutorial;

import juzu.plugin.less.Less;

This annotation triggers the compilation of the bootstrap.less in the assets package, the minified parameter instruct Less to minify the resulting css.

Injecting CSS

Now that we have worked out the CSS details we need to make our stylesheet available in the application page. The asset plugin will achieve this result for us. This plugin provides declarative configuration for the various assets required by an application. It works both for stylesheets and javascript, in this section we use it for stylesheet:

Example 7.2. Injecting Bootstrap CSS in our application

@Application
@Assets(stylesheets = @Stylesheet(
  src = "/examples/tutorial/assets/bootstrap.css",
  location = AssetLocation.CLASSPATH)
)
package examples.tutorial.weather7;

The usage is fairly straightforward with the @Assets and Stylesheet annotations. We configure the location parameter to be CLASSPATH because the Less plugin created it there.

Bringing CSS to life

After this step we need to modify our application template to use the various styles provided by Bootstrap:

Figure 7.1. The Bootstrapized application

We will not explain that in details, however we will study the important modifications:

Accordion

The Bootstrap provides the Collapse component. We will not use the entire Collapse component here but instead reuse the CSS rules to display the available cities:

<div class="accordion-group">
  <div class="accordion-heading"><a class="accordion-toggle" href="@{index(location = current)}">${current}</a></div>
  <div class="accordion-body">
    <div class="accordion-inner">The weather temperature in ${current} is ${temperature}&deg; ${grade.toUpperCase()}.</div>
  </div>
</div>

Adding a city

Finally the form for adding is modified to reuse Bootstrap form support:

<form action="@{add()}" method="post">
  <fieldset>
    <div class="controls">
      <div class="input-append">
         <input class="span2" type="text" size="16"name="location" value=""/>
         <button type="submit" class="btn">Add</button>
      </div>
    </div>
  </fieldset>
</form>

Now that our application look great, we are going to add a final touch to our application and make it more dynamic.

In the previous section we introduced the accordion user interface component, but it was used in a static way. In this section we will make it dynamic and introduce the Ajax plugin.

The accordion component can be combined to the JQuery collapse plugin providing the capability to unfold an item to display the weather of the location. When the item is unfolded an ajax request is performed to the application to retrieve the markup that will be inserted.

@Assets(
   scripts = {
      @Script(
         id = "jquery",  
         src = "jquery-1.7.1.min.js",
         location = AssetLocation.CLASSPATH),
      @Script(
         id = "transition",
         src = "bootstrap-transition.js",  
         location = AssetLocation.CLASSPATH,
         depends = "jquery"),  
      @Script(
         id = "collapse",
         src = "bootstrap-collapse.js",
         location = AssetLocation.CLASSPATH,
         depends = {
            "jquery", // 1
            "transition"}),  
      @Script(
         src = "weather.js",
         location = AssetLocation.CLASSPATH,
         depends = {
            "jquery",   
            "collapse"})  
   },
   stylesheets = @Stylesheet(src = "/examples/tutorial/assets/bootstrap.css", location = AssetLocation.CLASSPATH)
)
package examples.tutorial.weather8;

<div class="accordion-group">
  <div class="accordion-heading">
    <a class="accordion-toggle" href="#${current}" data-parent="${id}" data-toggle="collapse">${current}</a>
  </div>
  <% def expanded = i != index ? 'in' : ''; %>
  <div id="${current}" class="accordion-body collapse ${expanded}">
    <div class="accordion-inner">
    </div>
  </div>
</div>

  @Inject
  @Path("fragment.gtmpl")
  examples.tutorial.weather8.templates.fragment fragment;

  @Ajax
  @Resource
  @Route("/fragment")
  public void getFragment(String location) {
    fragment.
      with().
      location(location).
      temperature(weatherService.getTemperature(location)).
      render();
  }

#{param name=location/}
#{param name=temperature/}
<p>The weather temperature in ${location} is ${temperature} degrees C</p>

$(function () {

  // Setup an event listener on the .collapse element when it is shown
  $('.collapse').on('show', function () {

    // Get the location attribute from the dom
    var location = $(this).attr("id");

    // Update the .accordion-inner fragment
    $(this).
      closest(".accordion-group").
      find(".accordion-inner").
      each(function () {

      // Load the fragment from the resource controller
      $(this).jzLoad(
        "Weather.getFragment()",
        {"location":location});

    });
  });

  // Setup the collapse component
  $(".collapse").collapse();
});

$(function() {
  //
});

<div class="jz">
  <div data-method-id="Weather.getFragment()" data-url="http://localhost:8080/....."/>
  ...
</div>

The last chapter of our tutorial will teach you how to test a Juzu application. Juzu applications can be tested using existing tools, we will use in this chapter the following tools:

For making testing easy, Juzu provides a Maven dependencies containing all the required dependencies for testing an application:

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.juzu</groupId>
  <artifactId>juzu-bom-arquillian</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.juzu</groupId>
  <artifactId>juzu-bom-arquillian-tomcat7</artifactId>
  <scope>test</scope>
</dependency>

The juzu-bom-arquillian and juzu-bom-arquillian-tomcat7 provides setup for Arquillian and Selenium for Tomcat7 based testing.

@RunWith(Arquillian.class)
public class WeatherTestCase {
}

  @Deployment
  public static WebArchive deployment() {
    WebArchive war = Helper.createBaseServletDeployment();  
    war.addAsWebInfResource(new File("src/test/resources/spring.xml"));  
    war.addPackages(true, "examples.tutorial");  
    return war;
  }

  @Drone
  WebDriver driver;

  @ArquillianResource
  URL deploymentURL;

  public URL getApplicationURL(String application) {
    try {
      return deploymentURL.toURI().resolve(application).toURL();
    }
    catch (Exception e) {
      AssertionFailedError afe = new AssertionFailedError();
      afe.initCause(e);
      throw afe;
    }
  }

  @Test
  @RunAsClient
  public void testWeather1() throws Exception {
    URL url = getApplicationURL("weather1");  
    driver.get(url.toString());
    WebElement body = driver.findElement(By.tagName("body"));
    assertTrue(body.getText().contains("The weather application"));  
  }

We reached the ends our walk through Juzu, now you can learn more and study the Booking application. This application can be found in the package you downloaded in the booking directory.