Liking cljdoc? Tell your friends :D

com.fulcrologic.fulcro.ui-state-machines

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.

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

activateclj/s

(activate env state-id)

Move to the given state. Returns a new env.

Move to the given state. Returns a new env.
sourceraw docstring

active-state-handlerclj/s

(active-state-handler env)

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

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

actor->identclj/s

(actor->ident env actor-name)
source

actor-classclj/s

(actor-class env actor-name)

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

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

actor-pathclj/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.

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

actor-valueclj/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.

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

add-uism!clj/s

(add-uism! app
           {:keys [state-machine-definition id receive-props actors
                   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.
  • :actors - The actor definitions. See begin!.
  • :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.

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`.
* `:actors` - The actor definitions. See `begin!`.
* `: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.
sourceraw docstring

alias-valueclj/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.

Get a Fulcro state value by state machine data alias.
sourceraw docstring

aliased-dataclj/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

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

any->actor-component-registry-keyclj/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.

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

apply-actionclj/s

(apply-action env mutation-helper & args)

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

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

apply-event-valueclj/s

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

asm-active?clj/s

(asm-active? app-ish id)
source

asm-idclj/s

(asm-id env)

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

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

asm-identclj/s

(asm-ident asm-id)

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

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

asm-pathclj/s

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

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

Returns the path to an asm elements in an asm `env`.
sourceraw docstring

asm-valueclj/s

(asm-value env ks)

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

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

assoc-aliasedclj/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.

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

beginclj/s

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

Mutation to begin a state machine. Use `begin!` instead.
sourceraw docstring

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

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

clear-js-timeout!clj/s

(clear-js-timeout! timer)
source

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

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.

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

compute-targetclj/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.

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

convert-load-optionsclj/s

(convert-load-options env options)

INTERNAL: Convert SM load options into Fulcro load options.

INTERNAL: Convert SM load options into Fulcro load options.
sourceraw docstring

current-state-and-actorsclj/s

(current-state-and-actors state-map id)

Returns a map that contains the given state-machine's ID and actor state.

state-map - The current Fulcro state map asm-id - The ID of the state machine of interest.

Returns a map that contains the given state-machine's ID and actor state.

`state-map` - The current Fulcro state map
`asm-id` - The ID of the state machine of interest.
sourceraw docstring

defstatemachineclj/smacro

(defstatemachine name body)
source

derive-actor-componentsclj/s

(derive-actor-components actors)

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

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

derive-actor-identsclj/s

(derive-actor-idents actors)

Generate an actor->ident map.

Generate an actor->ident map.
sourceraw docstring

dissoc-aliasedclj/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.

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

exitclj/s

(exit env)

Indicate that the state machine is done.

Indicate that the state machine is done.
sourceraw docstring

fake-handlerclj/s

(fake-handler env)
source

generic-event-handlerclj/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.

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

get-active-stateclj/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 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)] ...))
```
sourceraw docstring

get-js-timerclj/s

(get-js-timer env timer-id)
source

get-state-machineclj/s

(get-state-machine id)
source

handle-load-errorclj/s

source

handle-load-error*clj/s

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

integrate-identclj/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.
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.
sourceraw docstring

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

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

load-actorclj/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.

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

lookup-state-machineclj/s

(lookup-state-machine env)
source

lookup-state-machine-fieldclj/s

(lookup-state-machine-field env ks)
source

mutation-delegateclj/s

source

new-asmclj/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.

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

queue-actor-load!clj/s

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

Internal implementation. Queue a load of an actor.

Internal implementation. Queue a load of an actor.
sourceraw docstring

queue-loads!clj/s

(queue-loads! app env)
source

queue-mutations!clj/s

(queue-mutations! app env)
source

queue-normal-load!clj/s

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

Internal implementation. Queue a load.

Internal implementation. Queue a load.
sourceraw docstring

register-state-machine!clj/s

(register-state-machine! id definition)
source

registryclj/s

source

remove-identclj/s

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

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

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

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.

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

reset-actor-identclj/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).

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

resolve-aliasclj/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.

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

retrieveclj/s

(retrieve env k)
(retrieve env k dflt)

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

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

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

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

schedule-timeouts!clj/s

(schedule-timeouts! app env)

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

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

set-actor-valueclj/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 a value in the actor's Fulcro entity. Only the actor is resolved. The k is not processed as an alias. 
sourceraw docstring

set-aliased-valueclj/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.

Deprecated. Use assoc-aliased.
sourceraw docstring

set-js-timeout!clj/s

(set-js-timeout! f tm)
source

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.

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

set-timeoutclj/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).

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

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.

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

spec-mutationclj/s

source

state-machine-envclj/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 .

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

storeclj/s

(store env k v)

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

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

transactclj/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!.

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

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

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

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.

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

trigger-queued-events!clj/s

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

trigger-remote-mutationclj/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.

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

trigger-state-machine-eventclj/s

Mutation: Trigger an event on an active state machine

Mutation: Trigger an event on an active state machine
sourceraw docstring

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.

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

ui-refresh-listclj/s

(ui-refresh-list env)

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

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

update-aliasedclj/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.

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

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

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

valid-state?clj/s

(valid-state? env state-id)
source

with-actor-classclj/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)})
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)})
```
sourceraw docstring

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

× close