{"id":19589445,"url":"https://github.com/spray/twirl","last_synced_at":"2025-04-27T12:32:26.956Z","repository":{"id":66754336,"uuid":"3366127","full_name":"spray/twirl","owner":"spray","description":"The Play framework Scala template engine, stand-alone and packaged as an SBT plugin","archived":false,"fork":false,"pushed_at":"2014-06-06T14:46:47.000Z","size":534,"stargazers_count":215,"open_issues_count":4,"forks_count":20,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-03-25T22:12:36.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spray.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-02-06T10:38:34.000Z","updated_at":"2024-03-25T22:12:36.022Z","dependencies_parsed_at":"2023-02-20T10:45:46.613Z","dependency_job_id":null,"html_url":"https://github.com/spray/twirl","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spray%2Ftwirl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spray%2Ftwirl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spray%2Ftwirl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spray%2Ftwirl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spray","download_url":"https://codeload.github.com/spray/twirl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224069638,"owners_count":17250505,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T08:18:30.062Z","updated_at":"2024-11-11T08:18:31.099Z","avatar_url":"https://github.com/spray.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"#######\n Twirl\n#######\n\n**Note:**\n\n**Twirl has moved** `back home to play`_ **where all future versions will live. The new\nofficial version only supports sbt \u003e= 0.13.5. If you depend on an older version of sbt read on, otherwise, you will probably\nbe better off directly heading over to the new repository.**\n\n\n*Twirl* is the `Play Framework`_ `Scala template engine`_, repackaged for stand-alone use.\nThis project provides an `SBT`_ plugin that lets you use *Twirl* in your Scala_ applications without any additional\ndependencies on the `Play Framework`_.\n\nThe `Scala template engine`_ (which we dubbed *Twirl*, see below) provided by Play 2.0 enables type-safe templating that\nintegrates seamlessly into your Scala applications. Templates are text files containing a mix of \"markup\" and Scala code.\nAt compile time the Twirl compiler translates them into actual Scala source files, which are then picked up by the Scala\ncompiler and compiled together with the rest of your application sources into regular .class files.\nOn a type level each template is just a function from a number of (strongly typed) input values to a result object.\n\nThe *Twirl* SBT plugin smoothly integrates templating support into your Scala builds. It supports triggered\ncompilation (via SBTs ``~`` operator) as well as hot reloading via `sbt-revolver`_.\n\n**Note:** The large majority of the code within this project, i.e. the twirl-api, the twirl-compiler and significant\nportions of the SBT plugin are nothing but verbatim copies of the respective code pieces from the\n`Play Framework Repository`_. All credits and copyrights for these belong to Play framework team.\n\n.. _`back home to play`: https://github.com/playframework/twirl\n\nInstallation\n============\n\nsbt-twirl requires SBT 0.13 or 0.12. Add the following dependency to your ``project/*.sbt`` file\n(e.g. ``project/plugins.sbt``)::\n\n    // needed because sbt-twirl depends on twirl-compiler which is only available\n    // at repo.spray.io\n    resolvers += \"spray repo\" at \"http://repo.spray.io\"\n\n    addSbtPlugin(\"io.spray\" % \"sbt-twirl\" % \"0.7.0\")\n\nThen, in your ``build.sbt``::\n\n    Twirl.settings\n\nIf you use SBTs full-configuration you need to::\n\n    import twirl.sbt.TwirlPlugin._\n\nand then add the ``Twirl.settings`` to all (sub-)projects containing *Twirl* templates.\n\n\nUsage\n=====\n\n*Twirl* template files are expected to live in the ``twirl`` subdirectory of your source directory, e.g. ``src/main/twirl``.\nThey have to be named ``{template-name}.scala.{ext}``, whereby ``ext`` can be either ``html``, ``xml`` or ``txt``\n(more extensions might be supported in the future).\n\nExample::\n\n    {project-directory}/src/main/twirl/index.scala.html\n\n\nTemplate Syntax\n---------------\n\nThe internal template syntax is documented `here`__. Currently the Twirl engine does not differ from the original\nPlay Scala Template Engine in any way.\n\n\n__ `Scala template engine`_\n\n\nTemplate Rendering\n------------------\n\nTo your Scala code a template is an object providing the following methods::\n\n    def apply(: A, b: B, ...): R\n\n    def render(a: A, b: B, ...): R = apply(a, b, ...)\n\n    def f: (A, B) =\u003e R = (a, b) =\u003e apply(a, b)\n\nwhereby ``A`` and ``B`` are the parameter types you have specified in the first line of your template.\n``R`` is the result type, which is either ``twirl.api.Html``, ``twirl.api.Txt`` or ``twirl.api.Xml``, depending on\nthe extension of your template. All result types are defined in `this file`_, please check it out to understand what\ninterface the respective result type offers.\n\n\n.. _`this file`: https://github.com/spray/twirl/blob/master/twirl-api/src/main/scala/twirl/api/Formats.scala\n\n\nFrom your Scala code you \"render\" a template by simply calling one of its methods, e.g., the template defined in\n``{project-directory}/src/main/twirl/index.scala.html`` would could be called with::\n\n    html.index.render(\"Bob\", 42)\n\nand the template ``{project-directory}/src/main/twirl/org/example/hello.scala.txt`` could be called with::\n\n    org.example.txt.hello(\"Fred\", \"Astair\")\n\n\nPackage Names\n-------------\n\nAs you already might have guessed from the last example above sub directories underneath the ``../twirl`` template\ndirectory are turned into package names for the created template objects. So, if you place a template in the\n``{project-directory}/src/main/twirl/org/example/`` directory it will have the package ``org.example.html``,\n``org.example.txt`` or ``org.example.xml``, depending on the file extension.\n\nSo, for example, if you'd like to include a template ``{project-directory}/src/main/twirl/org/example/Foo.scala.html``\nfrom another template you would say ``@org.example.html.Foo()``.\n\n\nConfiguration\n=============\n\nsbt-twirl currently offers the following customization options:\n\n1. ``twirlImports = SettingKey[Seq[String]]``: lets you specify one or more imports that are to be made available to the\n   Scala source in your template files.\n\n   For example::\n\n       twirlImports := Seq(\"org.example.util._\", \"com.mycompany.DbTools\")\n\n   will be turned into the following import statements::\n\n       import org.example.util._\n       import com.mycompany.DbTools\n\n   In addition the strings in ``twirlImports`` can contain a ``%format%`` placeholder, which is replaced with the template\n   file extension. This way you can target imports for specific template types.\n\n2. ``twirlSourceCharset = SettingKey[Charset]``: lets you specify the `java.nio.charset.Charset` to use when reading\n   twirl template sources and writing their corresponding ``.scala`` files. The default value is the ``UTF-8`` charset.\n\n3. ``twirlRecompilationLogger = TaskKey[(File, File) =\u003e Unit]``: lets you specify a custom logging function to call when\n   one twirl file is being recompiled. For each file that needs recompilation, the function is invoked with the source\n   and target file. Per default, one line is logged per file. E.g. to switch off logging completely you can use\n   a setting ``Twirl.twirlRecompilationLogger := ((_, _) =\u003e ())``.\n\nExample\n=======\n\nThe ``/example`` directory of this project contains a tiny, stand-alone SBT 0.11.2 example project that you can look\nat or use as the basis for your own endeavors.\n\n\nWhy \"Twirl\" ?\n=============\n\nAs a replacement for the rather unwieldy name \"Play Framework Scala template engine\" we were looking for something\nshorter with a bit of \"punch\" and liked *Twirl* as a reference to the template languages \"magic\" character ``@``,\nwhich is sometimes also called \"twirl\".\n\n\nKnown Issues\n============\n\nScala compilation errors in templates will be shown twice. Once as the verbatim error message as generated by the\ncompiler for the Scala source file created by the *Twirl* compiler and once mapped to the actual location in the\ntemplate source file. Suppressing the first message probably requires a fix in SBT.\n\n\nLicense\n=======\n\nJust like the `Play Framework`_ `Scala template engine`_ *Twirl* is licensed under the `Apache License 2.0`_.\n\n\nCredits\n=======\n\nAll credits are to go to the Play developers who devised the template language and provided its implementation! Thanks\nto @4lex1v for updating twirl to the latest upstream version which supports sbt 0.13.\n\n\nPatch Policy\n============\n\nFeedback and contributions to the project, no matter what kind, are always very welcome. However, patches can only be\naccepted from their original author. Along with any patches, please state that the patch is your original work and that\nyou license the work to the twirl project under the project’s open source license.\n\n\n.. _`Play Framework`: http://www.playframework.org/\n.. _`Scala`: http://www.scala-lang.org/\n.. _`Scala template engine`: http://www.playframework.org/documentation/2.0/ScalaTemplates\n.. _`SBT`: https://github.com/harrah/xsbt/wiki\n.. _`sbt-revolver`: https://github.com/spray/sbt-revolver\n.. _`Play Framework Repository`: https://github.com/playframework/Play20\n.. _`Apache License 2.0`: http://www.apache.org/licenses/LICENSE-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspray%2Ftwirl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspray%2Ftwirl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspray%2Ftwirl/lists"}