Merge lp:~schuller-lunatech/play/1.1-scala-tutorial into lp:play/1.1

[Bart Schuller]

[Bart Schuller (schuller-lunatech)]

A few more Scala tutorial chapters. Also enables printing of deprecation warnings, which is better than just being told there are some.

This may be my last contribution for a while, so feel free to continue without me.

=== modified file 'documentation/manual/scguide2.textile'
--- documentation/manual/scguide2.textile	2009-11-09 21:58:51 +0000
+++ documentation/manual/scguide2.textile	2009-11-25 08:20:26 +0000
@@ -32,8 +32,9 @@
     var fullname: String
 ) extends Model {
  
-    var isAdmin: boolean = false
+    var isAdmin: Boolean = false
  
+    def this() = this(null, null, null)
 }
 
 If you're new to Scala then this class definition might look a bit strange. What is happening here is that the definition of 3 fields is combined with the definition of the primary constructor. Then there is a fourth field which is set to false by default.
@@ -42,6 +43,7 @@
 
 * a public class
 * a public 3-argument constructor
+* a public 0-argument constructor
 * 4 private fields
 * 4 public accessors and mutators
 
@@ -159,6 +161,7 @@
  
     var postedAt: Date = new Date()
  
+    def this() = this(null, null, null)
 }
 
 Here we use the **@Lob** annotation to tell JPA to use a large text database type to store the post content. We have declared the relation to the User class using **@ManyToOne**. That means that each Post is authored by a single User, and that each User can author several Posts.
@@ -230,6 +233,7 @@
  
     var postedAt: Date = new Date()
  
+    def this() = this(null, null, null)
 }
 
 Let's write a first test case:

=== added file 'documentation/manual/scguide3.textile'
--- documentation/manual/scguide3.textile	1970-01-01 00:00:00 +0000
+++ documentation/manual/scguide3.textile	2009-11-25 08:20:26 +0000
@@ -0,0 +1,329 @@
+h1. Building the first screen (Scala version)
+
+Now that we have built a first data model, it's time to start to create the first page of the application. This page will just show the most recent posts, as well as a list of older posts.
+
+Here is a mock of what we want to achieve:
+
+!images/guide-mock1!
+
+h2. <a>Bootstrapping with default data</a>
+
+In fact before coding the first screen we need one more thing. Working on a web application without test data is not fun. You can't even test what you're doing. But because we haven't developed the contribution screens yet, we can't populate the blog with posts ourselves. 
+
+One way to inject default data into the blog is to load a fixture file at application load time. To do that we will create a Bootstrap Job. A play job is something that executes itself outside of any HTTP request, for example at the application start or at specific interval using a CRON job.
+
+Let's create the **/yabe/app/Bootstrap.java** job that will load a set of default data using fixture:
+
+bc. import play._
+import play.jobs._
+import play.test._
+import play.db.jpa.QueryFunctions._
+ 
+import models._
+ 
+@OnApplicationStart
+class Bootstrap extends Job {
+ 
+    override def doJob() {
+        // Check if the database is empty
+        if(count[User] == 0) {
+            Fixtures.load("initial-data.yml")
+        }
+    }
+ 
+}
+
+We have annotated this Job with the **@OnApplicationStart** annotation to tell play that we want to run this jobs synchronously at the application start.
+
+p(note). In fact this job will be run differently in DEV or PROD modes. In DEV mode, play waits for a first request to start. So this job will be executed synchronously at the first request. This way, if the job fail, you will get the error message in your browser. In PROD mode however, the job will be executed at application start (synchrously with the **'play run'** command) and will prevent the application to start in case of error.
+
+You have to create a initial-data.yml in the **/yabe/conf** directory. You can of course reuse the **data.yml** content that we just used for tests previously.
+
+Now run the application using **play run** and display the "http://localhost:9000":http://localhost:9000 page in the browser.
+
+h2. <a>The blog home page</a>
+
+This time, we can really start to code the home page.
+
+Do you remember how the first page is displayed? First the routes file defines that the **/** URL will invoke the **controllers.Application.index()** action method. Then this method calls **render()** and execute the **/yabe/app/views/Application/index.html** template.
+
+We will keep these components but add code to them to load the posts list and display them.
+
+Open the **/yabe/app/controllers/Application.java** controller and modify the **index()** action to load the posts list, as is:
+
+bc. package controllers
+ 
+import play._
+import play.mvc._
+import play.db.jpa.QueryFunctions._
+ 
+import models._
+ 
+object Application extends Actions {
+ 
+    def index() {
+        val frontPost = find[Post]("order by postedAt desc").first
+        val olderPosts = find[Post](
+            "order by postedAt desc"
+        ).from(1).fetch(10)
+ 
+        render(frontPost, olderPosts)
+    }
+ 
+}
+
+Can you see how we pass objects to the render method? It will allow us to access them from the template using the same name.
+
+Open the **/yabe/app/views/Application/index.html** and modify it to display these objects:
+
+bc. #{extends 'main.html' /}
+#{set title:'Home' /}
+ 
+#{if frontPost}
+    <div class="post">
+        <h2 class="post-title">
+            <a href="#">${frontPost.title}</a>
+        </h2>
+        <div class="post-metadata">
+            <span class="post-author">by ${frontPost.author.fullname}</span>
+            <span class="post-date">${frontPost.postedAt.format('MMM dd')}</span>
+            <span class="post-comments">
+                &nbsp;|&nbsp; 
+                ${frontPost.comments.size() ?: 'no'} 
+                comment${frontPost.comments.size().pluralize()}</a>
+                #{if frontPost.comments}
+                    , latest by ${frontPost.comments[0].author}
+                #{/if}
+            </span>
+        </div>
+        <div class="post-content">
+            ${frontPost.content.nl2br()}
+        </div>
+    </div>
+    
+    #{if olderPosts.size() > 1}
+        <div class="older-posts">    
+            <h3>Older posts <span class="from">from this blog</span></h3>
+        
+            #{list items:olderPosts, as:'oldPost'}
+                <div class="post">
+                    <h2 class="post-title">
+                        <a href="#">${oldPost.title}</a>
+                    </h2>
+                    <div class="post-metadata">
+                        <span class="post-author">
+                            by ${oldPost.author.fullname}
+                        </span>
+                        <span class="post-date">
+                            ${oldPost.postedAt.format('dd MMM yy')}
+                        </span>
+                        <div class="post-comments">
+                            ${oldPost.comments.size() ?: 'no'} 
+                            comment${oldPost.comments.size().pluralize()}
+                            #{if oldPost.comments}
+                                - latest by ${oldPost.comments[0].author}
+                            #{/if}
+                        </div>
+                    </div>
+                </div>
+            #{/list}
+        </div>
+        
+    #{/if}
+    
+#{/if}
+ 
+#{else}
+    <div class="empty">
+        There is currently nothing to read here.
+    </div>
+#{/else}
+
+You can read more about the "template language here":templates. Basically, it allows you to access your java objects dynamically. Under the hood we use Groovy. Most of the pretty constructs you see (like the ?: operator) come from Groovy. But you don't really need to learn groovy to write play templates. If you're already familiar with another template language like JSP with JSTL you won't be lost.
+
+OK, now refresh the blog home page.
+
+!images/guide3-0!
+
+Not pretty but it works!
+
+However you see you have already started to duplicate code. Because we will display posts in several fashions (full, full with comment, teaser) we should create something like a function that we could call from several templates. This is exactly what a play tag does!
+
+To create a tag, just create the new **/yabe/app/views/tags/display.html** file. A tag is just another template. It has parameters (like a function). The **#{display /}** tag will have 2 parameters: the Post object to display and the display mode which will be one of 'home', 'teaser' or 'full'.
+
+bc. *{ Display a post in one of these modes: 'full', 'home' or 'teaser' }*
+ 
+<div class="post ${_as == 'teaser' ? 'teaser' : ''}">
+    <h2 class="post-title">
+        <a href="#">${_post.title}</a>
+    </h2>
+    <div class="post-metadata">
+        <span class="post-author">by ${_post.author.fullname}</span>,
+        <span class="post-date">${_post.postedAt.format('dd MMM yy')}</span>
+        #{if _as != 'full'}
+            <span class="post-comments">
+                &nbsp;|&nbsp; ${_post.comments.size() ?: 'no'} 
+                comment${_post.comments.size().pluralize()}
+                #{if _post.comments}
+                    , latest by ${_post.comments[0].author}
+                #{/if}
+            </span>
+        #{/if}
+    </div>
+    #{if _as != 'teaser'}
+        <div class="post-content">
+            <div class="about">Detail: </div>
+            ${_post.content.nl2br()}
+        </div>
+    #{/if}
+</div>
+ 
+#{if _as == 'full'}
+    <div class="comments">
+        <h3>
+            ${_post.comments.size() ?: 'no'} 
+            comment${_post.comments.size().pluralize()}
+        </h3>
+        
+        #{list items:_post.comments, as:'comment'}
+            <div class="comment">
+                <div class="comment-metadata">
+                    <span class="comment-author">by ${comment.author},</span>
+                    <span class="comment-date">
+                        ${comment.postedAt.format('dd MMM yy')}
+                    </span>
+                </div>
+                <div class="comment-content">
+                    <div class="about">Detail: </div>
+                    ${comment.content.escape().nl2br()}
+                </div>
+            </div>
+        #{/list}
+        
+    </div>
+#{/if}
+
+Now using this tag we can rewrite the home page without code duplication :
+
+bc. #{extends 'main.html' /}
+#{set title:'Home' /}
+ 
+#{if frontPost}
+    
+    #{display post:frontPost, as:'home' /}
+    
+    #{if olderPosts.size()}
+    
+        <div class="older-posts">
+            <h3>Older posts <span class="from">from this blog</span></h3>
+        
+            #{list items:olderPosts, as:'oldPost'}
+                #{display post:oldPost, as:'teaser' /}
+            #{/list}
+        </div>
+        
+    #{/if}
+    
+#{/if}
+ 
+#{else}
+    <div class="empty">
+        There is currently nothing to read here.
+    </div>
+#{/else}
+
+Reload the page and check that all is fine.
+
+h2. <a>Improving the layout</a>
+
+As you can see, the **index.html** template extends **main.html**. Because we want to provide a common layout to all blog pages with the blog title and authentication links, we need to modify this file.
+
+Edit the **/yabe/app/views/main.html** file :
+
+bc. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+ 
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+    <head>
+        <title>#{get 'title' /}</title>		
+        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+        <link rel="stylesheet" type="text/css" media="screen" 
+            href="@{'/public/stylesheets/main.css'}" />
+        <link rel="shortcut icon" type="image/png" 
+            href="@{'/public/images/favicon.png'}" />
+    </head>
+    <body>
+        
+        <div id="header">
+            <div id="logo">
+                yabe.
+            </div>
+            <ul id="tools">
+                <li>
+                    <a href="#">Log in to write something</a>
+                </li>
+            </ul>
+            <div id="title">
+                <span class="about">About this blog</span>
+                <h1><a href="#">${blogTitle}</a></h1>
+                <h2>${blogBaseline}</h2>
+            </div>
+        </div>
+        
+        <div id="main">
+            #{doLayout /} 
+        </div>
+        
+        <p id="footer">
+            Yabe is a (not that) powerful blog engine built with the 
+            <a href="http://www.playframework.org">play framework</a>
+            as a tutorial application.
+        </p>
+        
+    </body>
+</html>
+
+Refresh and check the result. It seems to work, except that the **blogTitle** and the **blogBaseLine** variables are not displayed. This is because we didn't pass them during the **render(...)** call. Of course we could add them to the **render()** call in the index action. But because the **main.html** file will be used as main template for all application actions, we don't want to add them every time.
+
+One way to execute the same code for each action of a controller (or a hierarchy of controllers) is to define a **@Before** interceptor. 
+
+Let's add the **addDefaults()** method to the Application controller :
+
+bc. @Before
+def addDefaults() {
+	renderArgs.put("blogTitle", Play.configuration.getProperty("blog.title"))
+	renderArgs.put("blogBaseline", Play.configuration.getProperty("blog.baseline"))
+}
+
+All variables added to the **renderArgs** scope will be available from the templates. And you can see that the method reads the variable's values from the **Play.configuration** object. This object contains all configuration keys from the **/yabe/conf/application.conf** file.
+
+Add these 2 keys to the configuration file:
+
+bc. # Configuration of the blog engine
+# ~~~~~
+blog.title=Yet another blog
+blog.baseline=We won't write about anything
+
+Reload the home page and check that it works!
+
+!images/guide3-1!
+
+h2. <a>Adding some style</a>
+
+Now the blog home page is almost done, but it's not really pretty. We'll add some style to make it shinier. As you have seen, the main template file main.html includes the **/public/stylesheets/main.css** stylesheet. We'll keep it but add more style rules to it.
+
+You can "download it here":files/main.css, and copy it to the **/public/stylsheets/main.css** file.
+
+Refresh the home page and you should see a styled page now.
+
+!images/guide3-2!
+
+h2. <a>Commit your work</a>
+
+This time the blog home page is finished. As usual we can commit this blog version to bazaar:
+
+bc. $ bzr st
+$ bzr add
+$ bzr commit -m 'Home page'
+
+p(note). Go to the "next part":scguide4. 
+

=== added file 'documentation/manual/scguide4.textile'
--- documentation/manual/scguide4.textile	1970-01-01 00:00:00 +0000
+++ documentation/manual/scguide4.textile	2009-11-25 08:20:26 +0000
@@ -0,0 +1,245 @@
+h1. Viewing and posting comments (Scala version)
+
+The blog home page is now set, and we will continue by writing the post details page. This page will show all the comments about the current post, and will include a form to post new comments.
+
+h2. <a>Creating the 'show' action</a>
+
+To display the post details page, we will need a new action method to the Application controller. Let's call it **show()**:
+
+bc. def show(id: Long) {
+	val post = findById[Post](id)
+	render(post)
+}
+
+As you can see this action is pretty simple. We declare the **id** method parameter to automatically retrieve the HTTP **'id'** parameter as a Long  object. This parameter will be extracted either from the queryString, from the URL path or from the request body.
+
+p(note). If we try to send an **id** HTTP parameter that is not a valid number, the id variable value will be null and play will automatically add a validation error to the **errors** container.
+
+This action will display the **/yabe/app/views/Application/show.html** template :
+
+bc. #{extends 'main.html' /}
+#{set title:post.title /}
+ 
+#{display post:post, as:'full' /}
+
+Because we've already written the display tag, this page is really simple to write.
+
+h2. <a>Adding links to the details page</a>
+
+In the display tag we've left all links empty (using #). It's now time to make these links pointing to the **Application.show** action. With play you can easily build links in a template using the **@{...} notation**. This syntax uses the router to 'reverse' the URL needed to call the specified action. 
+
+Let's edit the **/yabe/app/views/tags/display.html** tag :
+
+bc. ...
+<h2 class="post-title">
+    <a href="@{Application.show(_post.id)}">${_post.title}</a>
+</h2>
+...
+
+You can new refresh the home page, and click on a post title to display it. 
+
+!images/guide4-0!
+
+It's great, but it lacks a link to go back to the home page. Edit the **/yabe/app/views/main.html** template to complete the title link:
+
+bc. ...
+<div id="title">
+    <span class="about">About this blog</span>
+    <h1><a href="@{Application.index()}">${blogTitle}</a></h1>
+    <h2>${blogBaseline}</h2>
+</div>
+... 
+
+We can now navigate between the home page and the post detail pages.
+
+h2. <a>Specifying a better URL</a>
+
+As you can see, the post detail page URL looks like
+
+bc. /application/show?id=1
+
+This is because play has used the default 'catch all' route.
+
+bc. *       /{controller}/{action}                  {controller}.{action}
+
+We can have a better URL by specifying a custom path for the **Application.show** action. Edit the **/yabe/conf/routes** file and add this route after the first one:
+
+bc. GET     /posts/{id}                             Application.show
+
+p(note). This way the id parameter will be extracted from the URL path.
+
+Refresh the browser and check that it now uses the correct URL.
+
+h2. <a>Adding some pagination</a>
+
+To allow users to navigate easily through posts, we will add a pagination mechanism. We'll extend the Post class to be able to fetch the previous and next post as required:
+
+bc. import play.db.jpa.QueryFunctions._
+...
+def previous(): Post = {
+    find[Post]("postedAt < ? order by postedAt desc", postedAt).first
+}
+ 
+def next(): Post = {
+    find[Post]("postedAt > ? order by postedAt asc", postedAt).first
+}
+
+Since we will call these methods several times during a request it could be optimized, but it's good enough for now. Also, add the pagination links in top of the show.html template (before the **#{display/}** tag):
+
+bc. <ul id="pagination">
+    #{if post.previous()}
+        <li id="previous">
+            <a href="@{Application.show(post.previous().id)}">
+                ${post.previous().title}
+            </a>
+        </li>
+    #{/if}
+    #{if post.next()}
+        <li id="next">
+            <a href="@{Application.show(post.next().id)}">
+                ${post.next().title}
+            </a>
+        </li>
+    #{/if}
+</ul>
+
+It's better now.
+
+h2. <a>Adding the comment form</a>
+
+Now it's time to set up a comments form. We'll start by adding the **postComment** action method to the Application controller.
+
+bc. def postComment(postId: Long, author: String, content: String) {
+    val post = findById[Post](postId)
+    post.addComment(author, content)
+    show(postId)
+}
+
+As you see we just reuse the **addComment()** method we previously added to the Post class.
+
+Let's write the HTML form in the show.html template (after the **#{display /}** tag in fact):
+
+bc. <h3>Post a comment</h3>
+ 
+#{form @Application.postComment(post.id)}
+    <p>
+        <label for="author">Your name: </label>
+        <input type="text" name="author" id="author" />
+    </p>
+    <p>
+        <label for="content">Your message: </label>
+        <textarea name="content" id="content"></textarea>
+    </p>
+    <p>
+        <input type="submit" value="Submit your comment" />
+    </p>
+#{/form}
+
+You can try to post a new comment. It should just work.
+
+!images/guide4-1!
+
+h2. <a>Adding validation</a>
+
+Currently we don't validate the form content before creating the comment. We would like to set both fields as required. We can easily use the play validation mechanism to ensure that HTTP parameters are correctly filled. Modify the **postComment** action to add validation annotations and check that no error occurs:
+
+bc. def postComment(postId: Long, @Required author: String, @Required content: String) {
+    val post = findById[Post](postId)
+    if (Validation.hasErrors()) {
+        render("Application/show.html", post)
+    }
+    post.addComment(author, content)
+    show(postId)
+}
+
+p(note). **Don't forget** to import play.data.validation._ as well.
+
+As you see, in case of validation errors, we re-display the post detail page. We have to modify the form code to display the error message:
+
+bc. <h3>Post a comment</h3>
+ 
+#{form @Application.postComment(post.id)}
+ 
+    #{ifErrors}
+        <p class="error">
+            All fields are required!
+        </p>
+    #{/ifErrors}
+ 
+    <p>
+        <label for="author">Your name: </label>
+        <input type="text" name="author" id="author" value="${params.author}" />
+    </p>
+    <p>
+        <label for="content">Your message: </label>
+        <textarea name="content" id="content">${params.content}</textarea>
+    </p>
+    <p>
+        <input type="submit" value="Submit your comment" />
+    </p>
+#{/form}
+
+Note that we reuse the posted parameters to fill the HTML input values.
+
+To make the UI feedback more pleasant for the poster, we will add a little Javascript to automatically focus the comment form in case of an error. As this script uses "JQuery":files/jquery-1.3.2.min.js and "JQuery Tools":files/jquery.tools.min.js as support libraries, you have to include them. Download these 2 libraries to the **/yabe/public/javascripts** directory and modify the **main.html** template to include them:
+
+bc. ...
+    <script src="@{'/public/javascripts/jquery-1.3.2.min.js'}"></script>
+    <script src="@{'/public/javascripts/jquery.tools.min.js'}"></script>
+</head>
+
+Now you can add this script to the **show.html** template (add it at the end of the page):
+
+bc. <script type="text/javascript" charset="utf-8">
+    $(function() {         
+        // Expose the form 
+        $('form').click(function() { 
+            $('form').expose({api: true}).load(); 
+        }); 
+        
+        // If there is an error, focus to form
+        if($('form .error').size()) {
+            $('form').expose({api: true, loadSpeed: 0}).load(); 
+            $('form input').get(0).focus();
+        }
+    });
+</script>
+
+!images/guide4-2!
+
+The comment form looks pretty cool now. We will add two more things.
+
+First we will display a success message after a comment is successfully posted. For that, we use the flash scope that allows to dispatch messages from one action call to the next one.
+
+Modify the **postComment** action to add a success message:
+
+bc. public static void postComment(Long postId, @Required String author, @Required String content) {
+    Post post = Post.findById(postId);
+    if(validation.hasErrors()) {
+        render("Application/show.html", post);
+    }
+    post.addComment(author, content);
+    flash.success("Thanks for posting, %s", author);
+    show(postId);
+}
+
+and display the success message in the **show.html** if present (add it at the top the page):
+
+bc. ...
+#{if flash.success}
+    <p class="success">${flash.success}</p>
+#{/if}
+ 
+#{display post:post, as:'full' /}
+...
+
+!images/guide4-3!
+
+The last thing we will adjust in this form is the URL used for the **postComment** action. As always it uses the default catch all route because we didn't define any specific route. So add this route to the application routes file:
+
+bc. POST    /posts/{postId}/comments                Application.postComment
+
+That's done. As always, commit the version to bazaar.
+
+p(note). Go to the "next part":scguide5. 
+

=== added file 'documentation/manual/scguide5.textile'
--- documentation/manual/scguide5.textile	1970-01-01 00:00:00 +0000
+++ documentation/manual/scguide5.textile	2009-11-25 08:20:26 +0000
@@ -0,0 +1,137 @@
+h1. Setting up a captcha (Scala version)
+
+Because anyone can post a comment to our blog engine, we should protect it a little to avoid automated spam. A simple way to protect a form from this is to add a captcha image.
+
+h2. <a>Generating the captcha image</a>
+
+We'll start to see how we can easily generate a captcha image using play. Basically we will just use another action, except that it will return a binary stream instead of HTML responses like what we've returned so far.
+
+Play being a **full-stack** web framework, we try to include built-in constructs for a web application's most typical needs; generating a captcha is one of them. We can use the **play.libs.Images** utility to simply generate a captcha image, and then write it to the HTTP response. 
+
+As usual, we will start with a simple implementation. Add the **captcha** action to the **Application** controller:
+
+bc. def captcha() {
+    val captcha = Images.captcha()
+    renderBinary(captcha)
+}
+
+Note that we can pass the captcha object directly to the renderBinary() method because the Images.Captcha class implements java.io.InputStream. 
+
+p(note). **Don't forget** to import play.libs._
+
+Now add a new route to the **/yabe/conf/routes** file:
+
+bc. GET     /captcha                                Application.captcha
+
+And try the **captcha** action by opening "http://localhost:9000/captcha":http://localhost:9000/captcha.
+
+!images/guide5-1!
+
+It should generate a random text for each refresh.
+
+h2. <a>How to manage the state?</a>
+
+Until now it was easy, but the most complicated part is coming. To validate the captcha we need to save the random text written to the captcha image and then check it at the form submission time. 
+
+Of course we could just put the text in the user session at image generation time and then retrieve it later. But this solution has two drawbacks:
+
+**First** the play session is stored as a cookie. It solves a lot of problems in terms of architecture but has a lot of implications. Data written to the session cookie are signed (so the user can't modify them) but not encrypted. If we write the captcha code to the session any bot could easily resolve it by reading the session cookie.
+
+**Then** remember that play is a **stateless** framework. We want to manage things in a pure stateless way. Typically, what happens if a user simultaneously opens two different blog pages with two different captcha images? We have to track the captcha code for each form.
+
+So to resolve the problem we need two things. We will store the captcha secret key on the server side. Because it is transient data we can easily use the play **Cache**. Moreover because cached data have a limited life time it will add one more security mechanism (let's say that a captcha code will be available for only 10mn). Then to resolve the code later we need to generate a **unique ID**. This unique ID will be added to each form as a hidden field and implicitly references a generated captcha code.
+
+This way we elegantly solve our state problem.
+
+Modify the **captcha** action as follows:
+
+bc. def captcha(id: String) {
+    val captcha = Images.captcha()
+    val code = captcha.getText("#E4EAFD")
+    Cache.set(id, code, "10mn")
+    renderBinary(captcha)
+}
+
+Note that the **getText()** method takes any color as parameter. It will use this color to draw the text.
+
+p(note). **Don't forget** to import play.cache._
+
+h2. <a>Adding the captcha image to the comment form</a>
+
+Now, before displaying a comment form we will generate a unique ID. Then we will modify the HTML form to integrate a captcha image using this ID, and add the ID to another hidden field.
+
+Let's rewrite the **Application.show** action:
+
+bc. public static void show(Long id) {
+    Post post = Post.findById(id);
+    String randomID = Codec.UUID();
+    render(post, randomID);
+}
+
+And now the form in the **/yable/app/views/Application/show.html** template:
+
+bc. ...
+<p>
+    <label for="content">Your message: </label>
+    <textarea name="content" id="content">${params.content}</textarea>
+</p>
+<p>
+    <label for="code">Please type the code below: </label>
+    <img src="@{Application.captcha(randomID)}" />
+    <br />
+    <input type="text" name="code" id="code" size="18" value="" />
+    <input type="hidden" name="randomID" value="${randomID}" />
+</p>
+<p>
+    <input type="submit" value="Submit your comment" />
+</p>
+...
+
+Good start. The comment form now has a captcha image.
+
+!images/guide5-2!
+
+h2. <a>Validating the captcha</a>
+
+Now we just have to validate the captcha. We have added the **randomID** as an hidden field right ? So we can retrieve it in the **postComment** action, then retrieve the actual code from Cache and finally compare it to the submitted code.
+
+Not that difficult. Let's modify the **postComment** action.
+
+bc. public static void postComment(
+        Long postId, 
+        @Required(message="Author is required") String author, 
+        @Required(message="A message is required") String content, 
+        @Required(message="Please type the code") String code, 
+        String randomID) 
+{
+    Post post = Post.findById(postId);
+    validation.equals(
+        code, Cache.get(randomID)
+    ).message("Invalid code. Please type it again");
+    if(validation.hasErrors()) {
+        render("Application/show.html", post, randomID);
+    }
+    post.addComment(author, content);
+    flash.success("Thanks for posting %s", author);
+    show(postId);
+}
+
+Because we have now more error messages, modify the way we display errors in the **show.html** template (yes we will just display the first error, it's good enough):
+
+bc. .. 
+#{ifErrors}
+    <p class="error">
+        ${errors[0]}
+    </p>
+#{/ifErrors}
+...
+
+p(note). Typically for more complex forms, error messages are not managed this way but externalized in the **messages** file and each error is printed in side of the corresponding field.
+
+Check that the captcha is now fully functional.
+
+!images/guide5-3!
+
+Great!
+
+p(note). Go to the "next part":guide6. 
\ No newline at end of file

=== modified file 'modules/scala/src/play/scalasupport/core/ScalaPlugin.scala'
--- modules/scala/src/play/scalasupport/core/ScalaPlugin.scala	2009-11-24 20:05:47 +0000
+++ modules/scala/src/play/scalasupport/core/ScalaPlugin.scala	2009-11-25 08:20:26 +0000
@@ -85,7 +85,8 @@
         private val virtualDirectory = new VirtualDirectory("(memory)", None)
         private val settings = new Settings()
         settings.debuginfo.level = 3
-        settings.outputDirs setSingleOutput virtualDirectory        
+        settings.outputDirs setSingleOutput virtualDirectory   
+        settings.deprecation.value = true
         private val compiler = new Global(settings, reporter)
 
         def compile(sources: List[VFile]) = {