Improved frontend docs

doc/frontend/basics.md

@@ -1,12 +1,31 @@
 # Frontend basics
 
-* https://github.com/metosin/reitit/tree/master/examples/frontend
+Reitit frontend integration is built from multiple layers:
+
+- Core functions which are enchanted with few browser specific
+features
+- [Browser integration](./browser.md) for attaching Reitit to hash-change or HTML5
+history events
+- Stateful wrapper for easy use of history integration
+- Optional [controller extension](./controllers.md)
+
+## Core functions
 
 `reitit.frontend` provides few useful functions wrapping core functions:
 
-- `match-by-path` version which parses a URI using JavaScript, including
+`match-by-path` version which parses a URI using JavaScript, including
-query-string, and also coerces the parameters.
+query-string, and also [coerces the parameters](../coercion/coercion.md).
-- `router` which compiles coercers by default
+Coerced parameters are stored in match `:parameters` property. If coercion
-- `match-by-name` and `match-by-name!` with optional `path-paramers` and
+is not enabled, the original parameters are stored in the same property,
-logging errors to `console.warn` instead of throwing errors (to prevent
+to allow the same code to read parameters regardless if coercion is
-React breaking due to errors).
+enabled.
+
+`router` which compiles coercers by default.
+
+`match-by-name` and `match-by-name!` with optional `path-paramers` and
+logging errors to `console.warn` instead of throwing errors to prevent
+React breaking due to errors.
+
+## Next
+
+[Browser integration](./browser.md)

doc/frontend/browser.md

@@ -21,5 +21,7 @@ Check examples for simple Ring handler example.
 ## Easy
 
 Reitit frontend routers require storing the state somewhere and passing it to
-all the calls. Wrapper (`reitit.frontend.easy`) is provided which manages
+all the calls. Wrapper `reitit.frontend.easy` is provided which manages
-router instance and passes the instance to all calls.
+a router instance and passes the instance to all calls. This should
+allow easy use in most applications, as browser anyway can only have single
+event handler for page change events.

doc/frontend/controllers.md

@@ -26,7 +26,7 @@ and `start` get called again.
 You can add controllers to a route by adding them to the route data in the
 `:controllers` vector. For example:
 
-```clojure
+```cljs
 ["/item/:id"
  {:controllers [{:params (fn [match] (get-in match [:path-params :id]))
                  :start  (fn [item-id] (js/console.log :start item-id))
@@ -44,8 +44,7 @@ call
 the URL changes. You can call it from the `on-navigate` callback of
 `reitit.frontend.easy`:
 
-```clojure
+```cljs
-
 (ns frontend.core
   (:require [reitit.frontend.easy :as rfe]
             [reitit.frontend.controllers :as rfc]))
@@ -70,10 +69,10 @@ See also [the full example](https://github.com/metosin/reitit/tree/master/exampl
 
 ## Nested controllers
 
-When you nest routes in the route tree, the controllers get nested as well.
+When you nest routes in the route tree, the controllers get concatenated when
-Consider this route tree:
+route data is merged. Consider this route tree:
 
-```clojure
+```cljs
 ["/" {:controllers [{:start (fn [_] (js/console.log "root start"))}]}
  ["/item/:id"
   {:controllers [{:params (fn [match] (get-in match [:path-params :id]))
@@ -90,20 +89,22 @@ Consider this route tree:
   started with the parameter `something-else`. The root controller stays on the
   whole time since its parameters do not change.
 
-## Authentication
+## Tips
+
+### Authentication
 
 Controllers can be used to load resources from a server. If and when your
 API requires authentication you will need to implement logic to prevent controllers
 trying to do requests if user isn't authenticated yet.
 
-### Run controllers and check authentication
+#### Run controllers and check authentication
 
 If you have both unauthenticated and authenticated resources, you can
 run the controllers always and then check the authentication status
 on controller code, or on the code called from controllers (e.g. re-frame event
 handler).
 
-### Disable controllers until user is authenticated
+#### Disable controllers until user is authenticated
 
 If all your resources require authentication an easy way to prevent bad
 requests is to enable controllers only after authentication is done.
@@ -119,7 +120,6 @@ Similar solution could be used to describe required resources as data (maybe
 even GraphQL query) per route, and then have code automatically load
 missing resources.
 
-
 ## Controllers elsewhere
 
 * [Controllers in Keechma](https://keechma.com/guides/controllers/)