Quick start with Japid module for Play
Japid works with both recent 1.1 nightly build and 1.0 nightly build.
The following quick steps have been tested with the March 4th’s version of Japid module and Play’ 1.1 nightly built r812 and Play! 1.0-r918
First of all, to get the latest japid module, issue the following command from the commandline.
# play install japid
This download a zip file and extract the content to modules directory in your Play! installation,
such as:
${play.path}/modules/japid-head
Go to there and find the source and a sample project named JapidSample in the directory.
Go to the ${play.path}/modules/japid-head/JapidSample, and
play run
You should now be able to browse to http://localhost:9000/ and play with the sample app the shows some of the features of the Japid template engine.
There are two ways to include the modele in your application:
- For an existing application:
add an entry in the application.conf:
module.japid=${play.path}/modules/japid-head
- To create a new application with Japid support:
# play new junkie --with japid
Verify the existence of the above japid reference in the application.conf file.
Now create the required package structure for the japid views:
# cd junkie # play japid:mkdir
This command creates
- app/japidviews/javatags, for placing your java based tag definitions
- app/japidviews/_layouts, for placing layout templates
- app/japidviews/tags, for placing tag templates.
It also creates a package for each controllers in the app/controllers/ directory/subdirectory,
such as:
And you usually create a template named after the controller’s action name with “.html” extension. This is optional however, since controller actions can explicitly call the renders directly using Java invocation syntax, the templates can be put anywhere under japidviews root package. But it’s mandetory if you use implicit template invocation, as explained later, in your controller.
Create the first template
# cd app/japidviews/Application # vi hello.html
Here is the content of hello.html:
%{
args String who
}%
<html>
Hello ${who}!
</html>
Or you can use the line oriented script prefix: the singel back-quote, which is the “tilde” key on a PC keyboard:
`args String who
<html>
Hello ${who}!
</html>
The “args” directive tells what arguments/objects the template actually renders. a Java String called “who” in this case.
Now transform/pre-compile the template to Java source:
If you develop in “cold” mode – not running your app in DEV mode while you develop:
# cd {back to your application root}
# play japid:gen
This command tranforms the template to a Java file called hello.java in the same package.
NOTE:
- This step is not required if you use the implicit template binding.
- If you do your developing live with you application running in DEV mode, you don’t need to run japid:gen command to synchronize the Java artifacts for the templates. It’ll be handled automatically for you. japid:gen is for you to develop you app “off-line”, or “cold”, using the explicit template binding.
# cd app/controllers
and modify your Application.java to something like this:
package controllers;
import play.mvc.*;
import japidviews.Application.hello;
import cn.bran.japid.template.RenderResult;
import cn.bran.play.JapidResult;
import cn.bran.play.JapidController;
public class Application extends JapidController {
public static void hello() {
String obj = "me";
throw new JapidResult(new hello().render(obj));
// or alternatively with implicit template binding:
// renderJapid(obj);
}
public static void index() {
render();
}
}
The interesting line is:
throw new JapidResult(new hello().render("me"));
where we invoke the renderer hello class directly and throw a JapidResult for the Play! framework to do its work.
You can also invoke the renderer implicitly from the controller using a method from the JapidController super class:
instead of the above line, we can also do:
renderJapid(param1, param2, etc);
For this to work we must make sure the hello.html is exactly in the app/japidviews/Application/ directory. This method
is slightly slower than direct invocation since it uses reflection to find the renderer, and we lose strong parameter
type checking until runtime. But it does come more convenient at times.
Now start your application by using the following command the app’s root directory
# play run
Now point your brower to http://127.0.0.1:9000/Application/hello and you’ll see:
----------------- Hello me! -----------------
In this sample action the dynamic content is actually a static “me” object, but you basically assemble your objects of any level
of complexity in the controller and pass them to the renderer in a similar way. Of course you will need to decalre those parameters
explicitly in your templates by way of using the args directive.
While you’re running the app in DEV mode, modify the hello.html and add one more ! to the end of ${who}.Reloading your browser
you’ll see the change.
----------------- Hello me!!! -----------------
The Japid engine detects the changes in the html and updates the hello.java which will be rolled in the whole Play change detection flow in DEV mode.
To issue
play install japid
to upgrade to the latest version of Japid.
Once it’s installed, you’ll need to go to the root of your project and issue
play japid:regen
to regenerate all the Java artifacts from the template files.
Now you’re in business!
I’m using Play! 1.0-r918 to write this quick start
- install the Play! 1.0-r918 from http://download.playframework.org/1.0-nightly/
- download the Japid module from http://www.playframework.org/modules/japid-head.zip
- create a directory named japid-head in ${play.path}/modules
- unzip the module in the japid-head directory
- now create you application as you would usually do, but don’t try —with japid. It’s not working yet. You’ll need manually add a reference to the japid module by modifying the application.conf:
add an entry in the application.conf:
module.japid=${play.path}/modules/japid-head
Then
# play japid:mkdir
and follow the rest steps as outlined in the 1.1 quick steps above.