Document displaying of Scala values by BaseScalaTemplate (#160)

docs/manual/working/scalaGuide/main/templates/ScalaTemplates.md

@@ -168,4 +168,16 @@ For example to output raw HTML:
 
 The template engine can be used as a [string interpolator](http://docs.scala-lang.org/overviews/core/string-interpolation.html). You basically trade the “@” for a “$”:
 
-@[string-interpolation](code/ScalaTemplates.scala)
+@[string-interpolation](code/ScalaTemplates.scala)
+
+## Displaying Scala types
+
+Twirl typically renders values of Scala types by calling `toString` method on them. However, if values are wrapped inside `Option` or collections (`Seq`, `Array`, `TraversableOnce`), Twirl first unwraps the values  and then calls `toString`. 
+
+For example,
+
+@[display-scala-types](code/scalaguide/templates/displayScalaTypes.scala.html)
+
+is rendered in the browser as
+
+[[images/displayScalaTypes.png]]

docs/manual/working/scalaGuide/main/templates/code/ScalaTemplates.scala

@@ -147,5 +147,16 @@ object ScalaTemplatesSpec extends Specification {
         body must contain("<foo>")
       }
     }
+
+    "display Scala types" in {
+      val body = html.displayScalaTypes().body
+
+      body must contain("User(Foo,Bar)")
+      body must contain("value inside option")
+      body must not contain("Option(value inside option)")
+      body must contain("firstlast")
+      body must not contain("List")
+      body must contain("helloUser(Foo,Bar)value inside optionfirstlast")
+    }
   }
 }

docs/manual/working/scalaGuide/main/templates/code/scalaguide/templates/displayScalaTypes.scala.html

@@ -0,0 +1,12 @@
+@import scalaguide.templates._
+
+@()
+
+@* #display-scala-types *@
+<ul>
+  <li>@Option("value inside option")</li>
+  <li>@List("first", "last")</li>
+  <li>@User("Foo", "Bar")</li>
+  <li>@List("hello", User("Foo", "Bar"), Option("value inside option"), List("first", "last"))</li>
+</ul>
+@* #display-scala-types *@