Merge pull request #8 from decebals/forms

Document form processing

Author: decebals

_posts/2015-06-01-forms.md

@@ -0,0 +1,97 @@
+---
+layout: page
+title: "Form Processing"
+category: doc
+date: 2015-06-01 10:11:42
+order: 55
+---
+
+### Cross-Site Request Forgery (CSRF) Protection
+
+See [Security](security.html).
+
+### Form Tricks
+
+Pippo supports several convenient tricks for making HTML form submission more useful in a RESTful world.
+
+#### Indexed Arrays
+
+You may POST Arrays, Lists, or Sets to your `RouteHandler` implementations by using `[n]` suffixes for your parameter names in your forms.
+
+```html
+<form>
+  <input name="rainbow[0]" value="Red">
+  <input name="rainbow[1]" value="Orange">
+  <input name="rainbow[2]" value="Yellow">
+  <input name="rainbow[3]" value="Green">
+  <input name="rainbow[4]" value="Blue">
+  <input name="rainbow[5]" value="Indigo">
+  <input name="rainbow[6]" value="Violet">
+</form>
+```
+
+In this example, Pippo will automatically collect the values into a parameter named *rainbow*.  The *rainbow* parameter may be accessed and transformed to a collection of your choice.
+
+```java
+POST("/rainbow", (routeContext) -> {
+  List<String> rainbowList = routeContext.getParameter("rainbow").toList(String.class);
+  Set<String> rainbowSet = routeContext.getParameter("rainbow").toSet(String.class);
+  TreeSet<String> rainbowTreeSet = routeContext.getParameter("rainbow").toCollection(TreeSet.class, String.class);
+}
+```
+
+Or if you are using Pippo controllers...
+
+```java
+public void postRainbow(@Param("rainbow") TreeSet<String> rainbow) {
+  // do something with the rainbow
+}
+```
+
+
+#### Browser-based PUT, PATCH, DELETE, etc
+
+Pippo supports overriding the `POST` method used to submit a form through the use of a hidden form field named `_method`.
+
+```html
+<form>
+  <input name="rainbow[3]" value="Gray">
+  <input type="hidden" name="_method" value="PATCH">
+</form>
+```
+
+Pippo will intercept the `_method` parameter specification and route the request to the `PATCH` handler that matches the URL pattern.
+
+```java
+PATCH("/rainbow", (routeContext) -> {
+  List<String> patched = routeContext.getParameter("rainbow").toList(String.class);
+  List<String> rainbow = dao.getRainbow();
+  for (int i = 0; i < patched.size(); i++) {
+    if (patched.get(i) != null) {
+      rainbow.set(i, patched.get(i));
+    }
+  }
+  dao.updateRainbow(rainbow);
+}
+```
+
+This allows you to develop a more RESTful design when handling form submissions.
+
+#### Browser-based submission of JSON or another format
+
+Pippo supports POSTing non-form content by specifying `_content_type` and `_content` hidden form fields.  When used in combination with the `_method` hidden form field you can exercise a RESTful api.
+
+```html
+<form>
+  <input type="hidden" name="_content" value="['Red', 'Orange', 'Yellow', 'Green', 'Blue', 'Indigo', 'Violet']">
+  <input type="hidden" name="_content_type" value="application/json">
+  <input type="hidden" name="_method" value="PUT">
+</form>
+```
+
+```java
+PUT("/rainbow", (routeContext) -> {
+  List<String> rainbow = routeContext.createEntityFromBody(List.class);
+});
+
+```