com.fulcrologic.fulcro.ui-state-machines — com.fulcrologic/fulcro 3.5.0

Support for structuring the logic of component interactions as a state machine. Useful when the logic of a group of components becomes non-trivial, which is often. Note that it is not recommended that you try to structure large parts of your application as a state machine (since this implementation is closer to FSM than state charts), but it turns out that most applications work very well with groups of components under separate state machines as somewhat larger modules of the overall application. See the Developer's Guide for more information on working with this namespace.

activate clj/s

(activate env state-id)

Move to the given state. Returns a new env.

active-state-handler clj/s

(active-state-handler env)

Find the handler for the active state in the current env.

actor->ident clj/s

(actor->ident env actor-name)

actor-class clj/s

(actor-class env actor-name)

Returns the Fulcro component class that for the given actor, if set.

actor-path clj/s

(actor-path env actor-name)

(actor-path env actor-name k)

Get the real Fulcro state-path for the entity of the given actor.

actor-value clj/s

(actor-value env actor-name k)

(actor-value {:com.fulcrologic.fulcro.ui-state-machines/keys [state-map]
              :as env}
             actor-name
             k
             follow-idents?)

Get the value of a particular key in the given actor's entity. If follow-idents? is true (which is the default), then it will recursively follow idents until it finds a non-ident value.

add-uism! clj/s

(add-uism! app
           {:keys [state-machine-definition id receive-props
                   initial-event-data]})

Add a UISM to Fulcro in a manner disconnected from React.

The options map should contain:

• :state-machine-definition - The state machine you want to create/use.
• :id - The ID you want to use for the instance of the state machine.
• :receive-props - A (fn [props]) that is called whenever the state changes in a way that affects an actor. The props is a map that contains the actor props (by actor name {:actor/x actor-x-props}) and the current state of the state machine as :active-state.
• :initial-event-data - The data to pass to the initial event if the machine is started (not remounted).

This will set up the given state machine under the given ID, and start it (if not already started). Your initial state handler MUST set up actors and otherwise initialize based on initial-event-data.

If the machine is already started at the given ID then this will send it an :event/remounted event.

You MUST include :componentName in each of your actor's normalizing component options (e.g. (nc query {:componentName ::uniqueName})) because UISM requires component appear in the component registry (components cannot be safely stored in app state, just their names).

NOTE: This function automatically supports a very fast variant of props change detection, so you will not receive calls when there is a transaction that does not change the actors/active state of this UISM.

alias-value clj/s

(alias-value {:com.fulcrologic.fulcro.ui-state-machines/keys [state-map]
              :as env}
             alias)

Get a Fulcro state value by state machine data alias.

aliased-data clj/s

(aliased-data env)

Extracts aliased data from Fulcro state to construct arguments. If explicit-args is supplied, then that is merged with aliased data, passed to the named plugin. The return of the plugin is the result of this function

any->actor-component-registry-key clj/s

(any->actor-component-registry-key v)

Convert one of the possible inputs for an actor into an actor component registry key.

v can be an ident with actor metadata (see with-actor-class), a Fulcro runtime instance whose get-ident returns a valid ident, or a Fulcro component class with a singleton ident.

Returns the Fulcro component registry key (a keyword) that will be able to find the real Fulcro component for v.

apply-action clj/s

(apply-action env mutation-helper & args)

Run a mutation helper function (e.g. a fn of Fulcro state).

apply-event-value clj/s

(apply-event-value env
                   {:com.fulcrologic.fulcro.ui-state-machines/keys
                      [event-id event-data]})

asm-active? clj/s

(asm-active? app-ish id)

asm-id clj/s

(asm-id env)

Returns the active state machine ID from the state machine env.

asm-ident clj/s

(asm-ident asm-id)

Returns the ident of the active state machine with the given ID

asm-path clj/s

(asm-path {:com.fulcrologic.fulcro.ui-state-machines/keys [state-map asm-id]
           :as env}
          ks)

Returns the path to an asm elements in an asm env.

asm-value clj/s

(asm-value env ks)

Get the value of an ASM based on keyword OR key-path ks.

assoc-aliased clj/s

(assoc-aliased env alias new-value)

(assoc-aliased env alias new-value alias-2 value-2 & kv-pairs)

Similar to clojure.core/assoc but works on UISM env and aliases.

begin clj/s

Mutation to begin a state machine. Use begin! instead.

begin! clj/s

(begin! this machine instance-id actors)

(begin! this machine instance-id actors started-event-data)

Install and start a state machine.

this - A UI component or app machine - A state machine defined with defstatemachine instance-id - An ID by which you will refer to this active instance. actors - A map of actor-names -> The ident, class, or react instance that represent them in the UI. Raw idents do not support SM loads. started-event-data - Data that will be sent with the ::uism/started event as ::uism/event-data

clear-js-timeout! clj/s

(clear-js-timeout! timer)

clear-timeout! clj/s

(clear-timeout! env timer-id)

Clear a scheduled timeout (if it has yet to fire). Harmless to call if the timeout is gone. This call takes effect immediately (in terms of making sure the timeout does not fire).

clear-timeouts-on-event! clj/s

(clear-timeouts-on-event! env event-id)

Processes the auto-cancel of events. This is a normal part of the internals, but can be used in handlers to simulate a different event than acutally occured for the purpose of clearing sets of timers that auto-cancel on other events than what occurred.

compute-target clj/s

(compute-target env
                {:com.fulcrologic.fulcro.algorithms.data-targeting/keys [target]
                 :com.fulcrologic.fulcro.ui-state-machines/keys [target-actor
                                                                 target-alias]})

Compute a raw Fulcro target based on the possible options.

env - The SM env

targeting options:

:com.fulcrologic.fulcro.algorithms.data-targeting/target explicit-target - A raw Fulcro data fetch target. ::uism/target-actor actor-alias - Helper that can translate an actor alias to a target ::uism/target-alias field-alias - Helper that can translate a data alias to a target (ident + field)

If more than one option is used, then df/mutliple-targets will be used to encode them all.

convert-load-options clj/s

(convert-load-options env options)

INTERNAL: Convert SM load options into Fulcro load options.

defstatemachine clj/s macro

(defstatemachine name body)

derive-actor-components clj/s

(derive-actor-components actors)

Calculate the map from actor names to the Fulcro component registry names that represent those actors.

derive-actor-idents clj/s

(derive-actor-idents actors)

Generate an actor->ident map.

dissoc-aliased clj/s

(dissoc-aliased env)

(dissoc-aliased env alias)

(dissoc-aliased env k & ks)

Similar to clojure.core/dissoc but works on UISM env and aliases.

exit clj/s

(exit env)

Indicate that the state machine is done.

fake-handler clj/s

(fake-handler env)

generic-event-handler clj/s

(generic-event-handler original-env)

Returns an event handler that can process events according to a state machine ::uism/events definition of the current event/state in env. If a definition cannot be found then it returns nil.

get-active-state clj/s

(get-active-state this asm-id)

Get the name of the active state for an active state machine using a component. If you use this to represent UI changes then you should include the ident of your state machine instance in the query of the component that uses it so that shouldComponentUpdate will see props change:

(defsc Component [this props]
  {:query (fn [] [ [::uism/asm-id ::my-machine] ...]) 
   ...}
  ...
  (let [s (get-active-state this ::my-machine)] ...))

get-js-timer clj/s

(get-js-timer env timer-id)

get-state-machine clj/s

(get-state-machine id)

handle-load-error clj/s

handle-load-error* clj/s

(handle-load-error* app load-request)

integrate-ident clj/s

(integrate-ident env ident & named-parameters)

Integrate an ident into any number of aliases in the state machine. Aliases must point to a list of idents.

The named parameters can be specified any number of times. They are:

• append: A keyword (alias) to a list in your app state where this new object's ident should be appended. Will not append the ident if that ident is already in the list.
• prepend: A keyword (alias) to a list in your app state where this new object's ident should be prepended. Will not append the ident if that ident is already in the list.

load clj/s

(load env key-or-ident component-class-or-actor-name)

(load env key-or-ident component-class-or-actor-name options)

Identical API to fulcro's data fetch load, but using a handle env instead of a component/app. Adds the load request to then env which will be sent to Fulcro as soon as the handler finishes.

The 3rd argument can be a Fulcro class or a UISM actor name that was registered with begin!.

The options can include anything from data fetch's load, but the following additional keys are more supported for better integration with UISM:

::uism/ok-event:: An event to send when the load is done (instead of calling a mutation) ::uism/ok-data:: To send as event-data on the ok-event. ::uism/error-event:: The event to send if the load has a network error. ::uism/error-data:: To send as event-data on error. ::uism/target-actor:: Set target to a given actor's ident. See also load-actor. ::uism/target-alias:: Set load target to the path defined by the given alias.

NOTE: In general a state machine should declare an actor for items in the machine and use load-actor instead of this function so that the state definitions themselves need not be coupled (via code) to the UI.

load-actor clj/s

(load-actor env actor-name)

(load-actor env
            actor-name
            {:com.fulcrologic.fulcro.components/keys [component-class]
             :as options})

Load (refresh) the given actor. If the actor is not on the UI, then you must specify :com.fulcrologic.fulcro.components/component-class in the options map.

options can contain the normal df/load parameters, and also:

::comp/component-class - The defsc name of the component to use for normalization and query. Only needed if the actor was not declared using a Fulcro component or component class. ::uism/ok-event:: An event to send when the load is done (instead of calling a mutation) ::uism/ok-data:: To send as event-data on the ok-event. ::uism/error-event:: The event to send if the load has a network error. ::uism/error-data:: To send as event-data on error.

Adds a load request to then env which will be sent to Fulcro as soon as the handler finishes.

lookup-state-machine clj/s

(lookup-state-machine env)

lookup-state-machine-field clj/s

(lookup-state-machine-field env ks)

mutation-delegate clj/s

new-asm clj/s

(new-asm {:com.fulcrologic.fulcro.ui-state-machines/keys
            [state-machine-id asm-id actor->ident actor->component-name]})

Create the runtime state for the given state machine in it's initial state.

• ::asm-id is the globally unique key of for a state machine definition.
• ::asm-id is a user-generated unique ID for the instance of the asm. This allows more than one instance of the same state machine definition to be active at the same time on the UI.
• ::actor->ident is a map from actor name to an ident.

Returns an active state machine that can be stored in Fulcro state for a specific state machine definition.

queue-actor-load! clj/s

(queue-actor-load! app env actor-name component-class load-options)

Internal implementation. Queue a load of an actor.

queue-loads! clj/s

(queue-loads! app env)

queue-mutations! clj/s

(queue-mutations! app env)

queue-normal-load! clj/s

(queue-normal-load! app query-key component-class load-options)

Internal implementation. Queue a load.

register-state-machine! clj/s

(register-state-machine! id definition)

registry clj/s

remove-ident clj/s

(remove-ident env ident alias-to-idents)

Removes an ident, if it exists, from an alias that points to a list of idents.

remove-uism! clj/s

(remove-uism! app id)

Remove a previously-added UISM from state and the render listener. The state machine will not receive any (final) events.

reset-actor-ident clj/s

(reset-actor-ident env actor ident)

Safely changes the ident of an actor.

Makes sure ident is consistently reset and updates the actor class (if one is specified using with-actor-class).

resolve-alias clj/s

(resolve-alias env alias)

Looks up the given alias in the alias map and returns the real Fulcro state path or nil if no such path exists.

retrieve clj/s

(retrieve env k)

(retrieve env k dflt)

Retrieve the value for a k from the active state machine. See store.

run clj/s

(run env plugin-name)

(run env plugin-name explicit-args)

Run a state-machine plugin. Extracts aliased data from Fulcro state to construct arguments. If explicit-args is supplied, then that is merged with aliased data, passed to the named plugin. The return of the plugin is the result of this function. Plugins cannot side-effect, and are meant for providing external computation algorithms that the state machine logic might need. For example, an actor representing a form might need to provide validation logic.

If explicit-args are passed, then they will take precedence over the auto-extracted aliased data that is passed to the plugin.

schedule-timeouts! clj/s

(schedule-timeouts! app env)

INTERNAL: actually schedule the timers that were submitted during the event handler.

set-actor-value clj/s

(set-actor-value env actor-name k v)

Set a value in the actor's Fulcro entity. Only the actor is resolved. The k is not processed as an alias.

set-aliased-value clj/s

(set-aliased-value env alias new-value)

(set-aliased-value env alias new-value alias-2 value-2 & kv-pairs)

Deprecated. Use assoc-aliased.

set-js-timeout! clj/s

(set-js-timeout! f tm)

set-string! clj/s

(set-string! this active-state-machine-id alias event-or-string)

Similar to Fulcro's set-string, but it sets the string on an active state machine's data alias. event-or-string can be a string or a React DOM onChange event.

The incoming event-data to your handler will include ::uism/alias and :value (if you care to do anything with the value change event).

NOTE: Generates a ::uism/value-changed event. If you're state machine is implemented with the events structure that allows an event-predicate, then this set will be ignored if the current state's event-predicate returns false.

set-timeout clj/s

(set-timeout env timer-id event-id event-data timeout)

(set-timeout env timer-id event-id event-data timeout cancel-on-events)

Add a timeout named timer-id to the env that will send event-id with event-data event after timeout (in milliseconds) unless an event (i.e. some-event-id) occurs where a call to (cancel-on-events some-event-id) returns true.

Setting a timeout on an existing timer-id will cancel the current one and start the new one.

cancel-on-events is a predicate that will be passed an event ID on events. If it returns true on an event before the timeout fires, then the timeout will be auto-cancelled. If not specified, then it defaults to (constantly false).

set-value! clj/s

(set-value! this active-state-machine-id alias value)

Similar to Fulcro's set-value, but it sets the raw value on an active state machine's data alias.

The incoming event-data to your handler will include ::uism/alias and :value (if you care to do anything with the value change event).

NOTE: Generates a ::uism/value-changed event. If you're state machine is implemented with the events structure that allows an event-predicate, then this set will be ignored if the current state's event-predicate returns false.

spec-mutation clj/s

state-machine-env clj/s

(state-machine-env state-map asm-id)

(state-machine-env state-map ref asm-id event-id event-data)

(state-machine-env state-map ref asm-id event-id event-data app)

Create an env for use with other functions. Used internally, but may be used as a helper .

store clj/s

(store env k v)

Store a k/v pair with the active state machine (will only exist as long as it is active)

transact clj/s

(transact env txn)

(transact env txn options)

Just like components/transact!, but simply queues the transaction to be submitted after the handler completes. Usually you can use apply-action to do local state changes, and trigger-remote-mutation to do remote operations; however, sometimes external users of a state machine wish to supply ad-hoc operations that should be run by a state machine.

NOTE: It is legal to side-effect in an event handler, but in general the desired operation is to defer the side effects (e.g. comp/transact!) until the handler has finished. Running, for example, a synchronous transact inside of a handler will not work as expected because the handler will finish after such a transaction and overwrite the changes to state that such a transaction caused.

So, for example, someone might begin a state machine with:

(begin! this machine :id actors {:on-success `[(something-happened)])

which the state machine can save with store, and later look up with retrieve.

options is as described in components/transact!.

trigger clj/s

(trigger env asm-id event)

(trigger env asm-id event event-data)

Trigger an event on a state machine. Events sent this way will be processed immediately (synchronously) after the handler for the calling handler completes. If you prefer that a trigger happens as a separate transaction then use trigger!.

env - is the env in a state machine handler asm-id - The ID of the state machine you want to trigger an event on. event - The event ID you want to send. event-data - A map of data to send with the event

Returns the updated env. The actual event will not be sent until this handler finishes.

trigger! clj/s

(trigger! this active-state-machine-id event-id)

(trigger! this active-state-machine-id event-id extra-data)

Trigger an event on an active state machine. Safe to use in mutation bodies. The special key ::uism/transact-options can be used in extra-data to indicate a map of options to send to fulcro's transact! and rendering sublayer (for example to control rendering refresh).

trigger!! clj/s

(trigger!! this active-state-machine-id event-id)

(trigger!! this active-state-machine-id event-id extra-data)

Just like trigger!, but does optimistic actions synchronously so that events that change data rendered in form fields will be updated synchronously.

trigger-queued-events! clj/s

(trigger-queued-events! mutation-env queued-triggers refresh-list)

trigger-remote-mutation clj/s

(trigger-remote-mutation env actor mutation options-and-params)

Run the given REMOTE mutation (a symbol or mutation declaration) in the context of the state machine.

env - The SM handler environment actor - The name (keyword) of a defined actor. mutation - The symbol (or mutation declaration) of the server mutation to run. This function will not run a local version of the mutation. options-and-params - The parameters to pass to your mutation. This map can also include these additional state-machine options:

::uism/target-actor actor - If you use this it will set JUST the target (not necessary for loading an actor). Use ::m/returning to override the type if necessary. ::uism/target-alias field-alias - Helper that can translate a data alias to a target (ident + field). You must also use returning to specify the normalization type. :com.fulcrologic.fulcro.mutations/returning Class - Class to use for normalizing the result. :com.fulcrologic.fulcro.algorithms.data-targeting/target explicit-target - Target for result ::uism/ok-event event-id - The SM event to trigger when the pessimistic mutation succeeds (no default). ::uism/error-event event-id - The SM event to trigger when the pessimistic mutation fails (no default). ::uism/ok-data map-of-data - Data to include in the event-data on an ok event ::uism/error-data map-of-data - Data to include in the event-data on an error event ::uism/mutation-remote - The keyword name of the Fulcro remote (defaults to :remote) :com.fulcrologic.fulcro.algorithms.tx-processing/abort-id - An abort ID for being able to cancel the mutation.

NOTE: The mutation response will be merged into the event data that is sent to the SM handler.

This function does not side effect. It queues the mutation to run after the handler exits.

trigger-state-machine-event clj/s

Mutation: Trigger an event on an active state machine

trigger-state-machine-event! clj/s

(trigger-state-machine-event! {:keys [app state ref] :as mutation-env}
                              {:com.fulcrologic.fulcro.ui-state-machines/keys
                                 [event-id event-data asm-id]
                               :as params})

IMPLEMENTATION DETAIL. Low-level implementation of triggering a state machine event. Does no direct interaction with Fulcro UI refresh. Use trigger! instead.

• env - A fulcro mutation env, containing at least the state atom and optionally the ref of the component that was the source of the event.
• params - The parameters for the event

Returns a vector of actor idents that should be refreshed.

ui-refresh-list clj/s

(ui-refresh-list env)

Returns a vector of things to refresh in Fulcro based on the final state of an active SM env.

update-aliased clj/s

(update-aliased env k f)

(update-aliased env k f x)

(update-aliased env k f x y)

(update-aliased env k f x y z)

(update-aliased env k f x y z & more)

Similar to clojure.core/update but works on UISM env and aliases.

update-fulcro-state! clj/s

(update-fulcro-state! {:com.fulcrologic.fulcro.ui-state-machines/keys [asm-id]
                       :as env}
                      state-atom)

Put the evolved state-map from an env into a (Fulcro) state-atom

valid-state? clj/s

(valid-state? env state-id)

with-actor-class clj/s

(with-actor-class ident class)

Associate a given component UI Fulcro class with an ident. This is used with begin! in your actor map if the actor in question is going to be used with loads or mutations that return a value of that type. The actor's class can be retrieved for use in a handler using (uism/actor-class env).

(begin! ... {:person (uism/with-actor-class [:person/by-id 1] Person)})