h1. Scalate support

"Scalate":http://scalate.fusesource.org/ is a template engine written in scala. It supports three dialects: ssp (jsp for scala), scaml (haml for scala) and mustache. Play provides integration for both via a special Controller class. 

h3. Getting started

first you need to grab the release from the modules repository:

bc. play install scalate-0.7.2


h3. Starting a New Project

then if you start a new project all you need to do is:

bc. play new myapp --with scala,scalate

(if you have any other version installed from scala or scalate than 0.3, then you will need to explicitly reference both ie. --with scalate-0.7.2,scala-0.7.2)

p(note). the scalate module is depending on the scala module, so both modules need to be installed and activated 

h3. Existing Projects

or if you want to configure an existing scala project, you will need to edit your conf/application.conf:

bc. module.scalate=${play.path}/modules/scalate-0.3

then set scalate's dialect in the same file:

bc. scalate=ssp

or 

bc. scalate=scaml

or 

bc. scalate=mustache

then you will also need to increase the heap size:

bc. jvm.memory=-Xmx256M

afterwards create a default layout file: 

bc. touch <yourapp>/app/views/default.<ssp or scaml> 

copy files related to 500 errors: 

bc. cp <scalate-module>/resources/500.scaml  <yourapp>/app/views/errors
cp <scalate-module>/resources/500.css <yourapp>/public/stylesheets

and finally you will need to change your controllers to inherit from play.mvc.ScalateController

h3. Example

bc. object Application extends ScalateController  {
    def index(name: String = "Guest user") = render(name)  //populating context parameters via renderArgs("name",name) is also working
}


the corresponding template (ie view/Application/index.ssp) could look something like this:

bc. <%@ var name: String %>
Hello ${name}

if the method above is invoked, play will render app/views/Application/index.ssp with the following context variables already populated:
* name
* request
* flash
* session
* parameters

and the following packages will be imported by default:
* models._
* controllers._
* play.utils._

p(note). This means that you will need to have at least one class in each of these packages, otherwise templates can not be compiled


h3. Intelligent error reporting

Compilation and syntax related issues are reported in the browser the usual way:

!images/scalate-error!


h3. Precompile templates

bc. play precompile

the command above will pregenerate all templates into the tmp folder

p(note). It's worth noting that by default the precompiler is scanning only the first 20 lines of each template for variable declaration (ie <%@ var %> )

h3. Difference between production and dev mode

in dev mode, play will alow instant template reloading, that is, if you make a change to a template and refresh the page, the change will apear. In production, however, template reloading is disabled for performance reasons.

h3. Layout

scalate now supports "layouts, partials":http://scalate.fusesource.org/documentation/user-guide.html#layouts as well. Play stores default layouts in app/views/default.ssp (or app/views/default.scaml). 

h3. Reverse URL

bc. <%= url("Application.index") %>

this will give back the index page 

bc. <%= url("Application.something", Map("id"->5)) %>

this will resolve method "Application#something" with argument "id" 

bc. <%= absoluteurl("Application.index") %>

this will resolve the full url

bc. <%= staticurl("/public/images/favicon.png") %>

this will resolve the full url for the favicon asset.

h3. demo

a sample application is bundled with the module and you can find it under samples-and-tests/simpleapp.
