Exceptions indicated.
- declare-mutation
- default-result-action!
- defmutation
- defmutation*clj
- dispatch-ok-error-actions!
- integrate-mutation-return-value!
- mutate
- mutation-declaration?
- mutation-symbol
- raw-set-value!
- raw-update-value!
- returning
- rewrite-tempids!
- set-double!
- set-double!!
- set-integer!
- set-integer!!
- set-props
- set-string!
- set-string!!
- set-value!
- set-value!!
- toggle
- toggle!
- toggle!!
- trigger-global-error-action!
- update-errors-on-ui-component!
- with-params
- with-response-type
- with-server-side-mutation
- with-target
com.fulcrologic.fulcro.mutations
Mutations are the central mechanism of getting things done in Fulcro. The term mutation refers to two things:
- The literal data that stands for the operation. These are lists with a single symbol and a map of parameters. In
earlier version, you had to quote them:
'[(f {:x 1})], but Fulcro 3 includes a way to declare them so that they auto-quote themselves for convenience. This can be confusing to new users. Remember that a mutation call is nothing more than a submission of this data viacomp/transact!(i.e. callfwith the parameter{:x 1}). - One or more definitions of what to do when the mutation is requested.
The former are submitted with transact! and can be written like so:
;; The unquote on the parameters is typically needed because you'll use surrounding binding values in them.
(let [x 3
some-local-value 42]
(comp/transact! this `[(f ~{:x x}) (g ~{:y some-local-value})]))
;; or, if pre-declared and required:
(let [x 3
some-local-value 42]
(comp/transact! this [(f {:x x}) (g {:y some-local-value})]))
This works because a mutation definition actually builds a record that response to function calls. This means
(defn func [x] (inc x))
(defmutation f [params] ...)
;; A regular function runs when called...
(func 3)
;; => 4
;; A mutation simply returns its expression when called:
(f {:x 1})
;; => (f {:x 1})
This allows you to embed a mutation expression without quoting in your calls to transact (if desired) or with quoting if you have something like a circular reference problem.
See the Developer's Guide for more information.
Mutations are the central mechanism of getting things done in Fulcro. The term mutation refers to two things:
* The literal data that stands for the operation. These are lists with a single symbol and a map of parameters. In
earlier version, you had to quote them: `'[(f {:x 1})]`, but Fulcro 3 includes a way to declare them so that they
auto-quote themselves for convenience. This can be confusing to new users. Remember that a mutation call is nothing
more than a *submission* of this data via `comp/transact!` (i.e. call `f` with the parameter `{:x 1}`).
* One or more definitions of what to do when the mutation is requested.
The former are submitted with `transact!` and can be written like so:
```
;; The unquote on the parameters is typically needed because you'll use surrounding binding values in them.
(let [x 3
some-local-value 42]
(comp/transact! this `[(f ~{:x x}) (g ~{:y some-local-value})]))
;; or, if pre-declared and required:
(let [x 3
some-local-value 42]
(comp/transact! this [(f {:x x}) (g {:y some-local-value})]))
```
This works because a mutation *definition* actually builds a record that response to function calls. This means
```
(defn func [x] (inc x))
(defmutation f [params] ...)
;; A regular function runs when called...
(func 3)
;; => 4
;; A mutation simply returns its expression when called:
(f {:x 1})
;; => (f {:x 1})
```
This allows you to embed a mutation expression without quoting in your calls to transact (if desired) or with
quoting if you have something like a circular reference problem.
See the Developer's Guide for more information.
declare-mutationclj/smacro
(declare-mutation name target-symbol)Define a quote-free interface for using the given target-symbol in mutations.
The declared mutation can be used in lieu of the true mutation symbol
as a way to prevent circular references while also allowing the shorthand of ns aliasing.
In IntelliJ, use Resolve-as def to get proper IDE integration.
Define a quote-free interface for using the given `target-symbol` in mutations. The declared mutation can be used in lieu of the true mutation symbol as a way to prevent circular references while also allowing the shorthand of ns aliasing. In IntelliJ, use Resolve-as `def` to get proper IDE integration.
default-result-action!clj/s
(default-result-action! env)The default Fulcro result action for defmutation, which can be overridden when you create your app/fulcro-app.
This function is the following composition of operations from this same namespace:
(-> env
(update-errors-on-ui-component! ::mutation-error)
(integrate-mutation-return-value!)
(trigger-global-error-action!)
(dispatch-ok-error-actions!))
This function returns env, so it can be used as part of the chain in your own definition of a "default"
mutation result action.
The default Fulcro result action for `defmutation`, which can be overridden when you create your `app/fulcro-app`.
This function is the following composition of operations from this same namespace:
```
(-> env
(update-errors-on-ui-component! ::mutation-error)
(integrate-mutation-return-value!)
(trigger-global-error-action!)
(dispatch-ok-error-actions!))
```
This function returns `env`, so it can be used as part of the chain in your own definition of a "default"
mutation result action.
defmutationclj/smacro
(defmutation & args)Define a Fulcro mutation.
The given symbol will be prefixed with the namespace of the current namespace, and if you use a simple symbol it will also be def'd into a name that when used as a function will simply resolve to that function call as data:
(defmutation f [p]
...)
(f {:x 1}) => `(f {:x 1})
This allows mutations to behave as data in transactions without needing quoting.
Mutations can have any number of handlers. By convention things that contain logic use names that end
in action. The remote behavior of a mutation is defined by naming a handler after the remote.
(defmutation boo
"docstring" [params-map]
(action [env] ...)
(my-remote [env] ...)
(other-remote [env] ...)
(remote [env] ...))
NOTE: Every handler in the defmutation is turned into a lambda, and that lambda will be available in env under
the key :handlers. Thus actions and remotes can cross-call (TODO: Make the macro rewrite cross calls so they
can look like fn calls?):
(defmutation boo
"docstring" [params-map]
(action [env] ...)
(ok-action [env] ...)
(error-action [env] ...)
(result-action [env] ((-> env :handlers :ok-action) env)))
This macro normally adds a :result-action handler that does normal Fulcro mutation remote result logic unless
you supply your own. The default result-action ends up invoking either ok-action or error-action.
Remotes in Fulcro 3 are also lambdas, and are called with an env that contains the state as it exists after
the :action has run in state, but also include the 'before action state' as a map in :state-before-action.
IMPORTANT: You can fully-qualify a mutation's symbol when declaring it to force it into a custom namespace, but this is highly discouraged and will require quoting when used in a mutation.
Define a Fulcro mutation.
The given symbol will be prefixed with the namespace of the current namespace, and if you use a simple symbol it
will also be def'd into a name that when used as a function will simply resolve to that function call as data:
```
(defmutation f [p]
...)
(f {:x 1}) => `(f {:x 1})
```
This allows mutations to behave as data in transactions without needing quoting.
Mutations can have any number of handlers. By convention things that contain logic use names that end
in `action`. The remote behavior of a mutation is defined by naming a handler after the remote.
```
(defmutation boo
"docstring" [params-map]
(action [env] ...)
(my-remote [env] ...)
(other-remote [env] ...)
(remote [env] ...))
```
NOTE: Every handler in the defmutation is turned into a lambda, and that lambda will be available in `env` under
the key `:handlers`. Thus actions and remotes can cross-call (TODO: Make the macro rewrite cross calls so they
can look like fn calls?):
```
(defmutation boo
"docstring" [params-map]
(action [env] ...)
(ok-action [env] ...)
(error-action [env] ...)
(result-action [env] ((-> env :handlers :ok-action) env)))
```
This macro normally adds a `:result-action` handler that does normal Fulcro mutation remote result logic unless
you supply your own. The default result-action ends up invoking either `ok-action` or `error-action`.
Remotes in Fulcro 3 are also lambdas, and are called with an `env` that contains the state as it exists *after*
the `:action` has run in `state`, but also include the 'before action state' as a map in `:state-before-action`.
IMPORTANT: You can fully-qualify a mutation's symbol when declaring it to force it into a custom namespace,
but this is highly discouraged and will require quoting when used in a mutation.
dispatch-ok-error-actions!clj/s
(dispatch-ok-error-actions! env)Looks for network mutation result in env, checks it against the global definition of remote errors. If there
is an error and the mutation has defined an error-action section, then it calls it; otherwise, if the mutation
has an ok-action it calls that.
Typically used as part of the construction of a global default result handler for mutations.
Returns env.
Looks for network mutation result in `env`, checks it against the global definition of remote errors. If there is an error and the mutation has defined an `error-action` section, then it calls it; otherwise, if the mutation has an `ok-action` it calls that. Typically used as part of the construction of a global default result handler for mutations. Returns env.
integrate-mutation-return-value!clj/s
(integrate-mutation-return-value! env)If there is a successful result from the remote mutation in env this function will merge it with app state
(if there was a mutation join query), and will also rewrite any tempid remaps that were returned
in all of the possible locations they might be in both app database and runtime application state (e.g. network queues).
Typically used as part of the construction of a global default result handler for mutations.
Returns env.
If there is a successful result from the remote mutation in `env` this function will merge it with app state (if there was a mutation join query), and will also rewrite any tempid remaps that were returned in all of the possible locations they might be in both app database and runtime application state (e.g. network queues). Typically used as part of the construction of a global default result handler for mutations. Returns env.
mutation-symbolclj/s
(mutation-symbol mutation)Return the real symbol (for mutation dispatch) of mutation, which can be a symbol (this function is then identity)
or a mutation-declaration.
Return the real symbol (for mutation dispatch) of `mutation`, which can be a symbol (this function is then identity) or a mutation-declaration.
raw-set-value!clj/s
(raw-set-value! app current-props k v)Run a transaction that will update the given k/v pair in the props of the database. Uses the current-props to
derive the ident of the database entry. The props must contain an ID key that can be used to derive the ident from
the current-props.
For example, (raw-set-value! app {:person/id 42} :person/name "bob") would have the effect of a mutation that
does an (assoc-in state-db [:person/id 42 :person/name] "bob").
Run a transaction that will update the given k/v pair in the props of the database. Uses the `current-props` to
derive the ident of the database entry. The props must contain an ID key that can be used to derive the ident from
the current-props.
For example, `(raw-set-value! app {:person/id 42} :person/name "bob")` would have the effect of a mutation that
does an `(assoc-in state-db [:person/id 42 :person/name] "bob")`.
raw-update-value!clj/s
(raw-update-value! app current-props k f & args)Run a transaction that will update the given k/v pair in the props of the database. Uses the current-props as the basis
for the update, and to find the ident of the target. The current-props must contain an ID field that can be used to derive
the ident from the passed props.
For example, (raw-update-value! app {:person/id 42} :person/age inc) would have the effect of a mutation that
does an (update-in state-db [:person/id 42 :person/age] inc).
Run a transaction that will update the given k/v pair in the props of the database. Uses the `current-props` as the basis
for the update, and to find the ident of the target. The `current-props` must contain an ID field that can be used to derive
the ident from the passed props.
For example, `(raw-update-value! app {:person/id 42} :person/age inc)` would have the effect of a mutation that
does an `(update-in state-db [:person/id 42 :person/age] inc)`.
returningclj/s
(returning env class)(returning env class {:keys [query-params] :as opts})Indicate the the remote operation will return a value of the given component type.
env - The env of the mutation
class - A component class that represents the return type. You may supply a fully-qualified symbol instead of the
actual class, and this method will look up the class for you (useful to avoid circular references).
opts (optional):
query-params- Optional parameters to add to the generated query
Returns an update env, and is a valid return value from mutation remote sections.
Indicate the the remote operation will return a value of the given component type. `env` - The env of the mutation `class` - A component class that represents the return type. You may supply a fully-qualified symbol instead of the actual class, and this method will look up the class for you (useful to avoid circular references). `opts` (optional): - `query-params` - Optional parameters to add to the generated query Returns an update `env`, and is a valid return value from mutation remote sections.
rewrite-tempids!clj/s
(rewrite-tempids! env)Rewrites tempids in state and places a tempid->realid map into env for further use by the mutation actions.
Rewrites tempids in state and places a tempid->realid map into env for further use by the mutation actions.
set-double!clj/s
(set-double! component field & {:keys [event value]})Set the given double on the given field of a component. Allows same parameters as set-string!.
It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
Set the given double on the given `field` of a `component`. Allows same parameters as `set-string!`. It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
set-double!!clj/s
(set-double!! component field & {:keys [event value]})Just like set-double!, but synchronously refreshes component and nothing else.
Just like set-double!, but synchronously refreshes `component` and nothing else.
set-integer!clj/s
(set-integer! component field & {:keys [event value]})Set the given integer on the given field of a component. Allows same parameters as set-string!.
It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
Set the given integer on the given `field` of a `component`. Allows same parameters as `set-string!`. It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
set-integer!!clj/s
(set-integer!! component field & {:keys [event value]})Just like set-integer!, but synchronously refreshes component and nothing else.
Just like set-integer!, but synchronously refreshes `component` and nothing else.
set-propsclj/s
Mutation: A convenience helper, generally used 'bit twiddle' the data on a particular database table (using the component's ident).
Specifically, merge the given params into the state of the database object at the component's ident.
In general, it is recommended this be used for ui-only properties that have no real use outside of the component.
Mutation: A convenience helper, generally used 'bit twiddle' the data on a particular database table (using the component's ident). Specifically, merge the given `params` into the state of the database object at the component's ident. In general, it is recommended this be used for ui-only properties that have no real use outside of the component.
set-string!clj/s
(set-string! component field & {:keys [event value]})Set a string on the given field of a component. The string can be literal via named parameter :value or
can be auto-extracted from a UI event using the named parameter :event
Examples
(set-string! this :ui/name :value "Hello") ; set from literal (or var)
(set-string! this :ui/name :event evt) ; extract from UI event target value
It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
Set a string on the given `field` of a `component`. The string can be literal via named parameter `:value` or can be auto-extracted from a UI event using the named parameter `:event` Examples ``` (set-string! this :ui/name :value "Hello") ; set from literal (or var) (set-string! this :ui/name :event evt) ; extract from UI event target value ``` It is recommended you use this function only on UI-related data (e.g. data that is used for display purposes) and write clear top-level transactions for anything else. Calls to this are compressed in history.
set-string!!clj/s
(set-string!! component field & {:keys [event value]})Just like set-string!, but synchronously refreshes component and nothing else.
Just like set-string!, but synchronously refreshes `component` and nothing else.
set-value!clj/s
(set-value! component field value)Set a raw value on the given field of a component. It is recommended you use this function only on
UI-related data (e.g. form inputs that are used by the UI, and not persisted data). Changes made via these
helpers are compressed in the history.
Set a raw value on the given `field` of a `component`. It is recommended you use this function only on UI-related data (e.g. form inputs that are used by the UI, and not persisted data). Changes made via these helpers are compressed in the history.
set-value!!clj/s
(set-value!! component field value)Just like set-value!, but synchronously updates component and nothing else.
Just like set-value!, but synchronously updates `component` and nothing else.
toggleclj/s
Mutation: A helper method that toggles the true/false nature of a component's state by ident. Use for local UI data only. Use your own mutations for things that have a good abstract meaning.
Mutation: A helper method that toggles the true/false nature of a component's state by ident. Use for local UI data only. Use your own mutations for things that have a good abstract meaning.
toggle!clj/s
(toggle! comp field)Toggle the given boolean field on the specified component. It is recommended you use this function only on
UI-related data (e.g. form checkbox checked status) and write clear top-level transactions for anything more complicated.
Toggle the given boolean `field` on the specified component. It is recommended you use this function only on UI-related data (e.g. form checkbox checked status) and write clear top-level transactions for anything more complicated.
toggle!!clj/s
(toggle!! comp field)Like toggle!, but synchronously refreshes comp and nothing else.
Like toggle!, but synchronously refreshes `comp` and nothing else.
trigger-global-error-action!clj/s
(trigger-global-error-action! env)When there is a global-error-action defined on the application, this function will checks for errors in the given
mutation env. If any are found then it will call the global error action function with env.
Typically used as part of the construction of a global default result handler for mutations.
Always returns env.
When there is a `global-error-action` defined on the application, this function will checks for errors in the given mutation `env`. If any are found then it will call the global error action function with `env`. Typically used as part of the construction of a global default result handler for mutations. Always returns `env`.
update-errors-on-ui-component!clj/s
(update-errors-on-ui-component! env)(update-errors-on-ui-component! env k)A handler for mutation network results that will place an error, if detected in env, on the data at ref.
Errors are placed at k (defaults to ::m/mutation-error).
Typically used as part of the construction of a global default result handler for mutations.
Swaps against app state and returns env.
A handler for mutation network results that will place an error, if detected in env, on the data at `ref`. Errors are placed at `k` (defaults to `::m/mutation-error`). Typically used as part of the construction of a global default result handler for mutations. Swaps against app state and returns `env`.
with-paramsclj/s
(with-params env params)Modify an AST containing a single mutation, changing it's parameters to those given as an argument. Overwrites any existing params of the mutation.
env - the mutation environment
params - A new map to use as the mutations parameters
Returns an updated env, which can be used as the return value from a remote section of a mutation.
Modify an AST containing a single mutation, changing it's parameters to those given as an argument. Overwrites any existing params of the mutation. `env` - the mutation environment `params` - A new map to use as the mutations parameters Returns an updated `env`, which can be used as the return value from a remote section of a mutation.
with-response-typeclj/s
(with-response-type env response-type)Modify the AST in env so that the request is sent such that an alternate low-level XHRIO response type is used. Only works with HTTP remotes. See goog.net.XhrIO. Supported response types are :default, :array-buffer, :text, and :document.
Modify the AST in env so that the request is sent such that an alternate low-level XHRIO response type is used. Only works with HTTP remotes. See goog.net.XhrIO. Supported response types are :default, :array-buffer, :text, and :document.
with-targetclj/s
(with-target {:keys [ast] :as env} target)Set's a target for the return value from the mutation to be merged into. This can be combined with returning to define a path to insert the new entry.
env - The mutation env (you can thread together returning and with-target)
target - A vector path, or any special target defined in data-targeting such as append-to.
Returns an updated env (which is a valid return value from remote sections of mutations).
Set's a target for the return value from the mutation to be merged into. This can be combined with returning to define a path to insert the new entry. `env` - The mutation env (you can thread together `returning` and `with-target`) `target` - A vector path, or any special target defined in `data-targeting` such as `append-to`. Returns an updated env (which is a valid return value from remote sections of mutations).
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close