(add-child! {:com.fulcrologic.rad.form/keys [master-form] :as env})
Add a child. You must pass a form rendering environment that includes additional keys:
(form/add-child! (assoc env
::form/order :prepend
::form/parent-relation :person/addresses
::form/parent form-instance
::form/child-class ui))
See renderers for usage examples.
Add a child. You must pass a form rendering environment that includes additional keys: ``` (form/add-child! (assoc env ::form/order :prepend ::form/parent-relation :person/addresses ::form/parent form-instance ::form/child-class ui)) ``` See renderers for usage examples.
(apply-derived-calculations
{:com.fulcrologic.fulcro.ui-state-machines/keys [event-data] :as env})
Apply derived calcuations to the form using the UISM env of the master form. Derived calculations are configured on
the form via ::form/triggers
:derive-fields
function (a fn of ui props that must return new ui props).
Derived field calculations are first performed on the (sub)form on which the attribute that changed exists, and then via any defined trigger on the master form (assuming it isn't the same form).
The :derive-fields
functions should be pure functions.
Apply derived calcuations to the form using the UISM env of the master form. Derived calculations are configured on the form via `::form/triggers` `:derive-fields` function (a fn of ui props that must return new ui props). Derived field calculations are first performed on the (sub)form on which the attribute that changed exists, and then via any defined trigger on the master form (assuming it isn't the same form). The `:derive-fields` functions should be pure functions.
(attr->renderer {:com.fulcrologic.rad.form/keys [form-instance master-form]}
{:com.fulcrologic.rad.attributes/keys [type qualified-key style]
:com.fulcrologic.rad.form/keys [field-style]
:as attr})
Given a form rendering environment and an attribute: returns the renderer that can render the given attribute.
The attribute style of :default is the default, and can be overridden in ::form/field-styles on the form (master has precedence, followed by the form it actually appears on) or using ::form/field-style on the attribute itself.
Given a form rendering environment and an attribute: returns the renderer that can render the given attribute. The attribute style of :default is the default, and can be overridden in ::form/field-styles on the form (master has precedence, followed by the form it actually appears on) or using ::form/field-style on the attribute itself.
(auto-create-to-one {:com.fulcrologic.fulcro.ui-state-machines/keys [state-map]
:as env})
Create any to-one referenced entities that did not load, but which are marked as auto-create.
Create any to-one referenced entities that did not load, but which are marked as auto-create.
(calc-diff uism-env)
Calculates the minimal form diff from the UISM env of the master form's state machine.
Calculates the minimal form diff from the UISM env of the master form's state machine.
(cancel! {this :com.fulcrologic.rad.form/master-form})
Trigger a cancel of all changes on the given form rendering env. This is like undo, but attempts to route away from the form.
Trigger a cancel of all changes on the given form rendering env. This is like undo, but attempts to route away from the form.
(computed-value env
{:com.fulcrologic.rad.attributes/keys [computed-value]
:as attr})
Returns the computed value of the given attribute on the form from env
(if it is a computed attribute).
Computed attributes are regular attributes with no storage (though they may have resolvers) and a ::attr/computed-value
function. Such a function will be called with the form rendering env and the attribute definition itself.
Returns the computed value of the given attribute on the form from `env` (if it is a computed attribute). Computed attributes are regular attributes with no storage (though they may have resolvers) and a `::attr/computed-value` function. Such a function will be called with the form rendering env and the attribute definition itself.
(convert-options get-class location options)
Runtime conversion of form options to what comp/configure-component! needs.
Runtime conversion of form options to what comp/configure-component! needs.
(create! app-ish form-class)
(create! app-ish form-class options)
Create a new instance of the given form-class using the provided entity-id
and then route
to that form for editing.
app-ish
: A component instance or the app.form-class
: The form to create.options
map will be passed to the form as extra options.The options
in the default form state machine can contain:
:initial-state
- A tree of data to be deep-merged into the new instance of the form before form config
is added. This can be used to pre-set form fields to specific values.Create a new instance of the given form-class using the provided `entity-id` and then route to that form for editing. - `app-ish`: A component instance or the app. - `form-class`: The form to create. - `options` map will be passed to the form as extra options. The `options` in the default form state machine can contain: * `:initial-state` - A tree of data to be deep-merged into the new instance of the form before form config is added. This can be used to pre-set form fields to specific values.
(default-state FormClass new-id)
Generate a potentially recursive tree of data that represents the tree of initial
state for the given FormClass. Such generated trees will be rooted with the provided
new-id
, and will generate Fulcro tempids for all nested entities. To-one relations
that have no default will not be included. To-many relations that have no default
will default to an empty vector.
The FormClass can have ::form/default-values
, a map from attribute keyword to the value
to give that attribute in new instances of the form. A global default can be set on the
attribute itself using ::form/default-value
.
See the doc strings on default-to-one and default-to-many for more information on setting options.
WARNING: If a rendering field style is given to a ref attribute on a field, then the default value will be the raw default value declared on the attribute or form, but should generally be nil.
Generate a potentially recursive tree of data that represents the tree of initial state for the given FormClass. Such generated trees will be rooted with the provided `new-id`, and will generate Fulcro tempids for all nested entities. To-one relations that have no default will not be included. To-many relations that have no default will default to an empty vector. The FormClass can have `::form/default-values`, a map from attribute *keyword* to the value to give that attribute in new instances of the form. A global default can be set on the attribute itself using `::form/default-value`. See the doc strings on default-to-one and default-to-many for more information on setting options. WARNING: If a rendering field style is given to a ref attribute on a field, then the default value will be the *raw* default value declared on the attribute or form, but should generally be nil.
(default-to-many FormClass attribute)
Use default-state
on the top level form. This is part of the recursive implementation.
Calculate a default value for any to-many attributes on the form. This is part of the recursive algorithm that can generate initial state for a new instance of a form.
If a form has subform configuration that declares a ::form/default
which is a vector, then each element
in that vector will generate new subform state.
The result will be a merge
of:
(merge (form/default-state SubformClass id) default-value {id-key id})
If no defaults are provided you will at least get something that will normalize properly.
Example:
(defattr people :people :ref
{::attr/cardinality :many
::form/default-value [{}] ; used if form doesn't declare
...})
(defsc Form [this props]
{::form/id id
::form/columns [people]
::form/default-values {:people [{} {} {}]} ; overrides what is on attributes
::form/subforms {:people {::form/ui Person}}})
Default value can be a no-arg function, but the argument list may change in future versions.
Use `default-state` on the top level form. This is part of the recursive implementation. Calculate a default value for any to-many attributes on the form. This is part of the recursive algorithm that can generate initial state for a new instance of a form. If a form has subform configuration that declares a `::form/default` which is a vector, then each element in that vector will generate new subform state. The result will be a `merge` of: ``` (merge (form/default-state SubformClass id) default-value {id-key id}) ``` If no defaults are provided you will at least get something that will normalize properly. Example: ``` (defattr people :people :ref {::attr/cardinality :many ::form/default-value [{}] ; used if form doesn't declare ...}) (defsc Form [this props] {::form/id id ::form/columns [people] ::form/default-values {:people [{} {} {}]} ; overrides what is on attributes ::form/subforms {:people {::form/ui Person}}}) ``` Default value can be a no-arg function, but the argument list may change in future versions.
(default-to-one FormClass attribute)
Use default-state
on the top level form. This is part of the recursive implementation.
Generates the default value for a to-one ref in a new instance of a form set. Has the same behavior as default-to-many, though the default values must be a map instead of a vector.
Default value can be a no-arg function, but the argument list may change in future versions.
Use `default-state` on the top level form. This is part of the recursive implementation. Generates the default value for a to-one ref in a new instance of a form set. Has the same behavior as default-to-many, though the default values must be a map instead of a vector. Default value can be a no-arg function, but the argument list may change in future versions.
(delete! this id-key entity-id)
Delete the given entity from local app state and the remote (if present). This method assumes that the given entity is not currently being edited and can be used from anyplace else in the application.
Delete the given entity from local app state and the remote (if present). This method assumes that the given entity is *not* currently being edited and can be used from anyplace else in the application.
(delete-child! {:com.fulcrologic.rad.form/keys [master-form] :as env})
Delete a child of a master form. Only use this on nested forms that are actively being edited. See
also delete!
. The rendering env that you pass to this function must be the rendering env passed to the
child that is to be deleted.
Delete a child of a master form. Only use this on nested forms that are actively being edited. See also `delete!`. The rendering env that you pass to this function must be the rendering env passed *to* the child that is to be deleted.
(edit! this form-class entity-id)
(edit! this form-class entity-id extra-params)
Route to the given form for editing the entity with the given ID.
Route to the given form for editing the entity with the given ID.
(field-autocomplete {:com.fulcrologic.rad.form/keys [form-instance] :as env}
attribute)
Returns the proper string (or nil) for a given attribute's autocomplete setting
Returns the proper string (or nil) for a given attribute's autocomplete setting
(field-label form-env attribute)
Returns a human readable label for a given attribute (which can be declared on the attribute, and overridden on the specific form). Defaults to the capitalized name of the attribute qualified key. Labels can be configured on the form that renders them or on the attribute. The form overrides the attribute.
::form/field-label
: A string or function returning a string.::form/field-labels
: A map from attribute keyword to a string or function returning a string.If label functions are used they are passed the form instance that is rendering them. They must not side-effect.
Returns a human readable label for a given attribute (which can be declared on the attribute, and overridden on the specific form). Defaults to the capitalized name of the attribute qualified key. Labels can be configured on the form that renders them or on the attribute. The form overrides the attribute. * On an attribute `::form/field-label`: A string or function returning a string. * On a form `::form/field-labels`: A map from attribute keyword to a string or function returning a string. If label functions are used they are passed the form instance that is rendering them. They must not side-effect.
(field-style-config {:com.fulcrologic.rad.form/keys [form-instance]}
attribute
config-key)
Get the value of an overridable field-style-config option. If both the form and attribute set these then the result will be a deep merge of the two (with form winning).
Get the value of an overridable field-style-config option. If both the form and attribute set these then the result will be a deep merge of the two (with form winning).
(field-visible? form-instance
{:com.fulcrologic.rad.form/keys [field-visible?]
:com.fulcrologic.rad.attributes/keys [qualified-key]
:as attr})
Should the attr
on the given form-instance
be visible? This is controlled:
::form/field-visible?
. A boolean or (fn [form-instance attr] boolean?)
::form/fields-visible?
. A map from attr keyword to boolean or (fn [form-instance attr] boolean?)
A field is visible if the form says it is. If the form has no opinion, then it is visible if the attribute says it is (as true?). If neither the form nor attribute return a boolean, then the field is visible.
Should the `attr` on the given `form-instance` be visible? This is controlled: * On the attribute at `::form/field-visible?`. A boolean or `(fn [form-instance attr] boolean?)` * On the form via the map `::form/fields-visible?`. A map from attr keyword to boolean or `(fn [form-instance attr] boolean?)` A field is visible if the form says it is. If the form has *no opinion*, then it is visible if the attribute says it is (as true?). If neither the form nor attribute return a boolean, then the field is visible.
(form-container-renderer form-env)
The top-level container for the entire on-screen form
The top-level container for the entire on-screen form
(form-layout-renderer form-env)
The container for the form fields. Used to wrap the main set of fields, and as the container for fields in nested forms. This renderer can determine layout of the fields themselves.
The container for the form fields. Used to wrap the main set of fields, and as the container for fields in nested forms. This renderer can determine layout of the fields themselves.
(form-options->form-query {id-attr :com.fulcrologic.rad.form/id
:com.fulcrologic.rad.form/keys
[attributes field-styles subforms]
:as form-options})
Converts form options to the necessary EQL query for a form class.
Converts form options to the necessary EQL query for a form class.
(form-pre-merge {:com.fulcrologic.rad.form/keys [subforms]} key->attribute)
Generate a pre-merge for a component that has the given for attribute map. Returns a proper
pre-merge fn, or nil
if none is needed
Generate a pre-merge for a component that has the given for attribute map. Returns a proper pre-merge fn, or `nil` if none is needed
(form-will-enter app {:keys [action id] :as route-params} form-class)
Used as the implementation and return value of a form target's will-enter dynamic routing hook.
Used as the implementation and return value of a form target's will-enter dynamic routing hook.
(form-will-leave this)
Checks to see if the UISM is still running (indicating an exit via routing) and cleans up the machine.
Checks to see if the UISM is still running (indicating an exit via routing) and cleans up the machine.
(input-blur! {:com.fulcrologic.rad.form/keys [form-instance master-form]}
k
value)
Helper: Informs the form's state machine that focus has left an input. Requires a form rendering env, attr keyword, and the current value.
Helper: Informs the form's state machine that focus has left an input. Requires a form rendering env, attr keyword, and the current value.
(input-changed! {:com.fulcrologic.rad.form/keys [form-instance master-form]
:as env}
k
value)
Helper: Informs the form's state machine that an input's value has changed. Requires a form rendering env, attr keyword, and the current value.
Helper: Informs the form's state machine that an input's value has changed. Requires a form rendering env, attr keyword, and the current value.
Renamed to rad-application/install-ui-controls!
Renamed to rad-application/install-ui-controls!
(invalid? form-rendering-env)
(invalid? form-class-or-instance props)
Returns true if the validator on the form in env
indicates that some form field(s) are invalid. Note that a
field does not report valid OR invalid until it is marked complete (usually on blur).
Returns true if the validator on the form in `env` indicates that some form field(s) are invalid. Note that a field does not report valid OR invalid until it is marked complete (usually on blur).
(leave-form {:com.fulcrologic.fulcro.ui-state-machines/keys [fulcro-app]
:as uism-env})
Discard all changes, and attempt to change route.
Discard all changes, and attempt to change route.
(mark-filled-fields-complete* state-map {:keys [entity-ident initialized-keys]})
Helper function against app state. This function marks initialized-keys
as complete on the form given a set of
keys that you consider initialized. Like form state's mark-complete, but on a set instead of a single field.
Helper function against app state. This function marks `initialized-keys` as complete on the form given a set of keys that you consider initialized. Like form state's mark-complete, but on a set instead of a single field.
(master-form component)
Return the master form for the given component instance.
Return the master form for the given component instance.
(master-form? rendering-env form-instance)
Returns true if the given react element form-instance
is the master form in the supplied rendering env.
Returns true if the given react element `form-instance` is the master form in the supplied rendering env.
(pathom-plugin save-middleware delete-middleware)
A pathom plugin that installs general form save/delete support on the pathom parser. Requires save and delete middleware, which will accomplish the actual actions. Calling RAD form save/delete without this plugin and both bits of middleware will result in a runtime error.
A pathom plugin that installs general form save/delete support on the pathom parser. Requires save and delete middleware, which will accomplish the actual actions. Calling RAD form save/delete without this plugin and both bits of middleware will result in a runtime error.
(picker-join-key qualified-key)
Returns a :ui/picker keyword customized to the qualified keyword
Returns a :ui/picker keyword customized to the qualified keyword
(read-only? form-instance
{:com.fulcrologic.rad.attributes/keys [qualified-key identity?
read-only? computed-value]
:as attr})
Returns true if the given attribute is meant to show up as read only on the given form instance. Attributes
configure this by placing a boolean value (or function returning boolean) on the attribute at ::attr/read-only?
.
The form's options may also include ::form/read-only-fields
as a set (or a function returning a set) of the keys that should
currently be considered read-only. If it is a function it will only be passed the form instance.
If the form has a ::form/read-only?
option that is true
(or a (fn [form-instance] boolean?)
that returns true) then
everything on the form will be read-only.
If you use a function for read only detection it will be passed the form-instance
and the attribute
being
checked. You may reach into app state to examine things, but beware that doing so may not dynamically update
as you'd expect.
Returns true if the given attribute is meant to show up as read only on the given form instance. Attributes configure this by placing a boolean value (or function returning boolean) on the attribute at `::attr/read-only?`. The form's options may also include `::form/read-only-fields` as a set (or a function returning a set) of the keys that should currently be considered read-only. If it is a function it will only be passed the form instance. If the form has a `::form/read-only?` option that is `true` (or a `(fn [form-instance] boolean?)` that returns true) then *everything* on the form will be read-only. If you use a function for read only detection it will be passed the `form-instance` and the `attribute` being checked. You may reach into app state to examine things, but beware that doing so may not dynamically update as you'd expect.
(ref-container-renderer {:com.fulcrologic.rad.form/keys [form-instance]
:as form-env}
{:com.fulcrologic.rad.form/keys [field-style]
:com.fulcrologic.rad.attributes/keys [qualified-key]
:as attr})
Given the current rendering environment and an attribute: Returns the renderer that wraps and lays out elements of refs. This function interprets the ::form/subforms settings for referenced objects that will render as sub-forms, and looks for ::form/layout-style first in the subform, and next on the component options of the ::form/ui class.
Given the current rendering environment and an attribute: Returns the renderer that wraps and lays out elements of refs. This function interprets the ::form/subforms settings for referenced objects that will render as sub-forms, and looks for ::form/layout-style first in the subform, and next on the component options of the ::form/ui class.
(render-field env attr)
Given a form rendering environment and an attrbute: renders that attribute according to its type/style/value.
Given a form rendering environment and an attrbute: renders that attribute according to its type/style/value.
(render-fn {:com.fulcrologic.rad.form/keys [form-instance] :as form-env}
element)
Find the correct UI renderer for the given form layout element
.
element
must be one of :
#{:form-container :form-body-container}
Find the correct UI renderer for the given form layout `element`. `element` must be one of : ``` #{:form-container :form-body-container} ```
(render-layout form-instance props)
Render the complete layout of a form. This is the default body of normal form classes. It will call a render factory on any subforms, and they, in turn, will use this to render their body. Thus, any form can have a manually-overriden render body.
Render the complete layout of a form. This is the default body of normal form classes. It will call a render factory on any subforms, and they, in turn, will use this to render *their* body. Thus, any form can have a manually-overriden render body.
(rendering-env form-instance)
(rendering-env form-instance props)
Create a form rendering environment. form-instance
is the react element instance of the form (typically a master form),
but this function can be called using an active sub-form. props
should be the props of the form-instance
, and are
allowed to be passed as an optimization when you've already got them.
NOTE: This function will automatically extract the master form from the computed props of form-instance in cases where you are in the context of a sub-form.
Create a form rendering environment. `form-instance` is the react element instance of the form (typically a master form), but this function can be called using an active sub-form. `props` should be the props of the `form-instance`, and are allowed to be passed as an optimization when you've already got them. NOTE: This function will automatically extract the master form from the computed props of form-instance in cases where you are in the context of a sub-form.
Form save and delete mutation resolvers. These must be installed on your pathom parser for saves and deletes to work, and you must also install save and delete middleware into your pathom env per the instructions of your database adapter.
Form save and delete mutation resolvers. These must be installed on your pathom parser for saves and deletes to work, and you must also install save and delete middleware into your pathom env per the instructions of your database adapter.
(route-target-ready {:com.fulcrologic.fulcro.ui-state-machines/keys [state-map]
:as env}
target)
Same as dynamic routing target-ready, but works in UISM via env.
Same as dynamic routing target-ready, but works in UISM via env.
(save! {this :com.fulcrologic.rad.form/master-form :as form-rendering-env})
Trigger a save on the given form rendering env.
Trigger a save on the given form rendering env.
MUTATION: DO NOT USE. You may use save-form* within your own mutations.
MUTATION: DO NOT USE. You may use save-form* within your own mutations.
(save-form* env params)
Internal implementation of clj-side form save. Can be used in your own mutations to accomplish writes through the save middleware.
params MUST contain:
::form/delta
- The data to save. Map keyed by ident whose values are maps with :before
and :after
values.::form/id
- The actual ID of the entity being changed.::form/master-pk
- The keyword representing the form's ID in your RAD model's attributes.Returns:
{:tempid {} ; tempid remaps master-pk id} ; the k/id of the entity saved. The id here will be remapped already if it was a tempid.
Internal implementation of clj-side form save. Can be used in your own mutations to accomplish writes through the save middleware. params MUST contain: * `::form/delta` - The data to save. Map keyed by ident whose values are maps with `:before` and `:after` values. * `::form/id` - The actual ID of the entity being changed. * `::form/master-pk` - The keyword representing the form's ID in your RAD model's attributes. Returns: {:tempid {} ; tempid remaps master-pk id} ; the k/id of the entity saved. The id here will be remapped already if it was a tempid.
The standard ::form/action-buttons button layout. Requires you include stardard-controls in your ::control/controls key.
The standard ::form/action-buttons button layout. Requires you include stardard-controls in your ::control/controls key.
The default value of ::control/controls for forms. Includes a ::done, ::undo, and ::save button.
The default value of ::control/controls for forms. Includes a ::done, ::undo, and ::save button.
(start-form! app id form-class)
(start-form! app id form-class params)
Forms use a state machine to control their behavior. Normally that state machine is started when you route to it using Fulcro's dynamic router system. If you start with a form on-screen, or do not use routing, then you will have to call this function when the form first appears in order to ensure it operates. Calling this function is destructive and will re-start the form's machine and destroy any current state in that form.
tempid
to create something new, otherwise
the form will attempt to load the current value from the server.The state machine definition used by this method can be overridden by setting ::form/machine
in component options
to a different Fulcro uism state machine definition. Machines do not run in subforms, only in the master, which
is what form-class
will become for that machine.
Forms use a state machine to control their behavior. Normally that state machine is started when you route to it using Fulcro's dynamic router system. If you start with a form on-screen, or do not use routing, then you will have to call this function when the form first appears in order to ensure it operates. Calling this function is *destructive* and will re-start the form's machine and destroy any current state in that form. * app - The app * id - The ID of the form, in the correct type (i.e. int, UUID, etc.). Use a `tempid` to create something new, otherwise the form will attempt to load the current value from the server. * form-class - The component class that will render the form and has the form's configuration. The state machine definition used by this method can be overridden by setting `::form/machine` in component options to a different Fulcro uism state machine definition. Machines do *not* run in subforms, only in the master, which is what `form-class` will become for that machine.
(undo-all! {this :com.fulcrologic.rad.form/master-form})
Trigger an undo of all changes on the given form rendering env.
Trigger an undo of all changes on the given form rendering env.
(update-tree* state-map xform component-class component-ident)
Run the given (xform ui-props)
against the current ui props of component-class
's instance at component-ident
in state-map
. Returns an updated state map with the transformed ui-props re-normalized and merged back into app state.
Run the given `(xform ui-props)` against the current ui props of `component-class`'s instance at `component-ident` in `state-map`. Returns an updated state map with the transformed ui-props re-normalized and merged back into app state.
(valid? form-rendering-env)
(valid? form-class-or-instance props)
Returns true if the validator on the form in env
indicates that all of the form fields are valid. Note that a
field does not report valid OR invalid until it is marked complete (usually on blur).
Returns true if the validator on the form in `env` indicates that all of the form fields are valid. Note that a field does not report valid OR invalid until it is marked complete (usually on blur).
(view! this form-class entity-id)
(view! this form-class entity-id extra-params)
Route to the given form in read-only mode.
Route to the given form in read-only mode.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close