re-frame/docs/API.md

3.4 KiB

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:

Occasionally, you'll need to use:

And, finally, there are the builtin Interceptors:

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 ...


: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