com.fulcrologic.fulcro.mutations — com.fulcrologic/fulcro 3.0.0

declare-mutation clj/s macro

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

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.

defmutation clj/s macro

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

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.

defmutation* clj

(defmutation* macro-env args)

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.

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.

mutate clj/s multimethod

Mutation cljs

mutation-declaration? clj/s

(mutation-declaration? expr)

mutation-symbol clj/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.

returning clj/s

(returning env class)

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

Returns an update env, and is a valid return value from mutation remote sections.

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-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-props cljs

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

toggle cljs

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.

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.

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.

with-params clj/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.

with-target clj/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).