Japid Engine Quick Manual, V0.6

Bing Ran<bing_ran@hotmail.com>

20100/2/16

Japid is a Java*based dynamic content rendering templates system that aims to deliver the fastest possible result.

It’s a generic template engine that can be used by any Java applications to render any Java objects. It also provides adapters specifically for the Play! Framework. (The current version has some issues to be use standalone. So don’t use it that way yet. Sorry for for claim.)

The main goal of Japid is for use in large, high-traffic and highly dynamic Play! bases web sites. To reach that goal, Japid transforms templates files to clean Java source code thus the rendering can reach near raw Java speed.

The high-performance does not come at the cost of advanced features such as site*mesh like layout, tags, template inheritance, content caching, server-side include.

This document focuses on using the Japid module for the Play! Framework.

The Design philosophy

I want:

I don’t want:

Mechanism

Japid Module

First you need to get yourself familiar with the Play! module concept.

To show all the version of Japid module, from the command-line:


$ play list-modules

And the section for Japid is like:


~ [japid]
~   Japid template engine
~   http://www.playframework.org/modules/japid
~   Versions: 0.2, 0.3.1, 0.5.1, 0.6.0, head

Then you can pick the version to install, usually the head version, which is also the default version.

To install the Japid module:


$ play install japid-0.6.0

or, 


$ play install japid-head

or simply:


$ play install japid

to get the default version.

The module goes to the modules directory of the Play!'s installation root. The module contains

  1. the module jars in the lib directory
  2. the Eclipse plugin in the eclipse-plugin
  3. a sample Japid application in the JapidSample
  4. the source code in the src... directories

Now add a reference to Japid module in the application.conf file in your application:


module.japid=${play.path}/modules/japid-head

The next thing to do is to create the default directory structure required by Japid. From the app root:


$ play japid:gen

The japidviews tree is now created in the app directory

Now you’re ready to code your models, controllers and Japid views! Every time you add a new controller you can play japid:gen to create a new sub-directory to match the controller or you can create the directory manually if you’re confident of your typing.

Runtime Directory Structure of Japid in Play! applications

All template files are located in app/japidviews directory tree, as illustrated here:

/app/controllers/ControllerA.java
                /more/ControllerB.java
    /japidviews/_javatags/JapidWebUtil.java
               /_layouts/
               /_notifiers/
               /_tags/
               /ControllerA/action1.html
                           /action1.java
               /more/ControllerB/action1.html
                                /action1.java

Notes:

  1. the _javatags sub-directory contains a utility class that is statically imported to all generated java class definitions. One can add more static methods in the this class for use in the templates.
  2. the _layouts sub-directory contains global layouts that are accessible to all view templates. However as explained below, Japid layouts can be place anywhere in the tree and can be referenced using the fully qualified name in the templates, just like the way a Java class class is referenced in a typical Java project.
  3. the _tags sub-directory contains global tags that are accessible to all view templates. However as explained below, Japid tags can be place anywhere in the tree and can be referenced using the fully qualified name in the templates, just like the way a Java class class is referenced in a typical Java project.
  4. the _notifiers sub-directory contains email templates coded with Japid. There is a section for this later in this document.
  5. The rest nodes of the tree are conventionally created to match the structure of the controller and actions therein. For each controller, there is a directory (or directory path if the controller is nested in a deeper package) created which contains a bunch of template files named after the action method in the controller. The Japid converter translates the html template files to java files in the same directory. Please be noted though, the layouts of the template files are totally required only if we are going to use implicit template binding. A template can be placed anywhere in the case of explicit template invocation. There is a section of document for this later.

Syntax

The original version of Japid (around version 0.3) copied a lot of the syntax from the Play! framework. The idea was to help the Play! users to pick up the engine quickly. New and simpler syntax has been introduced to Japid templates over the course of one year use in real-world projects. This documents tries to compare the syntax of different flavors.

Also noted, the Microsoft Razor Template Engine is another source of inspiration.

Views, Tags and Layout

There are three types of templates in the Japid rendering system:

  1. Views: the templates that play the central role in rendering data. Most of the rendering logic is done here.
  2. Tags: the templates that encapsulate some logic of data rendering and can be invoked from any other templates. They’re equivalent to functions.
  3. Layouts: the templates that handle the out most level of “layout” of web pages, such as the arrangement of the headers, footers, side bars, columns etc.

Views usually extends layouts and pass text snippet to the layout to be displayed in designated location in the layout.

Here is a simple layout template (I have left out irrelevant markups (such as HTML tags) as much as possible make the syntax structure cleaner.):

master.html


This is the header. 
The title of this article is "`get title`"
`doLayout
This is the footer.

A layout can placed anywhere but usually is in the app/japidviews/_layouts directory, which is visible to any views in the project.

There are two Japid syntax to learn:

Display a named text value: `get <text block name>

In Japid the back quote “`” plays a very important role in mixing code in templates. A back quote basically starts a script line, which it may:

  1. start a directive or command, which is an instruction to the code generator to create special Java source. In this case `get title` is to retrieve a text block named “title”, to be passed from any child views that inherited from this layout.
  2. start a line of pure Java code to be placed in the generated code.
  3. end a script line if the line is already started by another `.

A script line ends with it encounter a new line, i.e., '\n' or another `. In the sample above the script line is wrapped in a pair of `: `get title`. The second ` can be left out if there is no other meaningful letters in the rest of the line.

The Japid parser will first determine if the word following the ` is a command name and treat the rest of the line as Java code if it is not.

A `get xxx command is usually matched by a `set xxx command in the views that inherit from this layout. The set command assign a string to the variable xxx. If the variable is not set by the child view, an empty string is returned. Note: older version of Japid requires each variable referenced by get must be set in the child. Japid 0.6.2 and up makes it optional.

Japid syntaxPlay! syntax
`get <text block name>`#{get "title"/}

`doLayout

This command is to let the child template to render itself. The result will be placed in the current position.

Japid syntaxPlay! syntax
`doLayout`#{doLayout/}

Once we have the layout we are ready to code the main view template.

user.html


`import models.mymodels.User
`extends master
`args User user, int count
`set title:"The User Detail"
`for (int i > 0; i < count; i++) {
    hello $user.name, and you are `tag showAge user.age`.
`}

Here are a few new syntax:

`import

Purpose: same as in java.

Japid syntaxPlay! syntax
import x.y.z, import static x.y.Z.* `importnone

Note:

  1. there is no ending `.
  2. the ending ; is optional
  3. one line per import

`extends

Purpose: same as in java. The super class is usually a layout template. The template name can be:

  1. the template file name: master.html
  2. the template file name without extension: master
  3. the template file in full path: japidviews.mypackage.master
  4. a file in a sub directory, using a leading “.”: .sub.master
Japid syntaxPlay! syntax
import x.y.z, import static x.y.Z.* none

Note:

  1. there is no ending `.
  2. the ending ; is optional
  3. one line per import

`args

Purpose: the parameters to be passed to this template to render. The format is the same as in Java method declaration.

Note:

  1. The data type must be visible, meaning it must be imported. However there are several classes and packaged that are imported to any templates by default:


import java.util.*;
import java.io.*;
import cn.bran.japid.tags.Each;
import static play.templates.JavaExtensions.*;
import static cn.bran.play.JapidPlayAdapter.*;
import static play.data.validation.Validation.*;
import static cn.bran.play.WebUtils.*;
import japidviews._layouts.*;
import japidviews._tags.*;
import japidviews._javatags.*;
import models.*;
import controllers.*;
import static  japidviews._javatags.JapidWebUtil.*;
import play.data.validation.Validation;
import play.mvc.Scope.*;
import play.data.validation.Error;
import play.mvc.Http.*;

JapidPlay!
import x.y.znone

Create a named text value: `set

Purpose: to create a text value under a name, which can be retrieved in the layout of the current view.

There are two forms of set:

  1. one-liner: `set title:"some value". The double quotes are required.
  2. block form: 


`set title
  a very long and funny title, a very long and funny title
  a very long and funny title
`

Notes:

  1. The set commands location-insensitive, meaning they can be placed anywhere in a template and won’t interfere with the main text flow.
  2. There can be multiple set commands in a template, of course each of which should define a different text block.
  3. Limitations:
    1. If there is any reference to variables, those variables must be 1) listed in the `args directive; or 2) defined within the set block.
    2. Tags cannot be referenced in a set command. This limitation will be lifted in the future.

`for

Actually this is the pure Java way of iterating through Java collections and arrays. The word “for” is not a special word in the Japid templates. It’s pure Java code started by a back quote. Looping in Japid is Java as usual, including the closing brace.


`for (int i = 0; i < count; i++) {
    whatever you put here. ${i}
`}

or, 


`String[] names = ...;
`for (String name: names ) {
    whatever you put here. ${i}
`}

However Japid provides each command, an enhanced looping tool, inspired by Play!'s list tag.

`each

The each command offer a loop construct that makes available additional looping attributes for users to fine-tune the data rendering. For an example:


`each names | String name
    $name $_size, $_index,  $_parity $_isOdd $_isFirst $_isLast 
`

Note:

  1. The each block ends with a single ` sign on a whole line.
  2. In fact the above syntax is a standard way to invoke a tag with a callback body.
  3. The variable names is the collection to iterate on. The construct after the vertical line is the instance variable for each round of iteration. The data type must present before the variable name. In the body of each we see a bunch of additional variables related to the current iteration:
VariableMeaning
int _sizethe size of the collection or array, -1 if not determined in the case of iterable as the collection
int _indexthe index of the current instance in the collection
boolean _isOddtrue if the index is odd, false if it is even
String _parity “odd” for the odd lines, “even” for the even lines
boolean _isFirst true if the current instance is the first in the collection
boolean _isLasttrue if the current line is the last in the collection

Java Expression: ${expression}

The string value of a Java expression can be interpolated in text stream using the ${} syntax, as is used in Play!. The {} signs can be omitted if it won’t cause confusion to the compiler (or your eyes) because it fused with the rest of the context. For examples:

${user.name} == $user.name
${user.name.length()} == $user.name.length()

As long as the expression is properly delimited by none identifier characters, the {} can be left out. The {} is mandatory in Play! default engine.

Note: Japid by default does not escape the string value of expressions, like what Play! does. One can simply do:

${escapeHtml(expr)}

to get the effect. The escapeHtml() is a static method defined in play.templates.JavaExtensions class in Play!, which is automatically imported to any Japid templates. There are other useful static methods in that class that are available directly in the templates.

Safe Property Navigation: `supressNull on

An expression like $user.name.length() can cause potential problems if any of the properties is null, in which case the template will throw NPE. There is so called safe navigation operator in Groovy: p?.p2?.p3. Java does not have this. Instead Japid introduces a directive to suppress the NPE in case such property navigation throws NPEs.


` suppressNull on
` String a = “a”;
safe to do $a.length()
` a = null;
also safe to do a.something too: $a.length()

The second call $a.length() in the above sample throws an NPE, which is caught by the template and discarded with the `suppressNull on directive at the top of the script.

Note: only NPEs thrown after the directive will be suppressed.

Simple Tag Invocation: `tag tagName arg1, arg2...`

Back to the view template:

user.html


`import models.mymodels.User
`extends master
`args User user, int count
`for (int i > 0; i < count; i++) {
    hello $user.name, and you are `tag showAge user.age`.
`}

In the body of the for loop we are invoking a tag called showAge. Think of a tag as a function defined in a separate file. Here is the tag file:

showAge.html


`args int age
$age years old

The above tag simply take an int as the age and append “years old” to it.

The tag invocation has alternative syntax:

`tag tagName(arg1, arg2...)`

which looks more like function calls.

And the `tag command can be further cut short as `t as in:

`t tagName(arg1, arg2...)`

Note: the closing ` can be omitted if there is no other letters in the rest of the current line. A new-line character is a valid tag closing symbol.

locating a tag file

Similar to locating a layout file, the tag name can take a few forms:

  1. a simple name: tagName, which can be either in the same directory as the current template file, or in the japidviews._tags directory.
  2. a full package form: japidviews.my.pack.tagName, or
  3. a relative form: .sub.tagName, which is located in a sub directory of the current directory.

Also noted is one can use “/” in lieu of “.” but I prefer the dot syntax.

Advanced Tag Invocation: `tag tagName arg1, arg2... | type1 arg1, type2 arg2`

A tag can take a block of template text as the last argument. For an example:


`tag fancyTag “hello” | String name
    what a fancy name: ~name
`

There are two arguments to the tag invocation:

  1. "hello", a String, and
  2. String name \n what a fancy name: ~name, a template.

The vertical line “|” separates the regular arguments and the template. Note: the Japid parser requires the presence of this separator even if the template does not have any parameters.

This is valid:


`tag fancyTag “hello” | 
    what a fancy name!
`

And this is not:


`tag fancyTag "hello"
    what a fancy name!
`

The reason is that a new-line character ‘\n’ can function as a tag terminator if the parser does not detect any a “|” in the argument list. The “|” tells the parser that a template block is following the current line.

The template parameter passed to a tag is rendered by a `doBody arg1, arg2... command in the tag file, as explained in the Tag Definition later in this document.

Tag definitions

Any views can be used as tags. The above mentioned view file:

user.html


`import models.mymodels.User
`extends master
`args User user, int count
`for (int i > 0; i < count; i++) {
    hello $user.name, and you are `tag showAge user.age`.
`}

can be invoked from other views. e.g.,


 another view 

` User aUser = ...;
`tag user aUser, 10

In another word, regular views can be invoked either from the controller actions or from other views.

However, the regular views cannot take a template as an argument, unless it contains a special tag: `doBody, as in:

fancyTag.html


`args String m
I got ~m, and the body is:


`doBody m

done.

Note: the argument list of the `doBody command must match that declared after the “|” symbol in the invoking templates.

The doBody command pass matching arguments to the passed-in template. This behavior is sometimes referred to as “call-back”.

With this feature, a tag can be effectively used as a layout to a view. The layout part is done in the tag and the main template section is passed in as the last argument of the tag invocation.

Note:

  1. tags can invoke other tags.
  2. tags usually don’t inherit from layouts.
  3. Tags can be places anywhere in the japidviews tree.

Verbatim text: `verbatim

Purpose: to display a block of text un-parsed by Japid. 


`verbatim
    OK, anything inside this block is not parsed: `command, ${expression}, etc
`

Note: a verbatim block must be closed by a standalone back quote that occupies a whole line.

JapidPlay!
`verbatim .... \n` #{verbatim}... {/}

Invoking templates in Controllers

Japid templates are compiled java classes which can be invoked statically or reflectively.

Note: to use Japid in a controller, one must let the controller to extends a special Japid controller super class named cn.bran.play.JapidController, instead of the Play!'s default Controller class.

Explicit Template Binding

Since any templates are compiled to Java classes, one can use them directly anywhere, of course including in the controller actions. Given a template japidviews/MyController/foo.html, Japid will generate a Java class named japidviews.MyController.foo. The entry point of using this class is:


    public cn.bran.japid.template.RenderResult render(Bar bar)

The RenderResult object contains the text which is the result of template rendering, and the additional HTTP headers. As you may have known, The Play! way to return a result from a controller method is to throw an Object of Result type. To use the result from the template class, one need to wrap it in a cn.bran.play.JapidResult object and throw it out. For an example, one needs to code something similar to the following snippet in a controller action:


    throw new JapidResult(new foo().render(myBar));

Of course all the classes must have been properly imported before use or one must use the fully qualified names.

The JapidContrller super class offers a static method render(RenderResult rr) to hide the JapidResult, so one can write:


    render(new foo().render(myBar));

Slightly cleaner.

As you may guess, invoking a template class directly does not require the class to be in a specific package. There is no need to match the name or the package of the template with the name of the action or the class or the package. The minimum requirement is the templates are in the japidviews tree, since the template converter will only scan this tree for Japid templates.

How to convert the template files to Java source code?

Conversion method 1: command-line tools

There are four Japid command-line commands that one can use in the application root:

  1. japid:mkdir: check the proper japidviews directory tree and create missing elements if necessary.
  2. japid:gen: do mkir first then translate all templates in html, xml, json to Java sourse code. Most of the time this command supersedes the japid:mkdir.
  3. japid:clean: remove all generated Java source files derived from the templates.
  4. japid:regen: do clean and gen

These commands are useful in what I call the “cold development” mode – in compile-time and you use the static linking (a.k.a. explicit template binding ) of the templates, i.e., you instantiate the java class derived from the view template in the controller actions and invoke the render() method directly. The workflow in this mode is:

  1. create the model classes if they’re to be rendered in the views.
  2. create the Japid views in html.
  3. run the play japid:gen to get the Java files derived from these templates.
  4. statically link the renderer in actions.

As explained before, implicit template binding is a lot more flexible and does not require the use of the code generation tools.

Let me show you how you can configure these commands in Eclipse to make using these commands less troublesome if one is using Eclipse as the main IDE to develop applications, me included.

The most used command is probably play japid:gen.

Here are the steps to create a quick link to the command in Eclipse:

  1. Open menu: Run -> External Tools -> External Tools Configuration
  2. Create a new entry with the following attributes:

Name: japid-gen

Under the Main tab:

  1. location: D:\home\bran\projects\play\play.bat
  2. Working Directory: ${project_loc}
  3. Arguments: japid:gen

Under the Refresh tab:

  1. Check the "Refresh resources upon completion"
  2. Select the "The project containing the selected resource"
  3. Check the "Recursively include sub-folders"

Now I can translate the latest templates to Java code right from the IDE.

Two other most useful commands are play japid:regen and play eclipsify, if you’re an Eclipse user. The latter is not directly related to Japid, but it’s convenient when you upgrade either Play! or Japid module.

Conversion method 2: care-free conversion in DEV mode.

The Play! runtime in DEV mode detects file changes automatically before processing any new HTTP requests or job activation, and Japid module will step in to translate the added/changed template files automatically. Java files derived from removed templates will get removed automatically too.

Conversion method 3: using the Japid plugin for Eclipse

There is a plugin for Eclipse that takes care of templates/Java synchronization at compile time. One don’t need to run the app in DEV mode to get the templates automatically translated. The detail is explained in a later section of this document.

In conclusoin, there are good and bad sides of using a template explicitly as a Java class:

Implicit Template Binding

To decouple an action and the template it defaults to render, the JapidController offers a method renderJapid(...) to hide the process of invoking the renderer. The method depends on the parallel package structure of the controllers tree and the japidviews tree to locate the right template to render with.

For an example, given the action method controllers.p1.MyController.foo(...), the default template name is japidviews/p1/MyController/foo.html.

The renderJapid makes binding to the default template a lot easier as shown below:


    public static void foo(...) {
        Bar bar = ...;
        renderJapid(bar);
    }

Note: the Play!'s default rendering engine binds the arguments by name. This means one must give any objects to be passed to the template a name or the template engine won’t find them. In contrast Japid conveniently binds arguments by position, just like any regular java method invocation. One don’t need to match the names of the variables in the action with those in the templates.

I personally find using the implicit template binding a lot easier on me, since I can work in the order of a request processing flow very naturally in this mode: the models, the controllers and then the views. I don’t need to manually convert the templates files at all. I need to however make sure the japidviews directory tree is synchronized with the controllers tree in terms of the package names and the files names. With the Japid Plugin for Eclipse, which is the IDE of my choice, I don’t even need to worry about the package structure and I can focus on the real coding logic. The Eclipse plugin will guide me to create the views in the proper locations, as described later in this document.

Now, what if there are multiple possible Japid templates to render with in an action?

Three ways:

  1. statically link the template class as explained in the previous section.
  2. use the JapidController.renderJapidWith() method: for an example: renderJapidWith("more/MyController/anotherTemplate.html", bar) will render the bar object with the japidviews/more/MyController/anotherTemplate.html template. The template name is a relative name to the japidviews directory. It can also be in the form of a Java class name: more.MyController.anotherTemplate.
  3. call other methods and render implicitly, i.e., action chaining.

The below example demonstrates all ways of template bindings:


    public static void foo() {
        Bar b = ...;
        if (cond1) {
            // implicit binding
            renderJapid(b);
        }
        else if (cond2) {
            // action chaining
            dontRedirect();
            bar(b);
        }
        else if (cond3) {
            // static linking
            render(new foo().render(b));
        }
        else {
            // explicit dynamic binding
            renderJapidWith(“more.MyController.foo”, b);
        }
    }
   public static void bar(Bar b) {
        // implicit binding
        renderJapid(b);
    }

In the above example, when cond1 == true, the template to render with is foo.html; when cond2 == true, bar.html will be used to render the data, etc. Note, JapidController.dontRedirect() must be called to avoid an HTTP redirect, since calling another action in Play! runtime will usually create an HTTP redirect. Please note, Play!'s original author does not like action chaining for some reason. In fact there is no way to do action chaining without creating an HTTP redirect with the classic Play! controller. The dontRedirect() opens up the possibility.

Use Japid to Render Email Content.

Japid has a replacement for Play!'s email rendering engine. The mechanism is very similar to the Play!'s email rendering flow, but fully takes advantage of Japid templates.

This is how:
1. Create a mail controller (a.k.a. mailer) in app/notifiers or any sub-directory. A mailer is conceptually equivalent to action controllers except it must extends cn.bran.play.JapidMailer. Here is a sample mailer:


public class CouponJapidMailer extends JapidMailer {
    public static void sendEditorEmail(String title, String content) {
        setSubject(title);
        addRecipient(“bing_ran@hotmail.com”);
        setFrom(“memberships <memberships@maimaijia.cn>”);
        // add an attachment
        EmailAttachment attachment = new EmailAttachment();
        attachment.setDescription(“A pdf document”);
        attachment.setPath(Play.getFile(“rules.pdf”).getPath());
        addAttachment(attachment);
        send(content);
    }
}

Given a mailer action sendNote() in:


app/notifiers/MyNoti.java

The send() action’s default template must be:


app/japidviews/_notifiers/MyNoti/sendNote.html

If the mailer is 


app/notifiers/org/MyNoti.java

then the default template is:


app/japidviews/_notifiers/org/MyNoti/sendNote.html

2. Create the email content renderer as you would do for any regular Japid view templates. You can use the full capacity of Japid of course, including layouts, tags, etc.

3. Invoking a mailer in your controller actions as you would invoke a static method. e.g.:


    // in a regular controller
    public static void feedback(String title, String content) {
        // ...
        CouponJapidMailer.sendEditorEmail(title, content);
    }

Note:

  1. The email sending process takes place in the current thread therefore is synchronous. This has impact on the scalability of sending large amount of emails simultaneously. This is an area for future improvement.
  2. The mailer can be invoked in the same way in Play! jobs.

Using the Japid Eclipse Plugin

First of all, the plugin is based on the PlayClipse project for Play! In fact the new plugin still keeps the name and tries to keep itself compatible with the default rendering engine.

Source code

- https://github.com/branaway/playclipse, branched from https://github.com/erwan/playclipse

Features:

  1. It integrates the Japid template transforming process to the standard Eclipse project incremental and full building processes, thus eliminates any manual process in applying Japid templates.
  2. The plugin as of now offers the same level of features that are in the original plugin for the groovy-based templates to the Japid template engine.
  3. Menu items and short-cuts to navigate between actions and Japid views, japid html templates and the derived Java files.
  4. An enhanced Play HTML editor that recognizes some Japid syntax, notably the back single quotation mark syntax – the flagship Japid syntax.
  5. Ctrl-click navigation in html views to actions, layout templates and tags.
  6. It has also fixed a few bugs coming with the original plugin and enhanced the pop-up menu in the views and editors.

Installation:

The plugin is in the eclipse-plugin directory of the Japid module.

  1. Just put the jar file in the dropins directory of the Eclipse installation and start/restart the IDE.
  2. You’ll be able to see a new menu named “JapidPlay” in the main menu bar. A new entry of the same name is also added to the context menu in the Java package navigation view, Java editor. A new html editor called HTML is also registered as an editor for html files. You’ll need to use this editor to edit HTML templates to gain the syntax highlighting, artifact navigation etc.

If you don’t see the JapidPlay menu in the IDE workbench window menu bar, please try starting the IDE with a command line option : 


$ ./eclipse -clean

Notes:

  1. The plugin has been tested with Eclipse Helios (3.6).
  2. If you have used the classic PlayClipse plugin, please remove it from the dropins directory of your Eclipse installation amnd use the -clean command line option to start the IDE.

Usage

First of all, right click on your Japid/Play project and invoke menu JapidPlay! -> "Enable Play! Nature" or the Japid transformation will not be integrated with the project building process, neither the popup menu will display the proper menu items.

The enablement of the Play nature does a few things:

  1. It adds a Japid builder in the project builders list, before the Java builder.
  2. The builder creating the necessary japidviews tree if it’s not there. This is the equivalent to the play japid:mkdir command.
  3. The builder also adds two files in the japidviews tree: SampleLayout.html in the _layouts and SampleTag.html in the _tags directory. These two files are not required by Japid per se. They are simply examples. Please leave them there since (actually the plugin will create them if you delete them.) any example views created by the Japid plugin reference them and there will compile-time errors without them. I figure this is good for Japid beginners, but it may change in the future.
  4. The builder does a fresh template translation and convert html templates to java source code, which is automatically picked up by the Java builder.

Now click on the controllers directory or sub-directory to select it and invoke “New Controller” command from wither the main “JapidPlay” menu or the context menu (by right-clicking on the package node). Of course you can create the class without bothering it.

Assuming you have highlighted the controllers.more node, the default controller created by the plugin looks like this:


package controllers.more;
import play.mvc.*;
import cn.bran.play.JapidController;
// make sure you have 
//      module.japid=${play.path}/modules/japid-head
// in your application.conf file, and "play eclipsify"
// if you notice the JapidController is not found.
public class MyController extends JapidController {
   public static void index() {
        renderJapid(“Hello world!”, 123);
    }
}

As you can tell, the sample controller renders data with the default Japid template. Now let’s try navigating from the action to the default view.

Move the cursor to anywhere in the action method, which starts from the public modifier and ends at the closing curly brace of the method. Now you can navigate to the view either opening the main JapidPlay menu and invoke the “Go to view” item or right-clicking to bring up the context menu and invoke JapidPlay! -> Go to view. Of course Ctrl-Alt-v is available if you’re a key-board only guy.

Since you don’t have the view ready yet, the plugin asks if you would like to create a view at the proper location. Saying “yes” and you’ll get a sample view created in the right location.


`extends SampleLayout.html
`args String s, int i 
`set title:"index"
hello ${s}, ${i}.
Here goes your Japid template content.
call a tag: 
`tag SampleTag “world”

It should have already compiled to a Java source file names “index.java”, and the Java code should compile clean, assuming that you have enabled the “Play Nature” on the project. If you don’t see the derived Java file in the same package, follow this procedure:


    if (you have enabled the “Play nature”) {
        invoke “JapidPlay! -> Disable Play! nature” on the context menu;
    }
    invoke “JapidPlay! -> Enable Play! nature” on the context menu;

I have found occasionally I need to re-enable the Play! nature to get the Japid auto-compilation going. This is an issue to be explored.

The Japid plugin automatically synchronize the html templates to the derived Java files if the project is set to build automatically:

  1. when you add a new template, a new Java file is derived from it. You can immediately spot any errors in the generated Java code and change your template to fix it. Here you get the full benefit of static typing.
  2. when you update a template, the derived Java file is also updated. Again, you get the error checking.
  3. when you delete or rename a template, the derived Java file is also removed or renamed accordingly.
  4. when you invoke the Project -> clean menu command, all the derived Java files are removed. If the “Build automatically” option is on, all the templates are translated to Java files, effectively equivalent to the play japid:regen command.

The template editor also does some basic error checking and rudimentary code completion, but it is far from being a sophisticated full-featured template editor. It does not

  1. edit html tags.
  2. do serious code completion.
  3. parse in the Java expressions.

But I have found it offers great assistance in navigating the code, which makes the users a lot more productive.

The plugin offers an HTML editor that is Japid-aware.

If you have already used another HTML editor in your Eclipse IDE, usually your html files are associated with them and are opened in one of them. You’ll need to use the HTML editor from the plugin to take advantage of some of the nice features.

In the Package Explorer, right-click on the template file and Open with -> HTML(Play!).

The current Play html editor is unfortunately not HTML-aware(something to improve on later), but it offers some nice Japid-aware features:

  1. highlight Japid constructs: Japid expressions, scripts, commands such as `tag, `extends, etc.
  2. Ctrl-click on layouts, tags, imports to navigate to the target files.
  3. navigate to the controller action that uses this template as the default templates with the Go to action context command, or simply ctrl-alt-a. I find myself using this key combination and ctrl-alt-v a lot to switch between the actions and the views.
  4. navigate to controller actions in the reverse route lookup expression: @controller.action(), again, with the Go to action command.
  5. navigate to the derived Java files, with the Go to generated Java file context command.

Invoking Actions in Views

Let’s image a porlet-like web page. It’s composed of multiple panels each of which displays totally different content. Let’s say we have already created a controller and corresponding views to display each of the content pane. How can we reuse all the controllers and views in the portlet page?

This is a page composition that is not supported by the default Play! rendering pipeline.

Japid provides a special command named `invoke or `a for action to help users to invoke a controller action right from a view template.

For an example, we have this controller:


package controllers.more;
import cn.bran.play.JapidController;
public class Portlets extends JapidController {
    public static void index() {
        renderJapid(“a”, “b”);
    }
   public static void panel1(String a) {
        renderJapid(a);
    }   public static void panel2(String b) {
        renderJapid(b);
    }
}

Highlight anywhere in the index() method and ctrl-alt-v and say “yes” to the question and you are in the index.html. Change it to something like this:


`args String a, String b
`invoke controllers.more.Portlets.panel1(a)
`a controllers.more.Portlets.panel2(b)

The invoke or the short form `a basically invokes the action method in the controller with the argument and includes whatever content the action generate right on the location.

I feel this is very intuitive for many developers to compose complex pages, although the original Play! developers do not seem to like this idea.

Advanced Caching with Invoke

Now the `invoke command can take one more option: a timeout value to cache the result from the action invocation.

Let’s change the above template a little bit:


    `args String a, String b
   `invoke controllers.more.Portlets.panel1(a)   `a controllers.more.Portlets.panel2(b), "10s"

I have attached a Timeout specification to the second action invocation. The timeout value is a string such as “1s”, “2mn” (“mn” for minute), “3h”, “4d” (“29d” maximum), to specify how long to cache the result content from the action.

There are another way to specify if the result should be cached and for how long: using the Play! CacheFor annotation on the action, like this:


package controllers.more;
import play.cache.CacheFor;
import cn.bran.play.JapidController;
public class Portlets extends JapidController {
   @CacheFor(“10s”)
    public static void panel2(String b) {
        renderJapid(b);
    }
}

The CacheFor annotation overrides any timeout spec in the `invoke command.

Now on to the “advance” part, nested caching.

What if the first level cached content is from a template that contains another cached `invoke? Will the outer cache “annihilate” the inner cache? The answer is “no”.

This is what will happen: the inner cache will “penetrate” the outer shell and operate by its own timeout pace. Consider a scenario where a complex home page (in our example the index.html) is cached for 20 seconds, but the headline news section (the panel2.html in our example) on the page will need to be updated very 10 seconds (or refresh every time a new request comes in).

There are two ways to specify cache controls:

  1. use the CacheFor annotation with the action method.
  2. append a timeout spec to the `invoke command. This will override any timeout value given by a CacheFor annotation on the action, if the annotation exists.

The controller:


package controllers.more;
import java.util.Date;
import play.cache.CacheFor;
import cn.bran.play.JapidController;
public class Portlets extends JapidController {
    @CacheFor(“20s”)
    public static void index() {
        renderJapid(“a”, “b”);
    }
   public static void panel1(String a) {
        System.out.println(“panel1 called”);
        renderJapid(a);
    }   public static void panel2(String b) {
        System.out.println(“panel2 called”);
        renderJapid(b);
    }   @CacheFor(“5s”)
    public static void panel3(String whatever) {
        System.out.println(“panel3 called”);
        renderText("
" + new Date() + "
");
    }
}

The view:


    `args String a, String b
   The outer most content is cached for 20 seconds, using the CacheFor annotation. ${new Date()}
    this part is never cached.
        `invoke controllers.more.Portlets.panel1(a)
    this part is cached for 10 seconds. Note the timeout spec with invoke overrides CacheFor annotation.
        `a controllers.more.Portlets.panel2(b), "10s"
    this part is cached for 4 seconds, specified with CacheFor annotation in the controller.
        `a controllers.more.Portlets.panel3(a + b)

With this composition pattern, the whole page will be cached for 20 seconds, and the panel2 will be cached for 10 seconds, the panel3 is cached for 4 seconds since the action is annotated with a CacheFor("4s"). The panel1 part will not be cached at all since there is no cache control at all.

If you have sharp eyes, you may notice that the content in a cached block is usually updated 1 second before the specified timeout value. The render result cache builds a mechanism to pre-expire an entry 1 second in advance. The first client to get the pre-expire is responsible to update the cache while other requests coming during the one second window will still get the cached entry until the entry is fully expired. This mechanism is to make sure the cache will perform seamlessly in a highly concurrent environment.

Debugging the Templates

Since all Japid templates are transformed to Java source files, debugging the views is as easy as debugging any Java code in Play!. Nothing fancy here.

I personally find it rare to need to debug the views, since usually it will work if the Java code compiles. That’s compile-time error checking at work. You’ll need to pay attention to the parameter list of the templates and make sure they match that in the actions that using implicit template binding.

Lastly, there is a handy command you can use to quickly log any data in your Japid templates. The command is natually called `log. 


`args String a
`log
`log “the value of a: ” + a
`log 1 + 2

The log command will print the string value of whatever Java expression following it to the system console, with template name and line number information, such as 


japidviews/templates/log.html(line 5): 
japidviews/templates/log.html(line 6): the value of a: Hello 
japidviews/templates/log.html(line 7): 3

By the way, you can use the log command without any arguments. You end up with just the template name and line number in the console, useful if you want to know where you are.

Use the Sample Application in the Module

There is a sample application distributed with the japid module in the JapidSample directory. It does not serve any real world purpose other than as a demo of Japid features.

This is how to run the sample:

  1. open the application.conf to make sure it has a proper reference to the japid module.
  2. run command play japid:regen to regenerate all the template Java code.
  3. if you would like to load it in Eclipse for example, you run play eclipsify command and open it in Eclipse.
  4. start the application and hit http://localhost:9000/, you’ll get a page with many links to different actions.
  5. follow those links to see how each features are used in a demo code.

Future work

  1. keep improving the Eclipse plugin
  2. find more ways to simplify japid syntax.
  3. keep improving the documentation.
  4. assimilate some fancy features from the Lift framework. Parallel action blocks comes to my mind.

Thanks for your interests in Japid!