From 6dbd864468feeddfe63ca0666e07eb7c4eecefd6 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Thu, 23 Aug 2018 10:41:13 +0300
Subject: [PATCH] Add some frontend docs

---
 doc/frontend/basics.md      | 11 ++++++++++-
 doc/frontend/browser.md     | 26 +++++++++++++++++++++++++-
 doc/frontend/controllers.md | 36 +++++++++++++++++++++++++++++++++++-
 3 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/doc/frontend/basics.md b/doc/frontend/basics.md
index 9f296057..af5a0acf 100644
--- a/doc/frontend/basics.md
+++ b/doc/frontend/basics.md
@@ -2,4 +2,13 @@
 
 * https://github.com/metosin/reitit/tree/master/examples/frontend
 
-**TODO**
+**WIP**
+
+`reitit.frontend` provides few useful functions wrapping core functions:
+
+- `match-by-path` version which parses a URI using JavaScript, including
+query-string, and also coerces the parameters.
+- `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).
diff --git a/doc/frontend/browser.md b/doc/frontend/browser.md
index a7a8c613..2181d64f 100644
--- a/doc/frontend/browser.md
+++ b/doc/frontend/browser.md
@@ -1,3 +1,27 @@
 # Frontend browser integration
 
-TODO
+**WIP**
+
+Reitit includes two browser history integrations.
+
+Functions follow HTML5 History API: `push-state` to change route, `replace-state`
+to change route without leaving previous entry in browser history.
+
+## Fragment router
+
+Fragment is simple integration which stores the current route in URL fragment,
+i.e. after `#`. This means the route is never part of the request URI and
+server will always know which file to return (`index.html`).
+
+## HTML5 router
+
+HTML5 History API can be used to modify the URL in browser without making
+request to the server. This means the URL will look normal, but the downside is
+that the server must respond to all routes with correct file (`index.html`).
+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
+router instance and passes the instance to all calls.
diff --git a/doc/frontend/controllers.md b/doc/frontend/controllers.md
index 40c3d35f..71e609e8 100644
--- a/doc/frontend/controllers.md
+++ b/doc/frontend/controllers.md
@@ -1,5 +1,39 @@
 # Controllers
 
+**WIP**
+
 * https://github.com/metosin/reitit/tree/master/examples/frontend-controllers
 
-**TODO**
+Controllers run code when a route is entered and left. This can be useful to:
+
+- Load resources
+- Update application state
+
+## 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
+
+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
+
+If all your resources require authentication an easy way to prevent bad
+requests is to enable controllers only after authentication is done.
+To do this you can check authentication status and call `apply-controllers`
+only after authentication is done (also remember to manually call `apply-controllers`
+with current `match` when authentication is done). Or if no navigation is possible
+before authentication is done, you can start the router only after
+authentication is done.
+
+## Alternatives
+
+Similar solution could be used to describe required resources as data (maybe
+even GraphQL query) per resource, and then have code automatically load
+missing resources.