rum.core — rum 0.11.3

cursor clj/s

(cursor ref key & options)

Same as cursor-in but accepts single key instead of path vector.

cursor-in clj/s

(cursor-in ref path & {:as options})

Given atom with deep nested value and path inside it, creates an atom-like structure that can be used separately from main atom, but will sync changes both ways:

(def db (atom { :users { "Ivan" { :age 30 }}}))

(def ivan (rum/cursor db [:users "Ivan"]))
(deref ivan) ;; => { :age 30 }

(swap! ivan update :age inc) ;; => { :age 31 }
(deref db) ;; => { :users { "Ivan" { :age 31 }}}

(swap! db update-in [:users "Ivan" :age] inc)
;; => { :users { "Ivan" { :age 32 }}}

(deref ivan) ;; => { :age 32 }

Returned value supports deref, swap!, reset!, watches and metadata.

The only supported option is :meta

defc clj/s macro

(defc & body)

(defc name doc-string? (< mixins+)? [ params* ] render-body+)

Defc does couple of things:

1. Wraps body into sablono/compile-html
2. Generates render function from that
3. Takes render function and mixins, builds React class from them
4. Using that class, generates constructor fn [args]->ReactElement
5. Defines top-level var with provided name and assigns ctor to it

Usage:

(rum/defc label < rum/static [t]
  [:div t])

;; creates React class
;; adds mixin rum/static
;; defines ctor fn (defn label [t] ...) => element

(label "text") ;; => returns React element built with label class

defcc clj/s macro

(defcc & body)

(defcc name doc-string? (< mixins+)? [ comp-arg params* ] render-body+)

Same as defc, but render will take additional first argument: react component.

defcs clj/s macro

(defcs & body)

(defcs name doc-string? (< mixins+)? [ state-arg params* ] render-body+)

Same as defc, but render will take additional first argument: component state.

derived-atom clj/s≠

(derived-atom refs key f)

(derived-atom refs key f opts)

clj

Use this to create “chains” and acyclic graphs of dependent atoms.

derived-atom will:

• Take N “source” refs.
• Set up a watch on each of them.
• Create “sink” atom.
• When any of source refs changes:
  • re-run function f, passing N dereferenced values of source refs.
  • reset! result of f to the sink atom.
• Return sink atom.

Example:

(def *a (atom 0))
(def *b (atom 1))
(def *x (derived-atom [*a *b] ::key
          (fn [a b]
            (str a ":" b))))

(type *x)  ;; => clojure.lang.Atom
(deref *x) ;; => "0:1"

(swap! *a inc)
(deref *x) ;; => "1:1"

(reset! *b 7)
(deref *x) ;; => "1:7"

Arguments:

• refs - sequence of source refs,
• key - unique key to register watcher, same as in clojure.core/add-watch,
• f - function that must accept N arguments (same as number of source refs) and return a value to be written to the sink ref. Note: f will be called with already dereferenced values,
• opts - optional. Map of:
  • :ref - use this as sink ref. By default creates new atom,
  • :check-equals? - Defaults to true. If equality check should be run on each source update: (= @sink (f new-vals)). When result of recalculating f equals to the old value, reset! won’t be called. Set to false if checking for equality can be expensive.

cljs

Use this to create “chains” and acyclic graphs of dependent atoms.

derived-atom will:

• Take N “source” refs.
• Set up a watch on each of them.
• Create “sink” atom.
• When any of source refs changes:
  • re-run function f, passing N dereferenced values of source refs.
  • reset! result of f to the sink atom.
• Return sink atom.

Example:

(def *a (atom 0))
(def *b (atom 1))
(def *x (derived-atom [*a *b] ::key
          (fn [a b]
            (str a ":" b))))

(type *x) ;; => clojure.lang.Atom
(deref *x) ;; => "0:1"

(swap! *a inc)
(deref *x) ;; => "1:1"

(reset! *b 7)
(deref *x) ;; => "1:7"

Arguments:

• refs - sequence of source refs,
• key - unique key to register watcher, same as in clojure.core/add-watch,
• f - function that must accept N arguments (same as number of source refs) and return a value to be written to the sink ref. Note: f will be called with already dereferenced values,
• opts - optional. Map of:
  • :ref - use this as sink ref. By default creates new atom,
  • :check-equals? - Defaults to true. If equality check should be run on each source update: (= @sink (f new-vals)). When result of recalculating f equals to the old value, reset! won’t be called. Set to false if checking for equality can be expensive.

dom-node cljs

(dom-node state)

Given state, returns top-level DOM node of component. Call it during lifecycle callbacks. Can’t be called during render.

hydrate cljs

(hydrate element node)

Same as mount but must be called on DOM tree already rendered by a server via render-html.

local clj/s

(local initial)

(local initial key)

Mixin constructor. Adds an atom to component’s state that can be used to keep stuff during component’s lifecycle. Component will be re-rendered if atom’s value changes. Atom is stored under user-provided key or under :rum/local by default.

(rum/defcs counter < (rum/local 0 :cnt)
  [state label]
  (let [*cnt (:cnt state)]
    [:div {:on-click (fn [_] (swap! *cnt inc))}
      label @*cnt]))

(rum/mount (counter "Click count: "))

mount cljs

(mount element node)

Add element to the DOM tree. Idempotent. Subsequent mounts will just update element.

portal cljs

(portal element node)

Render element in a DOM node that is ouside of current DOM hierarchy.

react clj/s≠

(react ref)

clj

Supported as simple deref.

cljs

Works in conjunction with reactive mixin. Use this function instead of deref inside render, and your component will subscribe to changes happening to the derefed atom.

reactive clj/s≠

clj

Supported, does nothing.

cljs

Mixin. Works in conjunction with react.

(rum/defc comp < rum/reactive
  [*counter]
  [:div (rum/react counter)])

(def *counter (atom 0))
(rum/mount (comp *counter) js/document.body)
(swap! *counter inc) ;; will force comp to re-render

ref cljs

(ref state key)

Given state and ref handle, returns React component.

ref-node cljs

(ref-node state key)

Given state and ref handle, returns DOM node associated with ref.

render-html clj

(render-html element)

(render-html element opts)

Main server-side rendering method. Given component, returns HTML string with static markup of that component. Serve that string to the browser and mount same Rum component over it. React will be able to reuse already existing DOM and will initialize much faster. No opts are supported at the moment.

render-static-markup clj

(render-static-markup element)

Same as render-html but returned string has nothing React-specific. This allows Rum to be used as traditional server-side templating engine.

request-render cljs

(request-render component)

Schedules react component to be rendered on next animation frame.

state cljs

(state comp)

Given React component, returns Rum state associated with it.

static clj/s≠

clj

Supported, does nothing.

cljs

Mixin. Will avoid re-render if none of component’s arguments have changed. Does equality check (=) on all arguments.

(rum/defc label < rum/static
  [text]
  [:div text])
  
(rum/mount (label "abc") js/document.body)

;; def != abc, will re-render
(rum/mount (label "def") js/document.body)

;; def == def, won’t re-render
(rum/mount (label "def") js/document.body)

unmount cljs

(unmount node)

Removes component from the DOM tree.

with-key clj/s

(with-key element key)

Adds React key to element.

(rum/defc label [text] [:div text])

(-> (label)
    (rum/with-key "abc")
    (rum/mount js/document.body))

with-ref clj/s≠

(with-ref element ref)

clj

Supported, does nothing.

cljs

Adds React ref (string or callback) to element.

(rum/defc label [text] [:div text])

(-> (label)
    (rum/with-ref "abc")
    (rum/mount js/document.body))