adding form examples

src/docs/cookbook/html_forms/example_lens.kt

@@ -0,0 +1,51 @@
+package cookbook.html_forms
+
+import org.http4k.core.Body
+import org.http4k.core.ContentType
+import org.http4k.core.Method
+import org.http4k.core.Request
+import org.http4k.core.with
+import org.http4k.lens.FormField
+import org.http4k.lens.FormValidator
+import org.http4k.lens.Header
+import org.http4k.lens.LensFailure
+import org.http4k.lens.WebForm
+import org.http4k.lens.int
+import org.http4k.lens.webForm
+
+data class Name(val value: String)
+
+fun main(args: Array<String>) {
+
+    // define fields using the standard lens syntax
+    val ageField = FormField.int().required("age")
+    val nameField = FormField.map(::Name, Name::value).optional("name")
+
+    // add fields to a form definition, along with a validator
+    val strictFormBody = Body.webForm(FormValidator.Strict, nameField, ageField).toLens()
+    val feedbackFormBody = Body.webForm(FormValidator.Feedback, nameField, ageField).toLens()
+
+    val invalidRequest = Request(Method.GET, "/")
+        .with(Header.Common.CONTENT_TYPE of ContentType.APPLICATION_FORM_URLENCODED)
+
+    // the "strict" form rejects (throws a LensFailure) because "age" is required
+    try {
+        strictFormBody.extract(invalidRequest)
+    } catch (e: LensFailure) {
+        println(e.message)
+    }
+
+    // the "feedback" form doesn't throw, but collects errors to be reported later
+    val invalidForm = feedbackFormBody.extract(invalidRequest)
+    println(invalidForm.errors)
+
+    // creating valid form using "with()" and setting it onto the request
+    val webForm = WebForm().with(ageField of 55, nameField of Name("rita"))
+    val validRequest = Request(Method.GET, "/").with(strictFormBody of webForm)
+
+    // to extract the contents, we first extract the form and then extract the fields from it using the lenses
+    val validForm = strictFormBody.extract(validRequest)
+    val age = ageField.extract(validForm)
+    println(age)
+
+}

src/docs/cookbook/html_forms/example_standard.kt

@@ -0,0 +1,13 @@
+package cookbook.html_forms
+
+import org.http4k.core.Method
+import org.http4k.core.Request
+import org.http4k.core.body.form
+
+fun main(args: Array<String>) {
+
+    val request = Request(Method.GET, "/").form("name", "rita").form("age", "55")
+
+    println(request.form("name"))
+    println(request.form("age"))
+}

src/docs/cookbook/html_forms/index.md

@@ -0,0 +1,15 @@
+HTML form support is provided on 2 levels:
+
+1. Through the use of `form()` extension methods on `Request` to get/set String values.
+1. Using the Lens system, which adds the facility to define form fields in a typesafe way, and to validate form contents (in either a strict (400) or "feedback" mode).
+
+### Gradle setup
+```
+    compile group: "org.http4k", name: "http4k-core", version: "2.28.0"
+```
+
+### Standard (non-typesafe) API
+<script src="https://gist-it.appspot.com/https://github.com/http4k/http4k/blob/master/src/docs/cookbook/html_forms/example_standard.kt"></script>
+
+### Lens (typesafe, validating) API
+<script src="https://gist-it.appspot.com/https://github.com/http4k/http4k/blob/master/src/docs/cookbook/html_forms/example_lens.kt"></script>

src/docs/guide/modules/core/index.md

@@ -139,8 +139,7 @@ val handler = routes(
 val app = ServerFilters.CatchLensFailure.then(handler(Request(Method.GET, "/hello/2000-01-01?myCustomType=someValue")))
 //With the addition of the `CatchLensFailure` filter, no other validation is required when using Lenses, as **http4k** will handle invalid requests by returning a BAD_REQUEST (400) response.
 
-//More convieniently for construction of HTTP messages, multiple lenses can be used at once to modify a message, which is useful for properly building both requests and responses in a typesafe way without resorting to string values (especially in 
-URLs which should never be constructed using String concatenation):
+//More conveniently for construction of HTTP messages, multiple lenses can be used at once to modify a message, which is useful for properly building both requests and responses in a typesafe way without resorting to string values (especially in URLs which should never be constructed using String concatenation):
 
 val modifiedRequest: Request = Request(Method.GET, "http://google.com/{pathLocalDate}").with(
     pathLocalDate of LocalDate.now(),

src/mkdocs.yml

@@ -52,9 +52,10 @@ pages:
     - Using JSON: cookbook/using_json/index.md
     - Using templates: cookbook/using_templates/index.md
     - Using typesafe RequestContexts: cookbook/request_context/index.md
+    - Typesafe HTTP requests with lenses: cookbook/typesafe_http_requests_with_lenses/index.md
+    - HTML forms: cookbook/html_forms/index.md
     - Generating data classes from JSON: cookbook/generating_data_classes_from_json/index.md
     - Typesafe HTTP contracts: cookbook/typesafe_http_contracts/index.md
-    - Typesafe HTTP requests with lenses: cookbook/typesafe_http_requests_with_lenses/index.md
     - Test driven apps: cookbook/test_driven_apps/index.md
   - Performance: performance/index.md
   - In action: in_action/index.md