Scalate: the Scala Template Engine

James Strachan
@jstrachan
FuseSource

Your presenter: James Strachan

• James Strachan
  • twitter: @jstrachan
  • blog: http://macstrac.blogspot.com/
• Software Fellow at FuseSource
• long term Open Source contributor
  • created Apache Camel
  • created the Groovy programming language
  • co-founder of
    • Apache ActiveMQ, Camel, ServiceMix, Fabric, …
    • Scalate

Scalate Overview

• its a Scala based Template Engine
  • Scala T E => Scalate

Design Goals

• make an awesome template engine
  • framework & container agnostic
• support different template flavours under same API
  • there isn't really a one size fits all
• reuse the power & type safety of Scala
  • catch errors in templates at edit/build time
    • templates are for life, not just for Christmas!
  • IDE friendly for smart completion

Features

• Templates are compiled & cached as fast Scala objects
• Template objects are statically typed to catch typos
  • apart from Mustache
• Scalate is equivalent to the combination of JSP, JSTL, JSP EL & SiteMesh/Tiles
  • Scala replaces JSP EL and Scala functions replace JSP custom tags
  • Scalate template languages are richer, more powerful & usually more DRY than JSP + JSTL
  • Scalate has in built layout support replacing SiteMesh/Titles

How Scalate works

• TemplateEngine is used to load Templates
  • typically templates are converted into scala code and compiled to avoid runtime parsing
  • can customize various things…
    • caching & reloading
    • how URIs are resolved (classpath, file system etc)
    • internationalisation
• RenderContext is used to render a template
  • has a Map[String,Any] like set of attributes for passing/sharing state
  • loads of helper methods for use inside the template
    • localisation, including other templates, views, layouts etc
• template languages implemented using Scala parser generators

Scalate Template Languages

• SSP
• Scaml
• Jade
• Mustache
• Scuery

SSP

• SSP or Scala Server Pages
  • like a non-sucky JSP :)
• easiest template engine to start with if folks know
  • ASP, JSP, GSP, Erb, Velocity, FreeMarker style templates
• supports JSP / Erb style syntax
  • <% statements %>
  • <%= expression %>
  • ${expression}
• examples:
  • Dear ${people.map(_.name).mkString(", “)} how are you?

SSP also supports Velocity style tokens

#if (lineItems.find(_.price > 10).isDefined)
  <b>Welcome big spender!</b>
#end

SSP sample page

Sample page using SSP markup

<%
  val people = Map("James" -> "Mells", "Hiram" -> "Tampa")
%>

<h1>Table Example</h1>

<div class="main">
  <table>
    <tr>
      <th>Name</th>
      <th>Location</th>
    </tr>
    #for ((name, location) <- people)
    <tr>
      <td>${name}</td>
      <td>${location}</td>
    </tr>
    #end
  </table> 
</div>

<div class="description">
  <p>
    This is lots and lots of text.
    <b>Scalate</b> really is rather awesome!
  </p>      
</div>

Scaml

• Scaml is a Scala port of HAML
• HAML started in the Rails world and became a very popular alternative to Erb templates
• whitespace sensitive (which is handy for markup, avoids badly nested markup)
• syntax
  • %foo to indicate <foo>…</foo>
  • - for statements
  • = expressions

Scaml sample page

Sample page using Scaml markup

- val people = Map("James" -> "Mells", "Hiram" -> "Tampa")

%h1 Table Example

.main
  %table
    %tr
      %th Name
      %th Location
    - for ((name, location) <- people) 
      %tr
        %td = name
        %td = location

.description      
  %p
    This is lots and lots of text.
    <b>Scalate</b> really is rather awesome!

Jade

• Jade came from JavaScript / Rails as a simpler more DRY version of HAML / Scaml
  • avoid the % to indicate element name
    • folks tend to use lots of elements; few are multi-line text content
  • use | to indicate text content inside an element when multiple lines required
  • Implemented as just a slightly different surface parser on Scaml
• Jade + markdown are the hotness!

Jade sample page

Sample page using Jade markup

- val people = Map("James" -> "Mells", "Hiram" -> "Tampa")

h1 Table Example

.main
  table
    tr
      th Name
      th Location
    - for ((name, location) <- people) 
      tr
        td= name
        td= location
      
.description      
  :markdown
    This is lots and lots of text.
    **Scalate** really is rather awesome!

Mustache

• no logic in the scripts
• can be used from JavaScript on the client side or Scala / Scalate on the server side
• uses {{foo}} mustaches for values
• use {{#foo}} and {{/foo}} for blocks/loops/conditionals
• good if you want your designer to own the templates
  • though dynamically typed

Mustache sample page

Sample page using Mustache markup

<table>
  <tr>
    <th>Name</th>
    <th>Location</th>
  </tr>
  {{#people}}
  <tr>
    <td>{{name}}</td>
    <td>{{location}}</td>
  </tr>
  {{/people}}
</table> 

<p>
  This is lots and lots of text.
  <b>Scalate</b> really is rather awesome!
</p>      

Scuery

• more of a HTML/XHTML transformation engine really
• uses CSS3 parser & transformation engine
• templates are regular HTML pages (possibly with mock data) owned by your designer
• use the transform API (jQuery-ish) to transform the HTML to inject/replace with dynamic data

Scuery sample HTML page

Sample page using plain HTML markup

<ul class="people">
  <li>
    <a href="#" class="person">A person</a>
  </li>
  <li>
    <a href="#" class="person">Another person</a>
  </li>
</ul>

Scuery sample Scala transform

Sample HTML page transform with Scuery

import org.fusesource.scalate.scuery._

case class Person(name: String, location: String)


object MyTransform extends Transformer {
  val people = List(Person("James", "Beckington"), Person("Hiram", "Tampa"))
  
  $(".people").contents {
    node =>
      people.flatMap {
        p =>
          transform(node.$("li:first-child")) {
            $ =>
              $("a.person").contents = p.name
              $("a.person").attribute("href").value = "http://acme.com/bookstore/" + p.name
          }
      }
  }
}

Tips on picking a template language

• If you want your designers to own your templates
  • consider mustache or scuery
• if you want developers to hack your templates
  • want to generate HTML/XML really DRY?
    • use jade
  • otherwise SSP

Scalate Layouts

• TemplateEngine.layoutStrategy defines the strategy
• default implementation uses the “layout” attribute to define the template used for laying out any template
• to change the layout you want to use…
  • - attributes("layout”) = “/my/layouts/foo.jade”
• to disable layouts
  • - attributes("layout”) = “"

Using Scalate

• can use TemplateEngine directly if doing code generation
• or if using servlets:

<filter>
  <filter-name>TemplateEngineFilter</filter-name>
  <filter-class>org.fusesource.scalate.servlet.TemplateEngineFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>TemplateEngineFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Framework support

• bowler
• jersey
• lift
• playframework
• scalatra
• servlets
• sbt / lifty
• spring mvc
• unfiltered

mod your Template Engine!

package scalate 

import org.fusesource.scalate.TemplateEngine
import java.io.File

class Boot(engine: TemplateEngine) {

  def run: Unit = {
    // lets change the workingDirectory
    engine.workingDirectory = new File("myScalateWorkDir")
  }
}
        

Precompile your templates

<build>
  <plugins>
    <plugin>
      <groupId>org.fusesource.scalate</groupId>
      <artifactId>maven-scalate-plugin</artifactId>
      <version>1.5.0</version>
      <executions>
        <execution>
          <goals>
            <goal>precompile</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
        

Getting Started

• install Scalate
  • http://scalate.github.io/scalate/download.html
  • add SCALATE_HOME/bin to your PATH

Create a sample project

scalate create jersey mygroup myartifact
cd myartifact
mvn jetty:run

To try out the Scalate shell

scalate
help

Static site generation

• maven plugin to generate a complete static website for your project using Scalate
• deploy it to some web server using maven's wagon transports
  • scp / webdav etc
• allows real time updates of templates & layouts while editing docs
• your own personal offline wiki using git for source control & versioning
  • use a text editor to edit, erm, text files! :)

Create a website project

scalate create sitegen mygroup mysite
cd mysite
mvn jetty:run

• now open http://localhost:8080/scalate
• click on the top right scalate icon for the Scalate Console

Presentation generation

• this presentation is created by Scalate :)
• deployed online static HTML
• implemented in a single jade + markdown template
• uses HTML Slidy for JavaScript + CSS

To try it out locally from a scalate checkout

cd samples/scalate-presentation
mvn jetty:run

• now open http://localhost:8080/scalate

Demo time!

• Demo templates & web app here:
• https://github.com/scalate/scalate/tree/master/samples/scalate-example

Any Questions?

• http://scalate.github.io/scalate/
• twitter: @jstrachan
• http://fusesource.com