- Revision
- 487
- Author
- mauro
- Date
- 2007-12-15 09:38:32 -0600 (Sat, 15 Dec 2007)
Log Message
Added docs on PRG and file uploads.
Modified Paths
- trunk/waffle-distribution/src/site/content/action-methods.html
- trunk/waffle-distribution/src/site/content/sitemap.xml
Added Paths
Diff
Modified: trunk/waffle-distribution/src/site/content/action-methods.html (486 => 487)
--- trunk/waffle-distribution/src/site/content/action-methods.html 2007-12-15 12:00:18 UTC (rev 486) +++ trunk/waffle-distribution/src/site/content/action-methods.html 2007-12-15 15:38:32 UTC (rev 487) @@ -124,7 +124,7 @@ </textarea> </dl> - <h3>The ActionMethod annotation (default)</h3> + <h3>The ActionMethod annotation (default behavior)</h3> <p> The <b>ActionMethod</b> annotation allows you to define the parameter names that should be used to resolve your @@ -214,17 +214,16 @@ </dd> </dl> - <h3>The DefaultActionMethod annotation</h3> + <h3>The default ActionMethod</h3> <p> Many time when a user first visits a page you may want to ensure that the action instance is properly initialized. In other words you may want a default ActionMethod to be triggered on that Controller when no other ActionMethod has - been triggered. For that Waffle provides the <b>DefaultActionMethod</b> annotation. In the example below we have a + been triggered. For that Waffle provides the <b>asDefault</b> attribute in <b>ActionMethod</b> annotation. In the example below we have a <i>CheckoutController</i> that will calculate the shipping cost by default when no other ActionMethod has been triggered. The method that has been annotated with - <b>@ActionMethod(asDefault=true, parameters = <a name=""theCart", "customerAddress"">"theCart", - "customerAddress"</a>)</b>. These two values, <b>theCart</b> and <b>customerAddress</b>, will be used - to resolve that methods arguments. + <b>@ActionMethod(asDefault=true, parameters = "theCart", "customerAddress")</b>. + These two values, <b>theCart</b> and <b>customerAddress</b>, will be used to resolve that methods arguments. </p> <textarea class="java:nogutter:nocontrols" name="code"> @@ -251,7 +250,7 @@ <dl> <dt>Note:</dt> <dd> - DefaultActionMethod annotations are also used when utilizing ParaNamer. They are needed so Waffle can handle + ActionMethod annotations are also used when utilizing ParaNamer. They are needed so Waffle can handle requests when no ActionMethod has been signalled. </dd> </dl> @@ -276,7 +275,7 @@ </li> <li> <b>null or void</b> - When an ActionMethod has a return type of <i>void</i> or when your ActionMethod returns a - <i>null</i> Waffle will simply redirect back to the referring page. + <i>null</i> Waffle will simply redirect back to the referring page, unless <a href="" is disabled. </li> <li> <b>Exception</b> - When an exception is thrown Waffle will set the response status to 400 (BAD REQUEST) and then
Added: trunk/waffle-distribution/src/site/content/file-upload.html (0 => 487)
--- trunk/waffle-distribution/src/site/content/file-upload.html (rev 0) +++ trunk/waffle-distribution/src/site/content/file-upload.html 2007-12-15 15:38:32 UTC (rev 487) @@ -0,0 +1,72 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> + <head> + <title>File Upload</title> + </head> + <body> + + <h2>File Upload</h2> + + <p> + Waffle provides support for uploading files, using <a href="" FileUpload</a>. + File uploads are abstracted by Waffle's <a href="" + org.codehaus.waffle.io.FileUploader</a> interface which can be declared as dependency by the controllers. + Waffle provides a <a href="" implementation</a>. + </p> + <p> + Let's walk through an example. The controller would simply decare the dependency: + + <textarea class="java:nogutter:nocontrols" name="code"> + public class UploadController { + private final FileUploader; + + public UploadController(FileUploader uploader) { + this.uploader = uploader; + } + + @ActionMethod(asDefault=true) + @PRG(false) // PRG needs to be disabled to allow request-scope content to be accessible in referring view + public void upload(){ + files = uploader.getFiles(); + formFields = uploader.getFormFields(); + errors = uploader.getErrors(); + } + + public Collection<String> getErrors() { + return errors; + } + + public List<FileItem> getFiles() { + return files; + } + + public List<FileItem> getFormFields() { + return formFields; + } + } + </textarea> + + The <code>RequestFileUploader</code> needs to be registered in at request scope, along with any dependency it needs. + <textarea class="java:nogutter:nocontrols" name="code"> + @Override + public void request() { + register("fileItemFactory", DiskFileItemFactory.class); + register("uploader", RequestFileUploader.class); + register("upload", UploadController.class); + } + </textarea> + + A few comments are in order: + <ul> + <li>By default, Waffle adopts the <a href="" pattern</a>, + which for request-scoped controllers would not allow the content of the request to be made available to the view, because it would be redirected + to a new request. Hence, we disable it via the @PRG annotation to show the uploaded files in the referring view. + </li> + <li>Waffle honours to the FileUpload interfaces, which allows the implementations and the configuration to be controlled by the + user via the registrar. In particular, Waffle by default uses FileUpload's resource cleanup mechanism, detailed in the + <a href="" guide</a>. + </li> + </ul> + + </body> +</html>
Added: trunk/waffle-distribution/src/site/content/prg.html (0 => 487)
--- trunk/waffle-distribution/src/site/content/prg.html (rev 0) +++ trunk/waffle-distribution/src/site/content/prg.html 2007-12-15 15:38:32 UTC (rev 487) @@ -0,0 +1,33 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> + <head> + <title>Post/Redirect/Get</title> + </head> + <body> + + <h2>Post/Redirect/Get Pattern</h2> + + <p> + Waffle adopts by default the <a href="" pattern</a>. + Any POST request from an action method that has a void return type or returns a null value will + do a redirect as GET back to the posted page. The PRG paradigm as the advantage of allowing + back button and refresh support for free. + </p> + <p> + The PRG pattern can become problematic for request-scoped controllers that need to display the content + of the operation in the referring view. For this reason, the PRG behavior can be disabled via the + @PRG annotation on the action method: + + <textarea class="java:nogutter:nocontrols" name="code"> + public class RequestScopedController { + + @ActionMethod(asDefault=true) + @PRG(false) // PRG needs to be disabled to allow request-scope content to be accessible in referring view + public void calculateSomething(){ + // calculate something that we'd want to display in referring view + } + } + </textarea> + + </body> +</html>
Modified: trunk/waffle-distribution/src/site/content/sitemap.xml (486 => 487)
--- trunk/waffle-distribution/src/site/content/sitemap.xml 2007-12-15 12:00:18 UTC (rev 486) +++ trunk/waffle-distribution/src/site/content/sitemap.xml 2007-12-15 15:38:32 UTC (rev 487) @@ -28,12 +28,14 @@ <page>i18n.html</page> <page>registrar.html</page> <page>views.html</page> + <page>prg.html</page> <page>pluggability.html</page> <page>binding.html</page> <page>validation.html</page> <page>lifecycle.html</page> <page>monitors.html</page> <page>ajax.html</page> + <page>file-upload.html</page> <page>webxml.html</page> <page>webapp-structure.html</page> </section>
To unsubscribe from this list please visit:
