139 lines
5.0 KiB
Markdown
139 lines
5.0 KiB
Markdown
## Talking To Servers
|
|
|
|
This page describes how a re-frame app might "talk" to a backend HTTP server.
|
|
|
|
We'll assume there's a json-returning server endpoint
|
|
at "http://json.my-endpoint.com/blah". We want to GET from that
|
|
endpoint and put a processed version of the returned json into `app-db`.
|
|
|
|
## Triggering The Request
|
|
|
|
The user often does something to trigger the process.
|
|
|
|
Here's a button which the user could click:
|
|
```clj
|
|
(defn request-it-button
|
|
[]
|
|
[:div {:class "button-class"
|
|
:on-click #(dispatch [:request-it])} ;; get data from the server !!
|
|
"I want it, now!"])
|
|
```
|
|
|
|
Notice the `on-click` handler - it `dispatch`es the event `[:request-it]`.
|
|
|
|
## The Event Handler
|
|
|
|
That `:request-it` event will need to be "handled", which means an event handler must be registered for it.
|
|
|
|
We want this handler to:
|
|
1. Initiate the HTTP GET
|
|
2. Update a flag in `app-db` which will trigger a modal "Loading ..." message for the user to see
|
|
|
|
We're going to create two versions of this event handler. First, we'll create a
|
|
problematic version of the event handler and then, realising our sins, we'll writes
|
|
a second version which is a soaring paragon of virtue. Both versions
|
|
will teach us something.
|
|
|
|
|
|
### Version 1
|
|
|
|
We're going to use the [cljs-ajax library](https://github.com/JulianBirch/cljs-ajax) as the HTTP workhorse.
|
|
|
|
Here's the event handler:
|
|
```clj
|
|
(ns my.app.events ;; <1>
|
|
(:require [ajax.core :refer [GET]]
|
|
[re-frame.core :refer [re-event-db]))
|
|
|
|
(reg-event-db ;; <-- register an event handler
|
|
:request-it ;; <-- the event id
|
|
(fn ;; <-- the handler function
|
|
[db _]
|
|
|
|
;; kick off the GET, making sure to supply a callback for success and failure
|
|
(GET
|
|
"http://json.my-endpoint.com/blah"
|
|
{:handler #(dispatch [:process-response %1]) ;; <2> further dispatch !!
|
|
:error-handler #(dispatch [:bad-response %1])}) ;; <2> further dispatch !!
|
|
|
|
;; update a flag in `app-db` ... presumably to cause a "Loading..." UI
|
|
(assoc db :loading? true))) ;; <3> return an updated db
|
|
```
|
|
|
|
Further Notes:
|
|
1. Event handlers are normally put into an `events.cljs` namespace
|
|
2. Notice that the GET callbacks issue a further `dispatch`. Such callbacks
|
|
should never attempt to close over `db` themselves, or make
|
|
any changes to it because, by the time these callbacks happen, the value
|
|
in `app-db` may have changed. Whereas, if they `dispatch`, then the event
|
|
handlers looking after the event they dispatch will be given the latest copy of the db.
|
|
3. event handlers registered using `reg-event-db` must return a new value for
|
|
`app-db`. In our case, we set a flag which will presumably cause a "Loading ..."
|
|
UI to show.
|
|
|
|
### Successful GET
|
|
|
|
As we noted above, the on-success handler itself is just
|
|
`(dispatch [:process-response RESPONSE])`. So we'll need to register a handler
|
|
for this event too.
|
|
|
|
Like this:
|
|
```clj
|
|
(reg-event-db
|
|
:process-response
|
|
(fn
|
|
[db [_ response]] ;; destructure the response from the event vector
|
|
(-> db
|
|
(assoc :loading? false) ;; take away that "Loading ..." UI
|
|
(assoc :data (js->clj response)))) ;; fairly lame processing
|
|
```
|
|
|
|
A normal handler would have more complex processing of the response. But we're
|
|
just sketching here, so we've left it easy.
|
|
|
|
There'd also need to be a handler for the `:bad-response` event too. Left as an exercise.
|
|
|
|
### Problems In Paradise?
|
|
|
|
This approach will work, and it is useful to take time to understand why it
|
|
would work, but it has a problem: the event handler isn't pure.
|
|
|
|
That `GET` is a side effect, and side effecting functions are like a
|
|
well salted paper cut. We try hard to avoid them.
|
|
|
|
### Version 2
|
|
|
|
The better solution is, of course, to use an effectful handler. This
|
|
is explained in detail in the previous tutorials: [Effectful Handlers](EffectfulHandler.md)
|
|
and [Effects](Effects.md).
|
|
|
|
We use the alternative registration function, `reg-event-fx` , and we'll use an
|
|
"Effect Handler" supplied by this library
|
|
[https://github.com/Day8/re-frame-http-fx](https://github.com/Day8/re-frame-http-fx).
|
|
You may soon feel confident enough to write your own.
|
|
|
|
Here's our rewrite:
|
|
```clj
|
|
(ns my.app.events
|
|
(:require
|
|
[day8.re-frame.http-fx]
|
|
[re-frame.core :refer [re-event-fx]))
|
|
|
|
(reg-event-fx ;; <-- note the `-fx` extension
|
|
:request-it ;; <-- the event id
|
|
(fn ;; <-- the handler function
|
|
[{db :db} _] ;; <-- 1st argument is coeffect, from which we extract db
|
|
|
|
;; we return a map of (side) effects
|
|
{:http-xhrio {:method :get
|
|
:uri "http://json.my-endpoint.com/blah"
|
|
:on-success [:process-response]
|
|
:on-failure [:bad-response]}
|
|
:db (assoc db :loading? true)}))
|
|
```
|
|
|
|
Notes:
|
|
1. Our event handler to "describe" a side effect, rather than to "do" the side effect
|
|
2. The event handler for `:process-response` stays as it was.
|
|
|