com.fulcrologic.rad.form — com.fulcrologic/fulcro-rad 1.1.0-RC1

add-child! clj/s

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

apply-derived-calculations clj/s

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

attr->renderer clj/s

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

auto-create-to-one clj/s

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

calc-diff clj/s

(calc-diff uism-env)

Calculates the minimal form diff from the UISM env of the master form's state machine.

cancel! clj/s

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

computed-value clj/s

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

convert-options clj/s

(convert-options get-class location options)

Runtime conversion of form options to what comp/configure-component! needs.

create! clj/s

(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-action clj/s

default-state clj/s

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

default-to-many clj/s

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

default-to-one clj/s

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

defsc-form clj/s macro

(defsc-form & args)

defsc-form* clj

(defsc-form* env args)

delete! clj/s

(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-child! clj/s

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

If you are rendering the child yourself via the body of a subform UI (which is a defsc-form), then you must set the env at ::form/form-instance to this.

delete-entity clj/s≠

cljs

edit! clj/s

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

edit-action clj/s

field-autocomplete clj/s

(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

field-label clj/s

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

• 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 clj/s

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

field-visible? clj/s

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

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

find-fields clj/s

(find-fields form-class pred)

Recursively walks the definition of a RAD form (form and all subforms), and returns the attribute qualified keys that match (pred attribute)

form-allow-route-change clj/s

(form-allow-route-change this)

form-body clj

(form-body argslist body)

form-container-renderer clj/s

(form-container-renderer form-env)

The top-level container for the entire on-screen form

form-layout-renderer clj/s

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

form-machine clj/s

form-options->form-query clj/s

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

form-pre-merge clj/s

(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

form-will-enter clj/s

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

form-will-leave clj/s

(form-will-leave this)

Checks to see if the UISM is still running (indicating an exit via routing) and cleans up the machine.

global-events clj/s

input-blur! clj/s

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

input-changed! clj/s

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

Using a value of nil will cause the field to become empty in an attribute-aware way:

• If the cardinality is to-one, will be dissoc'd
• Scalar to-many will be set to #{} instead.
• Ref to-many will be set to [] instead.

Furthermore, idents that contain a nil ID are considered nil.

install-ui-controls! clj/s deprecated

Renamed to rad-application/install-ui-controls!

invalid? clj/s

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

leave-form clj/s

(leave-form {:com.fulcrologic.fulcro.ui-state-machines/keys [fulcro-app]
             :as uism-env})

Discard all changes, and attempt to change route.

mark-all-complete! clj/s

(mark-all-complete! master-form-instance)

mark-fields-complete* clj/s

(mark-fields-complete* state-map {:keys [entity-ident target-keys]})

Helper function against app state. This function marks target-keys as complete on the form given a set of keys that you consider initialized. Like form state's mark-complete, but on all of the target-keys that appear on the form or subforms recursively.

mark-filled-fields-complete* clj/s deprecated

(mark-filled-fields-complete* state-map {:keys [entity-ident initialized-keys]})

Mark fields complete. Use mark-fields-complete* instead, but note the signature change.

master-form clj/s

(master-form component)

Return the master form for the given component instance.

master-form? clj/s

(master-form? rendering-env form-instance)

Returns true if the given react element form-instance is the master form in the supplied rendering env.

optional-fields clj/s

(optional-fields form-class)

Returns all of the form fields from a form (recursively) that are not marked ao/required?

parse-long clj/s deprecated

moved to integer.cljs

pathom-plugin clj/s

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

picker-join-key clj/s

(picker-join-key qualified-key)

Returns a :ui/picker keyword customized to the qualified keyword

read-only? clj/s

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

ref-container-renderer clj/s

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

render-field clj/s

(render-field env attr)

Given a form rendering environment and an attrbute: renders that attribute according to its type/style/value.

render-fn clj/s

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

render-layout clj/s

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

rendering-env clj/s

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

resolvers clj

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 clj/s

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

save! clj/s

(save! {this :com.fulcrologic.rad.form/master-form :as form-rendering-env})

Trigger a save on the given form rendering env.

save-as-form clj/s≠

cljs

MUTATION: Run a full-stack write as-if it were the save of a form. This allows you to leverage the save middleware to do all of the save magic without using a form. Useful for implementing simple model updates from action buttons.

Required params:

:root-ident - The ident of the entity to change

And ONE of:

:entity - A flat entity to write at :root-ident :delta - A proper form delta, a map ident->attr-key->before-after-map.

If you specify both, only delta will be used.

This mutation's ok-action will also update the data in the local state.

save-form clj/s≠

cljs

MUTATION: DO NOT USE. See save-as-form mutation for a mutation you can use to leverage the form save mechansims for arbitrary purposes.

save-form* clj

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

standard-action-buttons clj/s

The standard ::form/action-buttons button layout. Requires you include stardard-controls in your ::control/controls key.

standard-controls clj/s

The default value of ::control/controls for forms. Includes a ::done, ::undo, and ::save button.

start-form! clj/s

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

• 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.
• params - Extra parameters to include in the initial event data. The state machine definition you're using will determine the meanings of these (if any). The default machine supports: ** :on-saved fulcro-txn A transaction to run when the form is successfully saved. Exactly what you'd pass to transact!. ** :on-cancel fulcro-txn A transaction to run when the edit is cancelled. ** :on-save-failed fulcro-txn A transaction to run when the server refuses to save the data.

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! clj/s

(undo-all! {this :com.fulcrologic.rad.form/master-form})

Trigger an undo of all changes on the given form rendering env.

update-tree* clj/s

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

valid? clj/s

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

view! clj/s

(view! this form-class entity-id)

(view! this form-class entity-id extra-params)

Route to the given form in read-only mode.

view-action clj/s