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
start
function will be synchronously called with the current application state. This function returns a new version of the state if needed. (if thestart
function is not doing any changes to the app-state it must return the received version) - Controller’s
handler
function 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
stop
function 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 thestop
function 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.