Liking cljdoc? Tell your friends :D

rum.core


cursor

(cursor ref key & options)

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

Same as [[cursor-in]] but accepts single key instead of path vector.
source (clj)source (cljs)raw docstring

cursor-in

(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

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`
source (clj)source (cljs)raw docstring

defcmacro

(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
```
(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
```
sourceraw docstring

defccmacro

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

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

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

Same as [[defc]], but render will take additional first argument: react component.
sourceraw docstring

defcsmacro

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

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

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

Same as [[defc]], but render will take additional first argument: component state.
sourceraw docstring

derived-atom

(derived-atom refs key f)
(derived-atom refs key f opts)
cljClojure

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

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.
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.
source (clj)source (cljs)raw docstring

dom-node

(dom-node state)

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

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

hydrate

(hydrate element node)

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

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

local

(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: "))
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: "))
```
source (clj)source (cljs)raw docstring

mount

(mount element node)

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

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

portal

(portal element node)

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

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

react

(react ref)
cljClojure

Supported as simple deref.

Supported as simple deref.
cljsClojureScript

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.

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.
source (clj)source (cljs)raw docstring

reactive

cljClojure

Supported, does nothing.

Supported, does nothing.
cljsClojureScript

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
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
```
source (clj)source (cljs)raw docstring

ref

(ref state key)

Given state and ref handle, returns React component.

Given state and ref handle, returns React component.
sourceraw docstring

ref-node

(ref-node state key)

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

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

render-html

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

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

render-static-markup

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

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

request-render

(request-render component)

Schedules react component to be rendered on next animation frame.

Schedules react component to be rendered on next animation frame.
sourceraw docstring

state

(state comp)

Given React component, returns Rum state associated with it.

Given React component, returns Rum state associated with it.
sourceraw docstring

static

cljClojure

Supported, does nothing.

Supported, does nothing.
cljsClojureScript

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)
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)
```
source (clj)source (cljs)raw docstring

unmount

(unmount node)

Removes component from the DOM tree.

Removes component from the DOM tree.
sourceraw docstring

with-key

(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))
Adds React key to element.

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

(-> (label)
    (rum/with-key "abc")
    (rum/mount js/document.body))
```
source (clj)source (cljs)raw docstring

with-ref

(with-ref element ref)
cljClojure

Supported, does nothing.

Supported, does nothing.
cljsClojureScript

Adds React ref (string or callback) to element.

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

(-> (label)
    (rum/with-ref "abc")
    (rum/mount js/document.body))
Adds React ref (string or callback) to element.

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

(-> (label)
    (rum/with-ref "abc")
    (rum/mount js/document.body))
```
source (clj)source (cljs)raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close