OSCHINA-MIRROR/mirrors-twirl

Twirl

Twirl — это [шаблонизатор Play][play-site].

Шаблонизатор Twirl автоматически доступен в проектах Play и также может быть использован автономно без какой-либо зависимости от Play.

Дополнительную информацию о синтаксисе шаблонизатора можно найти в [документации Play][docs].

sbt-twirl

Twirl также можно использовать вне Play. Для простой интеграции с проектами Scala или Java предоставляется плагин sbt.

Для sbt-twirl требуется sbt 1.3.0 или выше.

Чтобы добавить плагин sbt в свой проект, добавьте зависимость плагина в project/plugins.sbt:

// twirl 2.0 и новее:
addSbtPlugin("org.playframework.twirl" % "sbt-twirl" % "LATEST_VERSION")
// twirl 1.6:
addSbtPlugin("com.typesafe.play" % "sbt-twirl" % "1.6.1")
// twirl 1.5.1 и раньше:
addSbtPlugin("com.typesafe.sbt" % "sbt-twirl" % "1.5.1")

Замените LATEST_VERSION на последнюю опубликованную версию, которая должна быть . И включите плагин в проектах, используя:

someProject.enablePlugins(SbtTwirl)

Если у вас есть только один проект и вы используете файл build.sbt, создайте корневой проект и включите плагин Twirl следующим образом:

lazy val root = (project in file(".")).enablePlugins(SbtTwirl)

Файлы шаблонов

Файлы шаблонов Twirl должны располагаться в папках src/main/twirl или src/test/twirl, аналогично источникам scala или java. Исходный код... Расположение файлов шаблонов можно настроить.

Файлы шаблонов должны называться {name}.scala.{ext}, где ext может быть html, js, xml или txt.

Компилятор шаблонов Twirl автоматически добавляется в качестве генератора исходного кода для конфигураций main/compile и test. При запуске compile или Test/compile компилятор Twirl будет генерировать исходные файлы Scala из шаблонов, а затем эти исходные файлы Scala будут скомпилированы вместе с остальной частью вашего проекта.

Дополнительные импорты

Чтобы добавить дополнительные импорты для кода Scala в файлах шаблонов, используйте ключ templateImports. Например:

TwirlKeys.templateImports += "org.example._"

Каталоги исходных файлов

Чтобы настроить каталоги исходных файлов, в которых будут найдены файлы шаблонов, используйте параметр sourceDirectories ключа compileTemplates. Например, чтобы иметь источники шаблонов рядом с исходными файлами Scala или Java:

Compile / TwirlKeys.compileTemplates / sourceDirectories := (Compile / unmanagedSourceDirectories).value

maven-twirl

Чтобы использовать плагин Twirl в своём проекте, добавьте плагин Maven и API Twirl как зависимость в pom.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>

Заменив TWIRL_VERSION на последнюю опубликованную версию, которая должна быть .

Файлы шаблонов

Ожидается, что файлы шаблонов Twirl будут помещены в src/main/twirl или src/test/twirl, аналогично источникам scala или java. Дополнительные расположения исходных файлов для файлов шаблонов могут быть настроены.

Файлы шаблонов должны называться {name}.scala.{ext}, где ext может быть html, js, xml или txt.

Дополнительные импорты

Для добавления дополнительных импортов для кода Scala в файлы шаблонов используйте параметр templateImports. Например:

<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>

Каталоги источников

Чтобы настроить каталоги источников, где будут найдены файлы шаблонов, используйте параметр sourceDir. Например:

<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>

Версия Scala

Чтобы настроить версию Scala, просто используйте суффикс в artifactId.

Другие свойства

Также вы можете использовать следующие параметры: Конфигурация плагина

<configuration>
    <constructorAnnotations></constructorAnnotations>
    <templateFormats>
        <csv>play.twirl.api.TxtFormat</csv>
    </templateFormats>
    <sourceEncoding>UTF-8</sourceEncoding>
</configuration>

Репозитории моментальных снимков

Чтобы использовать версию моментального снимка, добавьте репозиторий моментальных снимков Sonatype в pom.xml:

<pluginRepositories>
    <pluginRepository>
        <id>sonatype-snapshots</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Gradle-Twirl

⚠️ Плагин org.playframework.twirl требует Gradle 7.1 или выше.

Чтобы использовать плагин Twirl в своём проекте, добавьте плагин Gradle и API Twirl как зависимость в build.gradle.kts:

plugins {
  ...
  id("org.playframework.twirl") version "LATEST_VERSION"
}

dependencies {
  implementation("org.playframework.twirl", "twirl-api_${scalaVersion}", "LATEST_VERSION")
}

Заменив LATEST_VERSION на последнюю опубликованную версию, которая должна быть .

Файлы шаблонов

Файлы шаблонов Twirl должны размещаться под src/main/twirl или src/test/twirl, аналогично источникам scala или java. Можно настроить дополнительные расположения для файлов шаблонов.

⚠️ Обратите внимание, что результатом компиляции шаблона является исходный код Scala. Если вы используете эти шаблоны в своих исходных файлах Java, вы должны поместить их в папку совместной компиляции (см. документацию Gradle Scala Plugin для получения подробной информации). По умолчанию расположение этой папки — src/main/scala, но его можно настроить.

Файлы шаблонов должны называться {name}.scala.{ext}, где ext может быть html, js, xml или txt.

Дополнительные импорты

Чтобы добавить дополнительные импорты для кода Scala в файлы шаблонов, используйте ключ templateImports. Например:

sourceSets {
  main {
    twirl {
      templateImports.add("org.example._")
    }
  }
}

Исходные каталоги

Чтобы настроить исходные каталоги, в которых будут найдены файлы шаблонов, используйте метод srcDir для SourceDirectorySet. Например:

sourceSets {
  main {
    twirl {
      srcDir("app")
    }
  }
}

Версия Scala

Для настройки версии Scala используйте свойство scalaVersion класса TwirlExtension (2.13 по умолчанию). Например:

twirl {
  scalaVersion.set("3")
}

Другие свойства

Также можно использовать следующие свойства:

sourceSets {
  main {
    twirl {
      // Аннотации, добавленные к конструкторам в шаблонах с возможностью внедрения
      constructorAnnotations.add("@org.example.MyAnnotation()")
      // Определённые пользовательские форматы шаблонов Twirl
      templateFormats.put("csv", "play.twirl.api.TxtFormat")
      // Исходная кодировка для файлов шаблонов и сгенерированных файлов Scala
      sourceEncoding.set("<enc>")
    }
  }
}

Моментальные снимки

Чтобы использовать версию моментального снимка, добавьте репозиторий моментальных снимков Sonatype в settings.gradle.kts:

pluginManagement {
  repositories {
    maven {
      url = uri("https://oss.sonatype.org/content/repositories/snapshots")
    }
  }
}

Выпуск новой версии

См. https://github.com/playframework/.github/blob/main/RELEASING.md.

Благодарности

Название twirl было придумано командой Spray и относится к… В языке шаблонов есть волшебный символ @, который иногда называют «twirl».

Первая отдельная версия Twirl была создана командой [Spray].

Оптимизированную версию парсера Twirl предоставила команда [Scala IDE].