API.md

The re-frame API

Orientation:

1. The API is provided by re-frame.core:
   • at some point, it would be worth your time to browse it
   • to use re-frame, you'll need to require it, perhaps like this ...

   (ns  my.namespace
     (:require [re-frame.core :as rf]))
               
   ... now use rf/reg-event-fx or rf/subscribe

2. The API is small. Writing an app, you use less than 10 API functions. Maybe just 5.
3. There's no auto-generated docs because of this problem but, as a substitute, the links below take you to the doc-strings of often-used API functions.

Doc Strings For The Significant API Functions

The core API consists of:

• dispatch or dispatch-sync.
• reg-event-db or reg-event-fx
• reg-sub and subscribe working together

Occasionally, you'll need to use:

• reg-fx
• reg-cofx and inject-cofx working together

And, finally, there are the builtin Interceptors:

• path
• after
• debug
• and browse the others

Built-in Effect Handlers

The following built-in effects are also a part of the API:

:dispatch-later

dispatch one or more events after given delays. Expects a collection of maps with two keys: :ms and :dispatch

usage:

{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}    
                  {:ms 100 :dispatch [:also :this :in :100ms]}]}

Which means: in 200ms do this: (dispatch [:event-id "param"]) and in 100ms ...

Note: nil entries in the collection are ignored which means events can be added conditionally:

{:dispatch-later [ (when (> 3 5) {:ms 200 :dispatch [:conditioned-out]})
                   {:ms 100 :dispatch [:another-one]}]}

---

:dispatch

dispatch one event. Expects a single vector.

usage:

{:dispatch [:event-id "param"] }

---

:dispatch-n

dispatch more than one event. Expects a collection events.

usage:

{:dispatch-n (list [:do :all] [:three :of] [:these])}

Note 1: The events supplied will be dispatched in the order provided. Note 2: nil events are ignored which means events can be added conditionally:

{:dispatch-n (list (when (> 3 5) [:conditioned-out])
                   [:another-one])}

---

:deregister-event-handler

removes a previously registered event handler. Expects either a single id (typically a keyword), or a seq of ids.

usage:

{:deregister-event-handler :my-id)}

or:

{:deregister-event-handler [:one-id :another-id]}

---

:db

reset! app-db with a new value. Expects a map.

usage:

{:db  {:key1 value1 :key2 value2}}

---

Previous: Infographic: A re-frame Epoch       Up: Index       Next: Infographic: Event Processing