From ff45d24103684342a47ec2ed42565356a116f18d Mon Sep 17 00:00:00 2001
From: Iurii Malchenko <yurique@pm.me>
Date: Fri, 2 Nov 2018 09:30:52 +0200
Subject: improving twirl (#473)

* improving twirl support: default imports, better `compileTwirl().classes` value

* twirl module doc edits
---
 docs/pages/9 - Contrib Modules.md | 115 ++++++++------------------------------
 1 file changed, 22 insertions(+), 93 deletions(-)

(limited to 'docs/pages/9 - Contrib Modules.md')

diff --git a/docs/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md
index cd02f2c2..4d811cde 100644
--- a/docs/pages/9 - Contrib Modules.md	
+++ b/docs/pages/9 - Contrib Modules.md	
@@ -161,14 +161,16 @@ Also note that twirl templates get compiled into scala code, so you also need to
 ```scala
 import $ivy.`com.lihaoyi::mill-contrib-twirllib:0.3.2`,  mill.twirllib._
 object app extends ScalaModule with TwirlModule {
-
+// ...
 } 
 ``` 
 
 #### Configuration options
 
-* ` def twirlVersion: T[String]` (mandatory) - the version of the twirl compiler to use, like "1.3.15"
-
+* `def twirlVersion: T[String]` (mandatory) - the version of the twirl compiler to use, like "1.3.15"
+* `def twirlAdditionalImports: Seq[String] = Nil` - the additional imports that will be added by twirl compiler to the top
+  of all templates
+  
 #### Details
 
 The following filesystem layout is expected:
@@ -197,107 +199,34 @@ object app extends ScalaModule with TwirlModule {
 }
 ``` 
 
-#### Caveats
-
-There is a couple of caveats, to be aware of, as of now (in `v0.3.2`).
-
-##### Packages 
-First, if you structure your twirl templates into packages, like this:
-```text
-build.sc
-app/
-    src/hello/
-        Main.scala
-    views/
-        hello/
-            another/ 
-                view1.scala.html
-                view2.scala.html
-```
-
-the generated sources in the `out` directory will look like this:
-```text
-build.sc
-out/app/compileTwirl/dest/
-    hello/
-      another/
-        html/
-          view1.template.scala
-          view2.template.scala
-```
-
-Looking at the `mill show app.compileTwirl` in this setup shows this:
-```
-{
-    ...
-    "classes": "ref: ... : .../out/app/compileTwirl/dest/html"
-}
-```
-
-Basically it means that currently `TwirlModule` expects all templates to be html and with no packages.
-So adding this directly to the generated sources will not exactly work as expected (as there might not even be a `out/app/compileTwirl/dest/html` directory
-at all, unless you have templates in the default package).
-
-The workaround is simple, though:
+To add additional imports to all of the twirl templates:
 ```scala
 object app extends ScalaModule with TwirlModule {
   def twirlVersion = "1.3.15"
-  override def generatedSources = T{
-    val classes = compileTwirl().classes
-    Seq(classes.copy(path = classes.path / up)) // we just move one dir up
-  }
+  override def twirlAdditionalImports = Seq("my.additional.stuff._", "my.other.stuff._")
+  def generatedSources = T{ Seq(compileTwirl().classes) }
 }
 ``` 
 
-This should cover the problem with templates under packages, and also should make other-than-html 
-templates available as well.
-
-##### Default imports
-
-Another problem is with some default imports that the twirl sbt plugin assumes, but it seems not to work with `TwirlModule`.
-
-If you reference `Html` in your templates, like
-
+as the result all templates will get this line at the top:
 ```scala
-// wrapper.scala.html
-@(content: Html)
-<div class="wrapper">
-  @content
-</div>
+@import "my.additional.stuff._"
+@import "my.other.stuff._"
 ```
 
-the template will not compile. You'll need to add this import:
-```
-@import play.twirl.api._
-```
-
-in the template that uses twirl classes.
-
-Another one is `@defining`, which might be used like this:
-```
-@defining({
-  val calculatedClass = {
-    // do some calculations here
-  }
-  calculatedClass
-}) { calculatedClass =>
-    <div class="@calculatedClass">stuff 1</div>
-    <div class="@calculatedClass">stuff 2</div>
-}
-```
-
-You'll need this import:
+Besides that, twirl compiler has default imports, at the moment these:
 ```scala
-@import play.twirl.api.TwirlFeatureImports._
-```
-
-At some point `TwirlModule` might get support for the additional "default" imports, which will make this much easier, 
-but right now it is unimplemented
+Seq(
+    "_root_.play.twirl.api.TwirlFeatureImports._",
+    "_root_.play.twirl.api.TwirlHelperImports._",
+    "_root_.play.twirl.api.Html",
+    "_root_.play.twirl.api.JavaScript",
+    "_root_.play.twirl.api.Txt",
+    "_root_.play.twirl.api.Xml"
+)
+``` 
 
-```scala
-  // REMIND currently it's not possible to override these default settings
-  private def twirlAdditionalImports: Seq[String] = Nil
-```
+These imports will always be added to every template.  You don't need to list them if you override `twirlAdditionalImports`.
 
 #### Example
 There's an [example project](https://github.com/lihaoyi/cask/tree/master/example/twirl)
-- 
cgit v1.2.3