Play Tmpltr

I love the Play Framework. And I also love how beatuiful its views can be with plain old HTML and some Scala variables here and there. But no later than when it comes to build up some Bootstrap forms the drawbacks are inevitable. The views suddenly become a varied mixture of HTML and some way too inflexible field constructors—or they drown in repetetive boilerplate code that is required by Bootstrap. Play Tmpltr is an approach to create consistent and beautiful views within the Play Framework by moving the widget declarations back to plain Scala code.

Installation

When your Play Framework (Scala) application is up and running you need to add Play Tmpltr to your project dependencies. In order to do so you have to add my GitHub page as resolver.

resolvers += Resolver.url( "Play Tmpltr", url( "http://taig.github.io/Play-Tmpltr/release" ) )( Resolver.ivyStylePatterns )

Now sbt will automatically fetch the Play Tmpltr binaries for you if you add it to the project dependencies.

libraryDependencies += "com.taig" %% "play-tmpltr" % "1.0.0-BETA"

Integration

The dependencies are set up properly and you want to start building some beautiful views? Well, then it's time to deal with the imports now. Add com.taig.tmpltr.engine.html._ to the import directives in the head of your view and all the HTML tools will be ready to use. But without importing com.taig.tmpltr._ using them won't be fun, because all the implicit conversions are located there. So make sure to add both statements before you go on.

If your view now looks somehow like this, your basic configuration is ready.

@*************************
* Your view's signature. *
*************************@
@( args: Any* )

@***********************
* Play Tmpltr imports. *
***********************@
@import com.taig.tmpltr._
@import com.taig.tmpltr.engine.html._

@p{ Your @cite{ HTML5 } goes here. }

Alternatively you can add frequently used imports to your Build.scala file. That's a useful thing if you have multiple views that rely on Play Tmpltr. Open your project/Build.scala file and add the import directives to your project settings. Play will then take care of importing these files into your views. Less pain for you.

val main = play.Project( "project-name", "1.0" ).settings(
    templatesImport ++= Seq(
        "com.taig.tmpltr._",
        "com.taig.tmpltr.engine.html._"
    )
)

Play Tmpltr's most important features with useful examples are listed below. If you are missing something take a look into the source code of this documentation page. It's actually a Play application built with Play Tmpltr. Alternatively you might want to browse the ScalaDoc to get an overview of the available features. Also this module is far from being feature complete. So if you find yourself adding some utilities for your project make sure to send me a pull request!

HTML

Tags

When you've imported all com.taig.tmpltr.engine.html._ utilities right into your namespace as adviced above you will have easy access to all HTML features. In fact all you need is Play's magic @ character followed by the name of the HTML tag.

@div {
    @h1{ No big surprises here. }
    @p{ If you know the common @em{ HTML } tags this will be easy for you. }
}

<div>
    <h1>No big surprises here.</h1>
    <p>If you know the common <em>HTML</em> tags this will be easy for you.</p>
</div>

Tag Arguments

Most of the tags are capable to receive plenty of input parameters. In the examples above we only passed one argument to the tags: the actual HTML content. This, of course, is possible with all tags that may have a body by the HTML5 specification. So Play Tmpltr won't allow you to pass a body to a <meta /> tag for instance.

If some tags aren't working the way you expected them to or you find yourself hacking around the module chances are you missed a constructor that already covers your use-case. So, when in doubt better have a look into the ScalaDoc first. Let me show you the <input /> tag to give you a better understanding of what I'm talking about.

@input( type: Option[type], name: Option[String], value: Option[String], placeholder: Option[String], attributes: (String, String)* )
@input( type: Option[type], name: Option[String], value: Option[String], attributes: (String, String)* )
@input( type: Option[type], name: Option[String], attributes: (String, String)* )

As you can see there are parameter fields that allow you to quickly pass commom attribute values to the input tag. You may also ignore the Option types if you have com.taig.tmpltr._ imported. Just pass over the type in the brackets.

@input( input.`type`.text, "username", "taig", "Enter username ..."  )

<input type="submit" name="username" value="taig" placeholder="Enter username ..." />

But wait! There is more …

@input.text( "username", "taig", "Enter username ..."  )

Attributes

You sure have noticed the attributes: (String, String)* parameter in the above examples. It comes in pretty handy if Play Tmpltr's constructors aren't able to fullfill your needs. Just add some tuples to get your tag's attributes right.

@canvas( "id" -> "whiteboard", "class" -> "grey large" ) {
    @p{ No canvas, no fun. }
}

<canvas id="whiteboard" class="grey large">
    <p>No canvas, no fun.</p>
</canvas>

Boilerplate

We're done. You now know how to use Play Tmpltr to build your views. Just let me give you the @boilerplate tag to take along your way down the page.

@boilerplate {
    @meta.charset( "utf-8" )
    …
} {
    @h1{ Hello there! }
    …
}

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        …
    </head>
    <body>
        <h1>Hello there!</h1>
        …
    </body>
</html>

The MIT License (MIT)

Copyright (c) 2014 Nikas Klein <my.taig@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.