Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork116
Twirl is Play's default template engine
License
playframework/twirl
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Twirl is thePlaytemplate engine.
Twirl is automatically available in Play projects and can also be usedstand-alone without any dependency on Play.
See the Playdocumentation for the template engine for more informationabout the template syntax.
Twirl can also be used outside of Play. An sbt plugin is provided for easyintegration with Scala or Java projects.
sbt-twirl requires sbt 1.3.0 or higher.
To add the sbt plugin to your project add the sbt plugin dependency inproject/plugins.sbt:
// twirl 2.0 and newer:addSbtPlugin("org.playframework.twirl"%"sbt-twirl"%"LATEST_VERSION")// twirl 1.6:addSbtPlugin("com.typesafe.play"%"sbt-twirl"%"1.6.1")// twirl 1.5.1 and before:addSbtPlugin("com.typesafe.sbt"%"sbt-twirl"%"1.5.1")
Replacing theLATEST_VERSION with the latest version published, which should be
someProject.enablePlugins(SbtTwirl)If you only have a single project and are using abuild.sbt file, create aroot project and enable the twirl plugin like this:
lazyvalroot= (project in file(".")).enablePlugins(SbtTwirl)
Twirl template files are expected to be placed undersrc/main/twirl orsrc/test/twirl, similar toscala orjava sources. The source locations fortemplate files can be configured.
Template files must be named{name}.scala.{ext} whereext can behtml,js,xml, ortxt.
The Twirl template compiler is automatically added as a source generator forboth themain/compile andtest configurations. When you runcompile orTest/compile the Twirl compiler will generate Scala source files from thetemplates and then these Scala sources will be compiled along with the rest ofyour project.
To add additional imports for the Scala code in template files, use thetemplateImports key. For example:
TwirlKeys.templateImports+="org.example._"
To configure the source directories where template files will be found, use thecompileTemplates / sourceDirectories key. For example, to have templatesources alongside Scala or Java source files:
Compile/TwirlKeys.compileTemplates/ sourceDirectories:= (Compile/ unmanagedSourceDirectories).value
To use the Twirl plugin in your project add the Maven plugin andTwirl API as a dependency intopom.xml:
<dependencies> <dependency> <groupId>org.playframework.twirl</groupId> <artifactId>twirl-api_${SCALA_VERSION}</artifactId> <version>${TWIRL_VERSION}</version> </dependency></dependencies><build> <plugins> <plugin> <groupId>org.playframework.twirl</groupId> <artifactId>twirl-maven-plugin_${SCALA_VERSION}</artifactId> <version>${TWIRL_VERSION}</version> <executions> <execution> <goals> <goal>compile</goal> </goals> </execution> </executions> </plugin> </plugins></build>Replacing theTWIRL_VERSION with the latest version published, which should be
Twirl template files are expected to be placed undersrc/main/twirl orsrc/test/twirl, similar toscala orjava sources. The additional sourcelocations for template files can be configured.
Template files must be named{name}.scala.{ext} whereext can behtml,js,xml, ortxt.
To add additional imports for the Scala code in template files, use thetemplateImports parameter. For example:
<plugin> <groupId>org.playframework.twirl</groupId> <artifactId>twirl-maven-plugin_${SCALA_VERSION}</artifactId> <version>${TWIRL_VERSION}</version> <configuration> <templateImports> <import>org.example._</import> </templateImports> </configuration></plugin>To configure the source directories where template files will be found, use thesourceDir parameter. For example:
<plugin> <groupId>org.playframework.twirl</groupId> <artifactId>twirl-maven-plugin_${SCALA_VERSION}</artifactId> <version>${TWIRL_VERSION}</version> <configuration> <sourceDir>${project.basedir}/src/main/templates</sourceDir> </configuration> <executions> <execution> <id>additional-source-directory</id> <goals> <goal>compile</goal> </goals> <configuration> <sourceDir>${project.basedir}/src/main/other-templates</sourceDir> </configuration> </execution> </executions></plugin>To configure the Scala version just use the suffix inartifactId.
Also, you can use the next parameters:
<plugin> <groupId>org.playframework.twirl</groupId> <artifactId>twirl-maven-plugin_${SCALA_VERSION}</artifactId> <version>${TWIRL_VERSION}</version> <configuration> <constructorAnnotations> <annotation>@org.example.MyAnnotation()</annotation> </constructorAnnotations> <templateFormats> <csv>play.twirl.api.TxtFormat</csv> </templateFormats> <sourceEncoding>UTF-8</sourceEncoding> </configuration></plugin>To use a snapshot version add theMaven Central Snapshot repository intopom.xml:
<pluginRepositories> <pluginRepository> <id>maven-central-snapshots</id> <url>https://central.sonatype.com/repository/maven-snapshots/</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </pluginRepository></pluginRepositories>org.playframework.twirl plugin requires Gradle 7.1 or higher.
To use the Twirl plugin in your project add the gradle plugin andTwirl API as a dependency intobuild.gradle.kts:
plugins {... id("org.playframework.twirl") version"LATEST_VERSION"}dependencies { implementation("org.playframework.twirl","twirl-api_${scalaVersion}","LATEST_VERSION")}Replacing theLATEST_VERSION with the latest version published, which should be
Twirl template files are expected to be placed undersrc/main/twirl orsrc/test/twirl, similar toscala orjava sources. The additional sourcelocations for template files can be configured.
src/main/scala, but itcan be customized.
Template files must be named{name}.scala.{ext} whereext can behtml,js,xml, ortxt.
To add additional imports for the Scala code in template files, use thetemplateImports key. For example:
sourceSets { main { twirl { templateImports.add("org.example._") } }}To configure the source directories where template files will be found, use thesrcDir method forSourceDirectorySet. For example:
sourceSets { main { twirl { srcDir("app") } }}To configure the Scala version use thescalaVersion property ofTwirlExtension (2.13 by default). For example:
twirl { scalaVersion.set("3")}Also, you can use the next properties:
sourceSets { main { twirl {// Annotations added to constructors in injectable templates constructorAnnotations.add("@org.example.MyAnnotation()")// Defined custom twirl template formats templateFormats.put("csv","play.twirl.api.TxtFormat")// Source encoding for template files and generated scala files sourceEncoding.set("<enc>") } }}To use a snapshot version add theMaven Central Snapshot repository intosettings.gradle.kts:
pluginManagement { repositories { maven { url= uri("https://central.sonatype.com/repository/maven-snapshots") } }}Seehttps://github.com/playframework/.github/blob/main/RELEASING.md
The nametwirl was thought up by theSpray team and refers to themagic@ character in the template language, which is sometimes called "twirl".
The first stand-alone version of Twirl was created by theSpray team.
An optimized version of the Twirl parser was contributed by theScala IDE team.
About
Twirl is Play's default template engine
Topics
Resources
License
Code of conduct
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.