Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/playframework/twirl
Twirl is Play's default template engine
https://github.com/playframework/twirl
playframework sbt-plugin scala template-engine template-language template-library twirl
Last synced: 7 days ago
JSON representation
Twirl is Play's default template engine
- Host: GitHub
- URL: https://github.com/playframework/twirl
- Owner: playframework
- License: apache-2.0
- Created: 2013-09-22T22:48:40.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2024-10-07T21:21:34.000Z (3 months ago)
- Last Synced: 2024-10-29T10:25:44.136Z (about 2 months ago)
- Topics: playframework, sbt-plugin, scala, template-engine, template-language, template-library, twirl
- Language: Scala
- Homepage:
- Size: 1.92 MB
- Stars: 549
- Watchers: 38
- Forks: 108
- Open Issues: 45
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Twirl
[](https://twitter.com/playframework)
[](https://discord.gg/g5s2vtZ4Fa)
[](https://github.com/playframework/playframework/discussions)
[](https://stackoverflow.com/tags/playframework)
[](https://www.youtube.com/channel/UCRp6QDm5SDjbIuisUpxV9cg)
[](https://www.twitch.tv/playframework)
[](https://opencollective.com/playframework)
[](https://github.com/playframework/twirl/actions/workflows/build-test.yml)
[](https://mvnrepository.com/artifact/org.playframework.twirl/twirl-api_2.13)
[](https://github.com/playframework/twirl)
[](https://scala-steward.org)
[](https://mergify.com)
Twirl is the [Play][play-site] [template engine][docs].
Twirl is automatically available in Play projects and can also be used
stand-alone without any dependency on Play.
See the Play [documentation for the template engine][docs] for more information
about the template syntax.
## sbt-twirl
Twirl can also be used outside of Play. An sbt plugin is provided for easy
integration 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 in
`project/plugins.sbt`:
```scala
// 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 the `LATEST_VERSION` with the latest version published, which should be [](https://index.scala-lang.org/playframework/twirl/twirl-api). And enable the plugin on projects using:
```scala
someProject.enablePlugins(SbtTwirl)
```
If you only have a single project and are using a `build.sbt` file, create a
root project and enable the twirl plugin like this:
```scala
lazy val root = (project in file(".")).enablePlugins(SbtTwirl)
```
### Template files
Twirl template files are expected to be placed under `src/main/twirl` or
`src/test/twirl`, similar to `scala` or `java` sources. The source locations for
template files can be configured.
Template files must be named `{name}.scala.{ext}` where `ext` can be `html`,
`js`, `xml`, or `txt`.
The Twirl template compiler is automatically added as a source generator for
both the `main`/`compile` and `test` configurations. When you run `compile` or
`Test/compile` the Twirl compiler will generate Scala source files from the
templates and then these Scala sources will be compiled along with the rest of
your project.
### Additional imports
To add additional imports for the Scala code in template files, use the
`templateImports` key. For example:
```scala
TwirlKeys.templateImports += "org.example._"
```
### Source directories
To configure the source directories where template files will be found, use the
`compileTemplates / sourceDirectories` key. For example, to have template
sources alongside Scala or Java source files:
```scala
Compile / TwirlKeys.compileTemplates / sourceDirectories := (Compile / unmanagedSourceDirectories).value
```
## maven-twirl
To use the Twirl plugin in your project add the Maven plugin and
Twirl API as a dependency into `pom.xml`:
```pom
org.playframework.twirl
twirl-api_${SCALA_VERSION}
${TWIRL_VERSION}
org.playframework.twirl
twirl-maven-plugin_${SCALA_VERSION}
${TWIRL_VERSION}
compile
```
Replacing the `TWIRL_VERSION` with the latest version published, which should be [](https://index.scala-lang.org/playframework/twirl/twirl-api).
### Template files
Twirl template files are expected to be placed under `src/main/twirl` or
`src/test/twirl`, similar to `scala` or `java` sources. The additional source
locations for template files can be configured.
Template files must be named `{name}.scala.{ext}` where `ext` can be `html`,
`js`, `xml`, or `txt`.
### Additional imports
To add additional imports for the Scala code in template files, use the
`templateImports` parameter. For example:
```pom
org.playframework.twirl
twirl-maven-plugin_${SCALA_VERSION}
${TWIRL_VERSION}
org.example._
```
### Source directories
To configure the source directories where template files will be found, use the
`sourceDir` parameter. For example:
```pom
org.playframework.twirl
twirl-maven-plugin_${SCALA_VERSION}
${TWIRL_VERSION}
${project.basedir}/src/main/templates
additional-source-directory
compile
${project.basedir}/src/main/other-templates
```
### Scala version
To configure the Scala version just use the suffix in `artifactId`.
### Other properties
Also, you can use the next parameters:
```pom
org.playframework.twirl
twirl-maven-plugin_${SCALA_VERSION}
${TWIRL_VERSION}
@org.example.MyAnnotation()
play.twirl.api.TxtFormat
UTF-8
```
### Snapshots
To use a snapshot version add the [Sonatype Snapshot repository](https://oss.sonatype.org/content/repositories/snapshots/org/playframework/twirl/) into `pom.xml`:
```pom
sonatype-snapshots
https://oss.sonatype.org/content/repositories/snapshots/
false
true
```
## gradle-twirl
⚠️ `org.playframework.twirl` plugin requires Gradle 7.1 or higher.
To use the Twirl plugin in your project add the gradle plugin and
Twirl API as a dependency into `build.gradle.kts`:
```kotlin
plugins {
...
id("org.playframework.twirl") version "LATEST_VERSION"
}
dependencies {
implementation("org.playframework.twirl", "twirl-api_${scalaVersion}", "LATEST_VERSION")
}
```
Replacing the `LATEST_VERSION` with the latest version published, which should be [](https://index.scala-lang.org/playframework/twirl/twirl-api).
### Template files
Twirl template files are expected to be placed under `src/main/twirl` or
`src/test/twirl`, similar to `scala` or `java` sources. The additional source
locations for template files can be configured.
⚠️Please note that the output of the template compilation is Scala source code.
If you use these templates in your Java source files, you must place them in a _joint compilation_ folder (see the [Gradle Scala Plugin](https://docs.gradle.org/current/userguide/scala_plugin.html#sec:scala_project_layout) documentation for details).
The default location for this folder is `src/main/scala`, but it [can be customized](https://stackoverflow.com/questions/23261075/compiling-scala-before-alongside-java-with-gradle).
Template files must be named `{name}.scala.{ext}` where `ext` can be `html`,
`js`, `xml`, or `txt`.
### Additional imports
To add additional imports for the Scala code in template files, use the
`templateImports` key. For example:
```kotlin
sourceSets {
main {
twirl {
templateImports.add("org.example._")
}
}
}
```
### Source directories
To configure the source directories where template files will be found, use the
`srcDir` method for [SourceDirectorySet](https://docs.gradle.org/current/javadoc/org/gradle/api/file/SourceDirectorySet.html). For example:
```kotlin
sourceSets {
main {
twirl {
srcDir("app")
}
}
}
```
### Scala version
To configure the Scala version use the `scalaVersion` property of [TwirlExtension](gradle-twirl/src/main/java/play/twirl/gradle/TwirlExtension.java) (`2.13` by default). For example:
```kotlin
twirl {
scalaVersion.set("3")
}
```
### Other properties
Also, you can use the next properties:
```kotlin
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("")
}
}
}
```
### Snapshots
To use a snapshot version add the [Sonatype Snapshot repository](https://oss.sonatype.org/content/repositories/snapshots/org/playframework/twirl/org.playframework.twirl.gradle.plugin/) into `settings.gradle.kts`:
```kotlin
pluginManagement {
repositories {
maven {
url = uri("https://oss.sonatype.org/content/repositories/snapshots")
}
}
}
```
## Releasing a new version
See https://github.com/playframework/.github/blob/main/RELEASING.md
## Credits
The name *twirl* was thought up by the [Spray team][spray] and refers to the
magic `@` character in the template language, which is sometimes called "twirl".
The first stand-alone version of Twirl was created by the [Spray team][spray].
An optimized version of the Twirl parser was contributed by the
[Scala IDE team][scala-ide].
[play-site]: https://www.playframework.com
[docs]: https://www.playframework.com/documentation/latest/ScalaTemplates
[spray]: https://github.com/spray
[scala-ide]: https://github.com/scala-ide