The Quick Manual of Japid Engine with Play Framework

V0.9.10

Bing Ran<[email protected]>

Reference

Use Japid as a Generic Template Engine

Introduction

Japid is a Java-based statically typed text rendering templates system that aims to deliver the best possible performance.

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 main goal of Japid is for use in large, high-traffic and highly dynamic Play! bases web applications. To reach that goal, Japid transforms templates files to clean Java source code so that the rendering can run at the raw Java speed.

Due to its fast performance and low memory usage, Japid is a very good rendering system for Play applications targeting the Google App Engine runtime, which is very resource-constrained.

The high-performance does not come at the cost of advanced features such as page composition, tags, template inheritance, content caching, and server-side include.

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

The Design philosophy

I want:

• this template engine to have clean and practical syntax
• the templates to be strongly typed: all variables rendered in a template must be clearly declared as in a Java method. Developers get all the benefits of the strong typing: compile-time error checking, performance at runtime, being debuggable, etc.
• to use Java as the flow control and expression language. Any java classes and features can be very easily used in the templates.
• the best possible performance out of Java.
• it to be versatile to generate any text output and particular not limited to xml/xhtml content.
• to use right amount of convention over configuration.

I don’t want:

• it to be XHTML well-formatted, since the tool is used to generate potentially any text.
• it to depend on any other languages such as Groovy.

Mechanism

There are two ways Japid can be integrated with Play 1.2.x and later. In the classic way, Japid is participates in Play’s class loading and reloading process. All the controllers, models and Japid views are managed by the same Play’s class loader. This integration mechanism is called “pre-controller integration”. Since version 0.9.10, Japid provides it’s own class loading mechanism that is decoupled from Play’s class loading. Since the class-loading does not take place until the controllers pass control to the Japid view layer, the newer mechanism is called “post-controller integration”.

Pre-Controller Integration

• Japid engine is wrapped as a Play! module which must be configured in the application.conf file or the dependencies.yml file in the conf folder.
• Japid Templates are transformed to Java source files, automatically in a running Play! instance in DEV (development) mode, which then are picked up by the Play! runtime in the code change detection process.
• The Java classes that encapsulate all the layout logic can be invoked as plain java classes to generate text output, or they can be used reflectively with conventions in naming and location.
• A few command-line tools are also provided to generate Java source files from the templates.
• Master layouts are translated to abstract super classes, which is to be inherited by views.

Post-Controller Integration

In this mode,

• Technically Japid engine does not need to be configured to a Play’s instance. It is used in a way that’s very similar to how rendering engines such as Velocity and Freemarker are used in web applications.
• Japid is a simple, self managing layer that sits after the controllers. Japid manages its own template compiling to Java classes and class loading.
• File change detection and class reloading takes place after the code in the controller has been executed.
• The Java intermediaries are not supposed to be invoked directly from within the controllers. They are wrapped in a special controller super class named “JapidController2”.

The post-controller Japid decouples the view layer from the controller and model layer at class loading level. It further avoids cross interference when hot swapping new code in DEV mode. This can translate to further time saving in quickly making changes in DEV mode.

Another great advantage in using this model is that errors in compiling or running Japid views will be picked up by the Play’s nice error displaying page, another great debugging tool and time saver.

First you need to get yourself familiar with the “Play! module concept”:

- http://www.playframework.org/documentation/1.2.2/modules
- http://www.playframework.org/documentation/1.2.2/dependency

The following is a sample session.

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.9.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.9.10

$ 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-0.9.10  // or whatever the version number is

Since some versions ago, it’s recommended that developers use dependencies.yml to configure modules or “dependencies”. In case of Japid, add this line to the dependencies file:

    - play -> japid 0.9.10

The next thing to do is to create the default directory structure required by Japid, if you want to use the “pre-controller integration” model. From the app root:

$ play japid:gen

The japidviews tree is now created in the app directory

If you’re using the so called “post-controller integration” model, do nothing at this stage.

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 about your typing skill.

Runtime Directory Structure of Japid in Play! applications

Pre-Controller Intagration

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

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

Notes:

1. the _javatags sub-directory contains any Java code you want to use in your templates. Any java classes defined in the japidviews/_javatags will be imported in the generated template java code. Any static members will be imported too. There used to be a file named JapidWebUtil in Japid versions earlier than 0.8.6. It is not enforced anymore and is deprecated.
2. the _layouts sub-directory contains global layouts that are accessible to all view templates. However as explained below, Japid layouts can be placed 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.
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.
4. the _notifiers sub-directory contains email templates coded in Japid. There is a section for this later in this document.
5. The other nodes of the tree are created to match the structure of the controller and actions therein. For each controller there is a directory 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 note though, the layouts of the template files are 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.

Post-Controller Integration Japid File Structure

The post-controller japid model assumes a folder named “japidroot” as the root of the “japidviews” tree. The japidroot is located directly in the application root, rather than the app folder. This means it’s NOT on the application classpath hence the application’s class loader does not see any of those Java classes derived from the japid view files.

Japid Syntax

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

For your information, the Microsoft Razor Template Engine is a source of inspiration for some recent syntax improvement, particularly the consolidation of the usage of “`”, or “@” since version 0.8.4.1.

Note:

1. To escape the special markers used in various syntax constructs, please prefix them with the escape sign “~”, such as:

~~ for ~
~@ for @
~$ for $
~% for %
~& for &
~* for *

2. To join lines, please use a back slash “\” immediately followed by a new line. The back slash and the new line symbol will be simply swollen by the parser.

@ Str\
ing a = "hello\
 "; \
String b = “world”;
message:\
 ${a+b}

is equal to:

@ String a = “hello ”; String b = “world”;
message: ${a+b}

The delimiter: ` and @

The delimiter plays a very important role in dynamic templates:

1. It starts a directive or command, which is instruction to the code generator to create special Java source code.
2. It starts a line of pure Java code to be placed in the generated code.
3. It ends 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 delimiter.

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

Originally the back quote has been selected as the special character, because:

1. The back quote is the most left upper key on most keyboard ( except the escape key ) so it’s easy to remember.
2. It’s not a key combination like the #$%, which requires pressing two keys: the Shift and 3, 4 or 5, and with both hands. I think it’s easy for even the most untrained fingers. Comparing `get title` with #{get “title”/}, the Japid syntax requires 10 key pressings and the latter requires ~20 key pressings, including all the shift keys.
3. The back quote is rare enough in normal text content so it saves all the escapes.
4. In most Linux shell, the ` is a very important key that indicates “command substitution”: the part inside the quotes will be executed and the result be substituted in the place. I think Japid uses the symbol in exactly the same spirit.

A little annoying problem with ` is it appears less visible in some fonts, although not an issue for the fixed-width fonts that source code usually is displayed with.

Since version 0.8.4.1, one can use the ‘@’ sign in lieu of the the back quote. In some keyboard layout, the back quote is difficult to access while the “at” sign is a lot easier. The result is that both the back quote and the @ sign are valid delimiters, but they cannot be used in the same template file. There is no global configuration to specify which one is the special marker. Instead the system determines the marker file-by-file. This is how the parser determines which delimiter is used in template file:

1. It scans the template file for the first occurrence of a line that starts with either the back quote or the at sign and use the character as the Japid delimiter for the specific file.
2. If for some reason the marker cannot be determined, the back quote is used as the default.
3. To make sure the parser picks up the correct marker, one can add a single line on the top of the document and the single line contains the intended marker to use, like this:

`
the rest of the file

or:

@
the rest of the file

One of the ramifications is that a project can contain template files and some of them are using the ` as the special marker and the others using the @ sign.

Note: to escape the delimiter, please use a single back quote followed by the delimiter:

``this is normal text and so is `@

The rest of this document uses the single back quote(`) as the delimiter in most of the cases.

Views, Tags and Layout

There are three types of templates in the Japid system:

1. Views: the templates that play the central role in rendering data. Most of the rendering logic is being carried out 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 extend layouts and pass text snippet or variables 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.

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

`get title` is to retrieve a text block named “title”, to be passed from any child views that inherited from this layout. The second ` can be left out if there is no more meaningful letters in the rest of the line.

A `get xxx command is usually matched by a `set xxx command in the views that inherit from this layout. The set command assigns 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.

Invoke the Child Layout: `doLayout

This command is to let the child template to render itself and substitute the command with the result. This command is pretty much the marker of templates of layout type.

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"
`if count
    `for (int i > 0; i < count; i++) {
        hello $user.name, and you are `tag showAge user.age`.
    `}
`

There are a few new syntax here:

Import Java Classes to Templates: `import

Purpose: same as in java.

Note:

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

Specify the Layout for a Template: `extends

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

1. the short file name: master.html, or preferrably without the extension: master. The file must be either in the same directory or in the app/japidviews/_layouts directory.
2. the file in full path: japidviews.mypackage.master
3. a file in a sub directory, using a leading “.”: .sub.master

Note:

• there is no ending `.
• starting from version 0.7, the layout can take parameters right from the extends directive, as in

`args String a, int b
`extends aLayout(a, b +1)

Of course the layout must declare to accept the arguments with the `args directive.

The classic syntax style is still supported:

#{extends "mater.html"/}

Please note: you should use double quotes to enclose the layout name in the “classic” Japid style. The profuse use of single quote in Play!'s templates are mostly replaced with double quotes in Japid’s classic style to better match Java syntax. Some Japid’s recent syntax goes even further to remove those quotes.

Specify the Data Objects to Render: `args, or `()

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

Note:

1. some people may find the `() more expressive than the `args syntax, but they’re functionally identical: `(String a, Integer b) === `args String a, Integer b.
2. Data to be rendered must (almost) be declared passed to the templates via the `args directive. However There are a few Play! specific data that are implicitly available, as explained later in this document.
3. 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 japidviews._layouts.*;
import japidviews._tags.*;
import japidviews._javatags.*;
import models.*;
import controllers.*;
import play.data.validation.Validation;
import play.mvc.Scope.*;
import play.data.validation.Error;
import play.mvc.Http.*;

Note: One advantage of using `() is it can span multiple lines, useful when the argument list is long. Of course you can use the `args and the line continuator “\” to simulate multi-line argument list too.

{here I’m using the alternate marker @ instead of the default `}
@(
    my.Object o,
    int i,
    String s
)

Since 0.8.8, template parameter can be annotated with a default value for use with tag invocations with named arguments. E.g.:

    `args String msg, @Default(new String(“m2message”))String m2, Integer age

or:

`(
    @Default(“message 1 default value”) String msg, 
    @Default(new String(“m2message”)) String m2, 
    @Default(20) Integer age
)

Note:

1. due to parser limitation, there cannot be a new-line between the annotation and the parameter type.
2. It’s Default, not default.

Create a named text block: `set

Purpose: to assign a text block to 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 command is 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, each of which should define a different text block.
3. Limitations:
   1. If there is any reference to variables in the text block, 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.

Condition Statement `if

First of all you can use the plain Java if-else-statement:

`if (cond) {
    xxx
`} else if (cond2){
    yyy
`} else {
    zzz
`}

The cond and conds must be boolean values. This sometimes forces people to write tedious code like this:

`if (aString != null && aString.length() > 0) {
    xxx
`}

The Japid template base class has a method asBoolean(Object) that takes any object and infers a boolean value from it to any templates it generates. So you can improve the above a little bit:

`if (asBoolean(any_java_expression)) {
    xxx
`}

The asBoolean returns true if the argument is

1. none-empty string.
2. a collection that has at least one element.
3. an integer or long value that is not zero.
4. an array that has at least one element.
5. an object that is not null.

But some people really like the if to be smarter. So I have decided to enhance the if statement syntax to add some smartness to it, like in Groovy:

`if expr1 {
    xxx
`} else if expr2 {
    yyy
`} else {
    zzz
`}

`if (asBoolean(cond)) {
    xxx
`} else if (asBoolean(cond2)) {
    yyy
`} else {
    zzz
`}

But wait, you can go one more step further and get rid of the curly braces. Yes you can:

`if expr1
    xxx
`else if expr2
    yyy
`else
    zzz
`

Remember to use a ` to close the if-else statement.

What if you want to negate the condition? Use “!” of course.

`if ! expr1
    xxx
`else if ! expr2
    yyy
`else
    zzz
`

In summary,

1. if you wrap the expression in “()”, you must use the full Java syntax. The expression must be of a boolean type, otherwise it can be any data type. But check the conversion rule listed above and see if the outcome is what you’re looking for.
2. If you use “{}”, you must them all the way through. You cannot mix them u

You get the idea.

BTW, in case you want to write the if-else statement in one line, you can do it this way:

`if xxx` foo `else` bar `

What happens here is that each of the single back quote switches the current mode between script mode and plain text mode. The above line has odd number of ` therefore it’s still in script mode. However since the “\n” character always changes the current mode to plain text mode, the next line will be in plain text mode. If you have more text to display, you’ll need to add another ` like this:

`if xxx` foo `else` bar ` `more text to display

Note that I don’t use two consecutive back quotes. The reason is `` is treated as a escape sequence for a ` literal.

Iterate over collections, arrays: `for

Actually this is the plain 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. ${name}
`}

Starting from version 0.7.1, the for has an “open” form that gives template authors access to a few implicit variables related to the looThe variables are explained in the following section, but here is the syntax, basically you leave out the “()” and the "{}"

`String[] names = ...;
`for String name: names 
   Your name is: $name,
    the total size: $_size,
    the current item index: $_index,
    is odd line? $_isOdd
    is first? $_isFirst
    is last? $_isLast
`

• Since this form involves multiple method dispatching, it’s slower than the raw for loop. But the difference is in micro-second scale and probably does not matter.
• you cannot use “{}” with the “open for loop”. This is invalid:

`for String name: names { 
    xxx
`}

• there is _isOdd but there is no _isEven
• continue does not in open for loops, neither does break

Enhanced looping: `each

Note: it’s been deprecated in favor of the the “open for” format.

The each command creates a loop construct that makes available additional looping attributes for the template authors 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 new line.
2. In fact the above syntax is a standard way to invoke a tag with a callback body. See later in tag invocation.
3. The variable names is the collection to iterate on. It can be of any of the following Java type:
   1. Collection
   2. Iterator, in which case the _size property cannot be determined before hand and is given a value of -1.
   3. Iterable, in which case the _size property cannot be determined before hand and is given a value of -1.
   4. array of anything
4. The construct after the vertical line is the declaration of 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:

Java Expression: ${expression} and ~{expression}

The string value of a Java expression can be interpolated in text stream using the ${} syntax, as is used in Play’s Groovy based templates. The {} signs can be omitted if doing so won’t make the expression fuse with the rest of the context thus cause confusion to the compiler (or your eyes). For examples:

${user.name} == $user.name
${user.name.length()} == $user.name.length()
Japid parser is greedy in matching the Java expression:
$user.age + 10! == ${user.age + 10}!

Japid parser uses greedy logic to find the end of $ expressions without the {} pair:

It searches back from the end of the current line and matches the longest possible valid Java expression.

Note: the ${} notation does not escape the string value of expressions to make it HTML safe, like what Play! does. One can simply do:

${escape(expr)}

to get the effect. The escape() 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. See JavaExtension.

Another way to make the string value of expressions HTML safe is to take advantage of the escaped expression notation, i.e., the ~{} notation.

The ~{} does exactly the same as the ${escape(...)}. So if you are not concerned about the slight performance penalty caused by the escape method call, you can safely use the ~{} notation as the safe expression throughout the entire application and forget about ${}.

BTW, ~expr also works.

New! the Elvis operator: ?:.

Quoted from the Groovy online documentation:

The “Elvis operator” is a shortening of Java’s ternary operator. One instance of where this is handy is for returning a ‘sensible default’ value if an expression resolves to false or null.

Well it’s not exactly that I have implemented the Elvis in Java:) What I have added is the ?: combination that works only inside of ${} expressions. An example:

`args String name, Address addr
The name is ${name ?: “empty”}
The street number is ${addr.streetNo ?: “not present”}

Here is what will happen:

If the evaluation of the Java expression before the Elvis operator results in an empty string or an NPE is thrown during the evaluation, the default string value is displayed.

You can use "" as the default string, which effectively achieve “safe bean property navigation”: ${my.fancy.expr ?: ""}.

Imagine what you have to do if without using this handy operator? Perhaps something like this:

`args String name
The name is: `if name` $name `else` empty! ` 

Of course you can use the Elvis operator with the escaped expression notation: ~{}.

Safe Property Navigation: `supressNull on

An expression like $user.name.length() can cause potential problems if any of the nested properties is null, in which case the template will throw NPE. There is a 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 property navigation.

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

The second $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. what you end up with is an empty string "";

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

Again, you might find the Elvis operator “?:” a lot more flexible in dealing with nulls and empty variables.

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

Back to the view template:

user.html

@import models.mymodels.User
@extends master
@(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 named showAge. Think of a tag as a function defined in a separate file. Here is the tag file:

showAge.html

@(int age)
you are $age years old

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

The tag invocation has an alternative:

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

which looks more like function calls.

And the `tag command can be further shorten to `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, because a new-line character is a valid tag closing symbol.

Since version 0.8.5, Japid also supports invoking tags with named arguments:

`t tagName(argName1=arg1, argName2=arg2...)`

The caller side does not need to provides arguments for all the parameters. The missing ones default to null or default primitive values as defined by the Java specification.

Note: you cannot mix these two conventions. You either use arguments without any name prefix or all the arguments must use the named format.

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 please note that one can use “/” in lieu of “.” but I prefer the dot syntax.

The default Play! templates assume that all tags are located in the app/views/tags directory, just like the layouts which are assumed to be in the app/views. It will get too crowded when projects get bigger. Japid gives authors the flexibility to organize the layouts and tags in the whatever way the authors see fit, e.g., in the same directory as the view templates or sub-directories of it.

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 block. Note: the Japid parser requires the presence of this separator even if the template body 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’ is 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 parameters passed to a tag are rendered by a `doBody arg1, arg2... command in the tag file, as explained in the Tag Definition later in this document. Or one can use the renderBody(...) to get the result as a String in the template.

Note: the callback template block is optional and can be left out, such as:

`tag fancyTag "hello"

In the above invocation, the doBody in the fancyTag has no effect.

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 passes matching arguments to the passed-in template. This behavior is sometimes referred to as “call-back”.

With some imagination, 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 placed anywhere in the japidviews tree.

New feature since 0.8.9.4: sometimes authors may want to store the doBody result in a local String variable. One can acheive that using a special operator “->”, the pointer operator as in C, after the doBody callback. E.g.:

`doBody “hello”, 123 -> body
`// now a new variable named body of type String is defined in the current scope
Before body

$body
After body

Use tags to include static content

Some other template engines provides “include” directive to include static content in the templates. In Japid a tag without any parameters is effectively static content that can be “included” in other templates by the normal tag invocation syntax:

`t header
...
`t footer
`t disclaimer

So basically you throw the static content in the same directory where the main templates reside, or simply in the _tags directory, and invoke it with `t, then effectively you get static include.

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.

More about Passing Data to the Layouts

Previously I have explained how to use the 'set command to create a named text value and use the `get in the layout to place the value in the output.

There are two other ways to pass data from the child templates to the layouts.

Passing data in the `extends Directive (new in Japid v0.7)

The extends directive allows passing objects to the layout in this way:

child template

`args String a
`extends myLayout(a, 123, “home”)

The layout

`args String a, int b, String c
do whatever with them

Smells Scala?

The only limitation is the args to pass must either be from the arg list of the current template or a new object created inline. You cannot declare a variable somewhere else and pass it to the super class, like in:

` String a = "hello"
`extends myLayout(a)

Define a local method with `def

The `def command defines a local method that returns a String. The method can then be invoked in the same templates. def blocks are considered as local tags. It’s used to wrap a piece of rendering logic and presentation that can be reused in the the same template or its parent/children templates. def blocks can take parameters. You can invoke real tags from within the def body too. Using the local methods is just like calling a method.

An example:

The child template

`extends defLayout
`def foo
    `String s = “hi there”;
    hello $foo2(s)
`
`def foo2(String p)
    hi $p!
    `tag SampleTag p
`
{ the old syntax of def }
#{def bar}
    `String s = “hi2”;
    hi $s!
#{/}
#{dummyTag get(“bar”)/}
{ can call it directly }
$foo()

The `def foo block defines a method named foo. The method body declares a variable s and then calls another local method named foo2 with the variable. The foo2 is defined to take a String argument. Both return a string which is the result of interpolating the data in the text of the bodies. The arguments received from the `args statement are available in the method bodies.

The methods defined in the templates can be invoked with reflection. Japid provides a predefined method named get (not to be confused with the `get) that can be used to invoke the method. In the above example, #{dummyTag get("bar")/} is the “old” classic Play! way of invoking a tag. The argument is actually a function call to invoke the bar method defined above it (in the classic Play! style again). One limitation though, the get method can only invoke method without parameters. Future Japid will probably have another get that can take additional arguments.

The get() can be used in either the super class or the child class to reflect methods. The following example uses it call the foo() defined in the child.

defLayout.html

$get(“foo”)
#{doLayout/}

Effectively the data is passed from the child to the layout.

Using Implicit Data Objects in Templates

Although it has been said that all data passed to the templates must be declared, there are a few Play! specific objects, implicitly available in Japid templates. If you open any Java source code derived from the templates (including the views, layouts and tags), you’ll see in the main body that there are a few objects declared:

    final Request request = Request.current();
    final Response response = Response.current();
    final Session session = Session.current();
    final RenderArgs renderArgs = RenderArgs.current();
    final Params params = Params.current();
    final Validation validation = Validation.current();
    final cn.bran.play.FieldErrors errors = new cn.bran.play.FieldErrors(validation);
    final play.Play _play = new play.Play();

First of all, please use the “Implicit objects available in a Play! template”:http://www.playframework.org/documentation/1.1.1/templates#implicits as the background reference.

Japid implicit objects are comparable to those available in the standard Play! templates, but is not strictly one-to-one matching.

1. request: same as in Play! standard
2. response: not directly available in Play! standard, not advisable to use
3. session: same as in Play! standard
4. renderArgs: not directly available in Play! standard. Objects passed to this container can be retrieved in templates as `MyType my = (MyType)renderArgs.get("aKey");.
5. params: same as in Play! standard, not advisable to use since all parameters are supposed to be passed in via the `args directive.
6. validation: not directly available in Play! standard
7. errors: comparable to the variable of the same name in Play! standard.
8. _play: same as the play variable in Play! standard. The leading underscore is added to avoid possible name collision with user data.

There are a few static objects made available by the JapidPlayAdapter import.

1. flash: a wrapper class FlashWrapper that wraps the Play! Flash class.
2. message, same as in the standard Play! templates.
3. lang, same as in the standard Play! templates.

There is an out variable that is the content buffer for the current template. It’s an instance of StringBuilder and you can append content to it if you want. Use of out is not advisable.

Now I’ll describe some of the most useful implicit objects.

The flash Object

The flash scope stores information that will be available in the current and the next HTTP request, including a redirect.

See Flash and Session for the basic information.

The flash object is an instance of cn.bran.play.FlashWrapper, which wraps the Play! Flash class and provides a few handy methods,

1. hasError(): true if there is a message associated with the key “error”. This message can be created by invoking the error(...) method of the standard Flash object.
2. error(): return the message associated with the “error” key.
3. hasSuccess(): true if there is a message associated with the key “success”. This message can be created by invoking the success(...) method of the standard Flash object.
4. success(): return the message associated with the “success” key.

An example:

In the controller:

    
    public static void flashbad() {
        flash.error(“something bad”);
        // redirect to 
        flashout();
    }
   public static void flashMsg() {
        flash.put(“msg”, “a message”);
        // redirect to 
        flashout();
    }   public static void flashgood() {
        flash.success(“cool”);
        // redirect to 
        flashout();
    }
    
    public static void flashout() {
        renderJapid();
    }
    

In the view:

`// this is for demo the flash object, which is a wrapper of the Play’s flash object
`if flash.hasError() 
    $flash.error()
`else if flash.hasSuccess()
    ${flash.success()}
`else
    `if flash.contains(“msg”)
        the message: $flash.get(“msg”)
    `else
        oh well
    `
`

Note we’re using the “open if-else” statement for fast typing. Of course you can do:

`if(flash.hasError()){ 
    $flash.error()
`} else if (flash.hasSuccess()){
    ${flash.success()}
`} else {
    `if (flash.contains(“msg”)) {
        the message: $flash.get(“msg”)
    ` } else {
        oh well
    `}
`}

It’s plain Java stuff.

New: flash.get("msg") has been made simpler: flash("msg")

Validations and errors

The Play! validation is a good read. Get yourself familiar with that.

An object validation of the Play! Validation type is available in Japid templates. You can use the API to work with the validations and errors directly.

• Controller action:

    public static void validate(String name, Integer age) {
           validation.required(“name/姓名”, name);
           validation.required(“age/年龄”, age);
           validation.min(“age”, age, 10);
           renderJapid(name, age);
    }

• the view

`args String name, Integer age
`if validation.hasErrors()
   
Oops…
   `for Error error: validation.errors()
        
$error.getKey() : $error
    `
`else
    name is: $name, age is: $age
`

Compare this to the Play! version:

#{ifErrors}
 
   
Oops…

 
   #{errors}
       
${error}

   #{/errors}
 
#{/ifErrors}
#{else}
   Hello ${name}, you are ${age}.
#{/else}

and you’ll notice that Japid is a little “raw”.

You can retrieve an Error object associated with a key using:

validation.error(key)

You can also use the errors object:

errors.forKey(key)

Which is simply a wrapper to the validation object. I feel like removing the errors implicit object in the future.

New:

1. validation.hasErrors() has been made simpler: hasErrors(), just a static method invocation to the Validation
2. validation.errors() has been made simpler: errors(), just a static method invocation to the Validation
3. To get the errors for a field/key: List<Error> errors(String key)
4. To get the first error for a field/key: Error error(String key)

So the first example can be made simpler:

`args String name, Integer age
`if hasErrors()
    
Oops…
   `for(Error e: errors()){
        
$e.getKey() : $e 
    `}
`else
    name is: $name, age is: $age
`

Customizing the validation messages

The default messages for each is in the $PLAY_HOME/resources/messages and I copied here:

validation.required=Required
validation.minSize=Minimum size is %2$d
validation.maxSize=Maximum size is %2$d
validation.email=Invalid email address
validation.range=Not in the range %2$d through %3$d
validation.min=Cannot be lower than %2$d
validation.max=Cannot be greater than %2$d
validation.match=Must match %2$s
validation.isTrue=Must be checked
validation.equals=Must be equal to &{%2$s}
validation.invalid=Incorrect value
validation.future=Must be in the future
validation.after=Must be after %2$s
validation.past=Must be in the past
validation.before=Must be before %2$s
validation.object=Validation failed
validation.notFound=Object not found for id %2$s
validation.url=Not a valid URL
validation.phone=Not a valid phone
validation.ipv4=Not a valid IP address
validation.ipv6=Not a valid IP v6 address

You can override any of these in your conf/messages file.

For example, I can use Chinese as the error message:

    validation.required=不能为空
    validation.min=不能小于 %2$d

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. If you intend to use post-controller Japid integration. Please use the cn.bran.play.JapidController2 as the super controller class instead.

Explicit Template Binding (Pre-Controller Integration only)

Since all Japid 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 the 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 needs to wrap it in a cn.bran.play.JapidResult object and throw it out, like this in a controller action:

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

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, 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 and when are the template files translated to Java source code?

Three ways and timing.

Conversion method 1: command-line tools (pre-controller integration)

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

1. play japid:mkdir: check the proper japidviews directory tree and create missing elements if necessary.
2. play 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. play japid:clean: remove all generated Java source files derived from the templates.
4. play 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 the actions.

However as explained before, implicit template binding is a lot more flexible and does not require the use of the code generation tools. See the next section of this document.

Tip! Let me show you how you can configure these commands in Eclipse to make using these commands less troublesome if you are using Eclipse as the main IDE to develop applications.

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 (change this to your start script of your Play! installation).
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 with just two clicks.

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 the Play! installation or the 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 newly added/changed template files automatically. Java files derived from removed templates will get removed automatically too.

Note: for the IDE to display any changes made to the derived Java files, it’s highly recommended to turn on auto-refresh on external file changes. Take Eclipse for an example:

1. Open the Window menu in the main menu bar and open the Preferences menu item.
2. Open the General -> Workspace panel and check the Refresh automatically checkbox.

Now the artifacts of Japid transforming process will be displayed instantaneously or with a short delay, depending on the size of the project and the OS you’re running. If you have an error in your template, the derived Java file will be marked with an error marker and you can take a look at it to find out what’s wrong with it.

Conversion method 3: using the Japid plugin for Eclipse (pre-controller integration for now)

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:

• Pros:
  1. fast, since this is a regular Java class instantiation and method invocation.
  2. statically linked and thus there is compile-time check of argument binding.
• Cons:
  1. verbose: the classes need to be imported; the results need to be thrown out.
  2. strict in workflow: one must write the templates first and convert them to Java classes (manually or automatically, depending on the development environment) before they can be used in controller actions.

Implicit Template Binding

To decouple an action and the template it defaults to render, the JapidController or JapidController2 provides 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 implicit argument binding binds arguments by position, just like in any java method invocations. One does’t need to match the names of the variables in the action with those in the templates.

• Pros:
  1. a lot shorter.
  2. the templates do not need to exist and compiled to Java classes before template authors writing the action code.
• Cons:
  1. slightly slower, usually less than 1 μs, since it uses reflection to invoke the rendering code.
  2. no compile-time check on the parameters.
  3. need to match the directory structure of the japid templates to the controllers'. The play japid:gen or the Eclipse plugin would help to make it less a problem.

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.

You can specify the target target template in the same default directory using the “@” notation:

    renderJapidWith(“@anotherTemplate.html”, bar), or
    renderJapidWith(“@anotherTemplate”, bar)

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 trigger 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! controllers. The dontRedirect() opens up the possibility.

Invoking Templates with Named Argument

Since version 0.8.5, I have added support for invoking templates/tags with named arguments.

    renderJapidByName(named(“name”, “my name”), named(“age”, 100));

As of now, we’re not using the parameter name discovery mechanism provided by Play’s name enhancer.

The above calling convention offers a little advantage in that developers can omit some arguments provided they’re null.

Invoking Actions in Templates

Sometimes I call this feature “dynamic server-side include”.

Let’s consider 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 controller actions and corresponding views to display each of the content panels. How can we reuse all the controllers and views as sort of “components” 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.

In a controller:

package controllers.more;
import cn.bran.play.*;
public class Portlets extends JapidController /*or JapidController2*/ {
    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 incorporate whatever content the action generate right on the spot. Each of the controller action and view pairs becomes a reusable unit of component. This is a lot more powerful than other mechanisms such as tags since you have the full Java in your hand.

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

The `invoke command can take one optional argument: 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” and “4d” (“29d” maximum), to specify how long to cache the result content from the action.

There is 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);
    }
}

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

Now on to the “advanced” 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 cache 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).

An Example:

The controller:

package controllers.more;
import java.util.Date;
import play.cache.CacheFor;
import cn.bran.play.*;
public class Portlets extends JapidController /*or JapidController2*/ {
    @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 one second before the specified timeout value. Japid builds a mechanism to pre-expire an entry 1 second in advance. The first client to get the pre-expire is responsible for updating 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 be updated by only one thread thus perform seamlessly in a highly concurrent environment.

how to penetrate the cache programmatically?

Since version 0.9.4.4, programmer have a couple of APIs in the JapidController to control the use of a cached JapidResult that is resulted from the use invoke in the Japid templates.

1. public static void ignoreCache(): use this method to tell Japid not to use any cached JapidResult in the current request processing cycle.
2. public static void ignoreCacheNowAndNext(): use this method to tell Japid not to use any cached JapidResult in the current request processing cycle and the next cycle. The idea is to ensure a redirect after change will see the latest state in the database rather than the stale rendered results from previous rendering.
3. public static <C extends JapidController> void evictJapidResultCache(Class controllerClass, String actionName, Object... args): use this method to evict a cached Japid result resulted from a Japid directive invoke. It can be used in a controller action to invalidate a cached result from calling the controller action with the specified arguments.

Currently all cached Japid invoke results are stored with keys synthesized with the controller name, action name and the arguments. The id attribute of the CacheFor annotation is not yet supported.

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”:http://www.playframework.org/documentation/1.1.1/emails, but takes full advantage of Japid templates.

This is how:
1. Create a mail controller (a.k.a. mailer) in app/notifiers or any sub-directory of it. A mailer is conceptually equivalent to an action controllers except it must extend cn.bran.play.JapidMailer or cn.bran.play.JapidMailer2 if you’re using JapidController2. Here is a sample mailer:

public class CouponJapidMailer extends JapidMailer /* or JapidMailer2 */ {
    public static void sendEditorEmail(String title, String content) {
        setSubject(title);
        addRecipient(“[email protected]”);
        setFrom(“memberships <[email protected]>”);
        // add an attachment
        EmailAttachment attachment = new EmailAttachment();
        attachment.setDescription(“A pdf document”);
        attachment.setPath(Play.getFile(“rules.pdf”).getPath());
        addAttachment(attachment);
        send(content);
    }
}

• The send method is the counterpart of renderJapid(...) in regular controller. It searches for the japidviews/_notifiers directory for the matching template. e.g.:

Given a mailer action sendNote() in:

app/notifiers/MyNoti.java

The send() action’s default template is:

{japid root}/japidviews/_notifiers/MyNoti/sendNote.html

If the mailer is

app/notifiers/org/MyNoti.java

then the default template is:

{japid root}/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 it is a synchronous process. 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 Play! jobs in the same way.

Using the Japid Eclipse Plugin (Pre-Controller Integration Only)

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 provides a few “wizards” to help create Japid Play! classes/files.
2. It integrates the Japid template transforming process to the incremental and full project building processes of Eclipse, thus eliminates any manual process in applying Japid templates.
3. 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.
4. It enables some menu items and short-cuts to navigate between actions and Japid views, japid html templates and the derived Java source code.
5. It provides an enhanced Play HTML editor that recognizes some Japid syntax, notably the back single quotation mark syntax – the flagship Japid syntax.
6. It enables Ctrl-click navigation in html views to actions, layout templates and tags.
7. 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. 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 

Got troubles?

1. If you have used the classic PlayClipse plugin, please remove it from the dropins directory of your Eclipse installation and use the -clean command line option to start the IDE.
2. Another trick is to remove the plugin jar before starting Eclipse. Once you’re in, shut it down. Put the jar in the dropins and start the IDE again.

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 creates 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 be 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 the main “JapidPlay” menu or the context menu (by right-clicking on the package node). Of course you can create the class without bothering the wizards.

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-{version}
// 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 very handy here.

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 been compiled to a Java file named “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 synchronizes 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 and is placed in the same package. 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 immediately, 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.

Navigating in the views

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. highlighting Japid constructs: Japid expressions, scripts, commands such as `tag, `extends, etc.
2. Ctrl-clicking on the layouts, tags, imports directives to navigate to the target files.
3. navigating 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. navigating to controller actions in the reverse route lookup expression: @controller.action(), again, with the Go to action command.
5. navigating to the derived Java files, with the Go to generated Java file context command.

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.

If you need to output more monitoring information to the console or to the generated content, please read on.

Logging variables to the console

There is a handy command you can use to quickly log any data in your Japid templates. The command is naturally 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.

Traceing template nestings in the output

A page of any complexity may have comlicated nestings: the layout, lots of tag use, and tag use in tags, nested action invocation, etc. As the template size grows, it gets harder and harder to easily follow what part of and html/json source code has been generated from what japid view file.

Since Japid 0.9.3.3, there are a few more application.conf settings and a new template directive to help you trace the template nestings.

japid.trace.file = on/off

Used in the “application.conf” file, when the value is “on”, a line of comment text is printed to the rendered content:
for html/xml content types:

<!-- enter: “japidviews/...” -->

<!-- exit: “japidviews/...” -->

/*enter “japidviews/...”*/

exit: "japidviews/..."

japid.trace.file.html = on/off

The switch controls the tracing of html/xml rendering templates specifically. It overrides the japid.trace.file setting.

japid.trace.file.json = on/off

This switch controls the tracing of the templates that generate jons/javascript mime types. Note, you can use `json or `javascript directive to force the content type of any templates.

`tracefile

This a directive for use in template and control the per-file tracing. When `tracefile on|yes|true is present in a template file, the tracing of this file is enabled, otherwise the tracing is turned off.

This directive overrides any settings in the application.conf file.

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.

The same app has been ported to using Post-Controller model, as in the JapidSampleDecoupled folder.

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 the demo code.

Use Japid in Modules (version 0.8.7 or later)

Play modules are used for

1. providing development and runtime tools.
2. Composing multi-aspects big applications, with each part of separated functionality as a module.

Let see how we can use Japid in Module for application composition.

The way Japid is used in modules is almost the same as it being used in a standalone application. However, The Japid template files need to be compiled to Java files separately from the “main” application. The Japid tool won’t detect any changes in the template file in the modules. Therefore if one makes changes to the Japid files in a module, he/she must compile the file from within the module.

Here are the steps:

1 The “play japid:xxx” requires the currrent directory is a valid application. Therefore we need to put a dummy application.conf in the module’s conf directory.
2 Create a reference to the Japid module either in the application.conf or follow the new dependency management model and add an entry in the dependencies.yml file, like

self: play -> mymodule 0.1
require:
    - play
    - play -> japid 0.8.10

Then run

play deps

Or:

play deps --sync

3. Create controller and Japid templates files as in usual Japid applications. You can use the play japid:xxx commands to manipulate the Japid assets as you wish.

4. Update the routes file in the module to set up the URL access patterns, again as usual.

Back in the main application, set up your main app’s dependency on your module as usual and update your “routes” file to create an access path to your modules, like

      /mymodule                                 module:mymodule

Now you should be able access your module normally.

Everytime you change the code in the code in the module, you’ll need to compile them separately.

Perhaps I can make this smarter in the future.

i18n

Reference: “Play! i18n”:http://www.playframework.org/documentation/1.1.1/i18n

Everything said in the above documentation is supported in Japid.

There is one more API to retrieve an externalized messages, as illustrated in the following code snippet:

A Sample view:

login: &{‘login.name’} 
    or: ${i18n(“login.name”)}

customer name: &{‘cus.name’, “冉兵”} 
            or: ${i18n(“cus.name”, “Bing Ran”)}

The method i18n() basically calls the Messages.get(...).

Reverse URL Lookup

Play! uses the mapping rules in the conf/routes to map URLs to controller actions. This is very powerful. What is more powerful is to do the “reverse” mapping: to map a expression of a action invoke back to a valid URL.

For example: if the rule maps /myaction/{id} to more.MyController.action(id), the reverse lookup is to map the latter to the former. The core syntax is

    @{package.Controller.action(arg1, arg2...)}

for generating a relative URL from the host; and

    @@{package.Controller.action(arg1, arg2...)}

for generating an absolute URL including the host part.

The most common use case for the reverse lookup is to set the href attribute for the a tags and the action attribute for the form tags.

A sample view:

`String name = “bran”;
simple reverse lookup
simple reverse lookup with absolute url

    
    
    

simple reverse lookup

Note:

1. When there is no controller identifier in front of the action name, it’s assumed the controller is the current contoller that invoking this the template.
2. The reverse lookup takes place at rendering time, and it’s expensive.

There are a few methods available in you Java code, again imported from JapidPlayAdapter:

• String lookup(String action, Object... args): the action parameter is the controller plus action name, the args must be in the order of the parameters in the action.
• String lookupAbs(String action, Object... args): same as above except it returns the full URL including the host.
• String lookupStatic(String resource): look up the URL for the static resource, such as JavaScript, CSS, etc.
• String lookupStatic(String resource): same as above except it returns the full URL including the host.

Content Negotiation

Reference: “Content Negotiation in Play!”:http://www.playframework.org/documentation/1.1/routes#content-negotiation.

Japid tries to match the template to render to the Accept HTTP header of a user agent. This happens when we use renderJapid(), i.e., implicit template binding.

For the same controller action there can be multiple target templates to render depending on the client expections:

• if the client accept html, the target defaults to .html
• if the client accept xml, the target defaults to .xml
• if the client accept json, the target defaults to .json
• if the client accept JavaScript, the target defaults to .js
• if the client accept CSS, the target defaults to .css

Please note that the template translator maps the templates with an extension other than HTML to Java source file with the following naming pattern:

{action name}.{extension}  -> {action name}_{extension}.java 

The “Content-Type” header of the HTTP response is properly set in the above cases.

Japid allows you to set the Content-Type explicitly.

• Use a directive named `contentType

`// some examples
`contentType text/html; charset=utf-8
`contentType text/xml; charset=utf-8
`contentType application/json; charset=utf-8
`contentType application/x-javascript; charset=utf-8

To make it a lot simpler you can simply use a set of directive that does not require you to remember the exact correct format:

`txt
    `// for (“text/plain; charset=utf-8”),
`xml
    `// for (“text/xml; charset=utf-8”),
`json
    `// for (“application/json; charset=utf-8”),
`css
    `// for (“text/css; charset=utf-8”),
`js
    `// for (“application/x-javascript; charset=utf-8”),

BTW, you can directly manipulate the content type using the implicit object response:

`response.contentType = "text/xml; charset=utf-8"

Not recommended though.

Using Groovy and Japid in the Same Project

Japid is a module to bring another rendering engine for developing Play! applications. It does not replace the default Groovy-based template engine. It’s not one-or-the-other situation. In fact they can co-exist in the same project.

Controllers extending Controller will work as usual, meaning they search the app/views directory for the matching Goorvy-based templates, while those extending JapidController will use Japid, meaning use the app/japidview tree to store Japid templates.

The emailer is likewise. Both the Groovy-emailer and Japid emailer can exist in the same projects.

You can even render with Groovy in Japid controllers by simply calling render(...) methods instead of renderJapid(...)

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.
5. release a package that can be used in any Java projects.

Thanks for your interests in Japid!

Play! Default Syntax v.s. Japid

Functionally, Japid provides a few features that are missing from the standard Play! trmplates. For exmaples:

1. Invoking actions from the templates, with the `invoke/`a command, with advanced cache control. This is the Japid’s way of component-based page compositon.
2. Defining local methods in templates with the `def command, a light-weighted way of reusing rendering logic and presentation in the same template.
3. The import. Play! default must use the full qualified name to access static methods because you cannot do “import”. In Japid you can simply do “import static” to import all the great static methods you have designed and use them as if they’re part of your tempates.

Now let’s look at some of the Play! syntax and how similar things are done in Japid.

Japid has adopted most of the notations in the classic Play! templates.

• *{ }*: the server side comment block. Sometimes I use `// to make a one line comment.
• %{ }%: the code block. Most of the time I like the ` lead code line though.
• ${ }: the Java expression. Japid allows one to drop the curlies if won’t cause any confusion.
• &{ }: the message block.
• #{ }: the tag block. Note that named parameters are not supported. Many of the buidt-in tags has corresponding command form that use the back quote, such as extends, set, get, etc.

The following list starts with the tags available in standard Play! and gives the Japid counterpart. An explaination is given if a couterpart is missing.

• flash['user.name']:

• #{ifErrors}:

• #{else}:

• #{ifnot xxx}:

• #{errors}:

    `for Error e: errors()
       
$e

    `

• #{authenticityToken/}:

    

        $authenticityToken()
        <input .../>
    

• #{form ...}:

• #{field ...}:

• #{jsAction ...}:

        #{jsAction \@form(‘:name’, ‘:age’)}, 

        $jsAction(“form”, “:name”, “:age”)

If you’re so paranoid about your template performance, here are some of the tips to author Japid templates.

• All the general web site performance tips apply.
• Use cacheFor() annotation.
• All the field access in the model classes are transformed to invoke the FieldAccessor.invokeReadProperty() & FieldAccessor.invokeWriteProperty() and those two methods use reflection to finish the work. My advice is always create the getter and setter yourself if you’re performance conscious.
• The @{} reverse URL lookup is expensive. Use it cautiously.
• Invoking tags are more expensive than using local methods defined by def
• Use raw Java constructs, such as the if and for, particularly the the “open for” loop involves a lot of method dispatching.
• The format(Date...) in the JavaExtensions are not cheap if you care.

BTW, there is a special directive names `stopwatch that can be used to log the time it takes a template to render data.

`stopwatch on

A line like the following will be printed to the console:

[dummyTag] rendering time: 3

The unit of measurement is “ms”.

Migrating from Pre-controller Model to Post-Controller Model

The future direction of Japid is the Post-Controller Model where the view layer is less coupled with the rest of the application. The benefit is better performance and flexibility of manipulating the view layers such as the location of the template root, the internval to detect file system changes (or not at all) independent of Play’s mode (DEV or PROD). The API is provided by a method:

	/**
	 * The optional initialization step in using the JapidRender.
	 * 
	 * Users do not need to call this method to initialize this class. It takes
	 * “japidroot” as the default template root, which is relative to the application
	 * root. 
	 * 
	 * @param opMode
	 *            the operational mode of Japid. When set to OpMode.prod, it’s
	 *            assumed that all Java derivatives are already been generated
	 *            and used directly. When set to OpMode.dev, and using
	 *            none-static linking to using the renderer, file system changes
	 *            are detected for every rendering request given the refresh
	 *            interval is respected. New Java files are generated and
	 *            compiled and new classes are loaded to serve the request.
	 * @param templateRoot
	 *            the root directory to contain the “japidviews” directory tree. It must
	 *            be out of the “app” directory, or it will interfere with Play’s class
	 *            loading. 
	 * @param refreshInterval
	 *            the minimal time, in second, that must elapse before trying to
	 *            detect any changes in the file system.
	 */
JapidPlayRenderer.init(Mode opMode, String templateRoot, int refreshInterval)

Note:

1. Call this method in a bootstrap method.
2. Using the API is optional. If it’s not used, Japid runs in the same Mode as the current Play app. The default root to host japidviews is named “japidroot” relative to the app root. The default change detecting interval is two seconds.

Migrating from Pre-Controller mode to Post-controller mode is easy:

1. Move the entire japidview directory to the “japidroot” folder (or a folder configured with the above function).
2. Change all the controllers from extending from JapidController to JapicControler2.
3. Change all mailers to extending from JapidMailer2.
4. The _javatags folder in the japidviews folder is deprecated. Move all the static methods to utility classes in any of the app folder, such as the utils folder.

That’ll be it.

Note: JapidController and JapidController2 might co-exist in the same application. Some part of the app might be using the old Japid integration model while others suing the new “indi” model.

::eof