keechma.controller
Controllers in Keechma are the place where you put the code that has side-effects. They are managed by the keechma.controller-manager which will start them or stop them based on the current route.
Each controller implements the params function. params function returns a subset of the route params that are the controller is interested in.
For instance let’s say that you have a UserController which should be running only when the user is on the route /users:
;; let's say that your routes are defined like this:
(def routes [":page"]) ;; Routes are managed by the app-state library.
;; When user goes to the url `/users` the params function would receive
;; something that looks like this:
{:data {:page "users"}}
;; `params` function returns `true` only when user is on the `:page` "users"
(defrecord UserController [])
(defmethod controller/params UserController [_ route-params]
(when (= "users" (get-in route-params [:data :page]))
true))
When params function returns a non nil value the controller will be started:
- Controller’s
startfunction will be synchronously called with the current application state. This function returns a new version of the state if needed. (if thestartfunction is not doing any changes to the app-state it must return the received version) - Controller’s
handlerfunction will be called - this function will receive application state atom, channel through which the controller receives the commands (in-chan) and the channel through which the controller can send commends to other controllers (out-chan).
When params function returns a nil value that instance of the controller will be stopped:
- Controller’s
stopfunction will be synchronously called with the current application state. This function returns a new version of the state if needed - use this function to clean up any data loaded by the controller (if thestopfunction is not doing any changes to the app-state it must return the received version). - Controller’s
in-chan(through which it can receive commands) will be closed.
Controller’s start and stop functions can asynchronuously send commends to the controller. Calling (execute controller-instance :command) will put that command on the controller’s in-chan.
Controller can react to these commands from the handler function.
->SerializedController
(->SerializedController params)context
Return the context passed to the application.
dispatcher
(dispatcher app-db-atom in-chan actions)Helper function to dispatch commands from the handler function.
Most of the time, handler function will just dispatch the commands to other functions. This functions provides a shortcut for that case.
(defrecord Controller []
IController
(handler [_ app-db-atom in-chan _]
(dispatcher app-db-atom in-chan {:command-name some-fn})))
execute
Puts the command on the controller’s in-chan which is passed as an argument to the handler function. Can be called from the start and stop functions.
handler
Called after the start function. You can listen to the commands on the in-chan inside the go block. This is the function in which you implement anything that reacts to the user commands (coming
from the UI).
is-running?
Returns true if this controller is still running. You can use this if you have some kind of async action, and you want to make sure that the controller is still running when you receive the results.
map->SerializedController
(map->SerializedController G__14188)not-implemented
params
Receives the route-params and returns either the params for the controller or nil
record-type
(record-type record & args)redirect
Redirects the page to the URL based on the params.
report
send-command
Sends a command to another controller
SerializedController
ssr-handler
Called in after the start (instead of the handler function) function in the server side context. This function should call the done callback when it has completed the server side data loading.
Returning ::not-implemented which is a default behavior will mark the controller as non server side.
start
Called when the controller is started. Receives the controller params (returned by the params function) and the application state. It must return the application state.
stop
Called when the controller is stopped. Receives the controller params (returned by the params function) and the application state. It must return the application state.
wake
Called when the controller is started from the saved state stored on the server. It will be called instead of the start function if the ssr-handler function is implemented. This allows you to manually revive
the serialized data if needed. Usually this function is not needed, but if you for instance start the inner application from the controller, you can use this function to wake the inner app.