fulcro.ui.forms — fulcrologic/fulcro 2.8.0

allowed-input-dom-props clj/s

assert-or-fail clj/s

(assert-or-fail obj pred msg & [ex-data])

build-form clj/s

(build-form form-class entity-state)

Build an empty form based on the given entity state. Returns an entity that is compatible with the original, but that has had form support added. If any fields are declared on the form that do not exist in the entity, then the form will fill those with the default field values for the declared input fields. This function does not recursively build out nested forms, even when declared. See init-form.

checkbox-input clj/s

(checkbox-input name
                &
                {:keys [className default-value] :or {default-value false}})

Declare a checkbox on a form

clj->js clj

commit-state clj/s

(commit-state form-props)

Commits the state of the form to the entity, making it the new original data. Returns new form props (use in a mutation)

commit-to-entity! clj/s

(commit-to-entity! component
                   &
                   {:keys [remote rerender fallback fallback-params]
                    :or {fallback-params {} remote false}})

Copy the given form state into the given entity. If remote is supplied, then it will optimistically update the app database and also post the entity to the server.

IMPORTANT: This function checks the validity of the form. If it is invalid, it will NOT commit the changes, but will instead trigger an update of the form in the UI to show validation errors.

For remotes to work you must implement (f/commit-to-entity {:form-id [:id id] :value {...}) on the server.

This function uses the following functions and built-in mutations (that you can also use to create your own custom commit mutations):

Functions: (validate-fields form) - To get back a validated version of the form (valid? form) - To check that the form is valid (diff form) - Returns a diff of just what has changed in the form (recursive)

Mutations: commit-to-entity - The remote-capable mutation that copies the new state and is sent over the wire. validate-form - Triggered (instead of commit) when the form is invalid (to show validation errors)

Named parameters: remote - True, or the name of the remote to commit to. Can be a local-only commit. fallback - A mutation symbol to run (as a fallback) if there is a commit error. rerender - An optional vector

NOTES:

• If you want commit to do more that remap tempids (e.g. you want a return value from the server), see mutation-merge option of fulcro client.
• Writes always happen before reads in Fulcro (on a single remote). Therefore, you can do this commit AND a load together (sequentially) as a way to gather more information about the commit result. E.g. you could re-read the entire entity after your update by triggering the load with the commit.

css-class clj/s

(css-class form-props field)

Gets the css class for the form field

current-validity clj/s

(current-validity form field)

Returns the current validity from a form's props for the given field. One of :valid, :invalid, or :unchecked

current-value clj/s

(current-value form-props field)

Gets the current value of a field in a form.

DBAdapter clj/s≠ protocol

commit! clj/s

(commit! this params)

Entry point for creating (& executing) a transaction, given params with the same shape as what diff-form returns. Example code for using DBAdapter/commit!: (defmethod your-mutate `forms/commit-to-entity [env k params] (commit! (:adapter env) params))

gen-tempid clj/s

(gen-tempid this)

Generates a db tempid.

parse-tx clj/s

(parse-tx this tx-type data)

Given a tx-type and data, transforms it into a db transaction. OR TODO: Should this be add-tx, set-tx, etc...

transact! clj/s

(transact! this tx)

Execute a transaction!

default-state clj/s

(default-state fields)

INTERNAL METHOD. Get the default state configuration for the given field definitions. MUST ONLY BE PASSED PURE FIELDS. Not subforms.

defvalidator clj/s macro

(defvalidator & args)

Define an form field validator.

The given symbol will be prefixed with the namespace of the current namespace, as if it were def'd into the namespace.

The arglist should match the signature [sym value args], where sym will be the symbol used to invoke the validation, value will be the value of the field, and args will be any extra args that are passed to the validation from field spec configuration.

Should return true if value, false otherwise.

diff-form clj/s

(diff-form root-form)

Returns the diff between the form's current state and its original data. The return value is a map where the keys are the idents of the forms that have changed, and the values are vectors of the keys for the fields that changed on that form.

Return value: {:form/new-entities {[:phone/by-id #phone-id] {...}} :form/updates {[:phone/by-id 1] {:phone/number "123-4567"}} :form/add-relations {[:person/by-id 1] {:person/number #{phone-id-not-ident ...}}} :form/remove-relations {[:person/by-id 1] {:person/number #{4 5}}}}

dirty-field? clj/s

(dirty-field? form field)

dirty? clj/s

(dirty? form)

Checks if the top-level form, or any of the subforms, are dirty. NOTE: Forms remain dirty as long as they have tempids.

dropdown-input clj/s

(dropdown-input name
                options
                &
                {:keys [default-value className]
                 :or {default-value :fulcro.ui.forms/none className ""}})

Declare a dropdown menu selector.

name is the keyword property name of the field options is a vector of f/option items to display

Additional (optional) named parameters are default-value and className. The default-value should be the :key of one of the options (defaults to :f/none).

element-names clj/s

(element-names form-props)

Get all of the field names that are defined on the form.

entity-xform clj/s

(entity-xform state form-id xf)

Modify the form's (under form-id) using update-forms and a passed in transform xf

fail! clj/s

(fail! msg)

(fail! msg ex-data)

(fail! obj msg ex-data)

field-config clj/s

(field-config form-props name)

Get the configuration for the given field in the form.

field-type clj/s

(field-type form-props name)

Get the configuration for the given field in the form.

form-component clj/s

(form-component form-props)

Get the UI component (class) that declared the given form props.

form-field clj/s

(form-field component form field-name & params)

Function for rendering form fields. Call this to render. If you want to add a new form field renderer, then you can do defmethod on form-field*.

form-field* clj/s multimethod

Multimethod for rendering field types. Dispatches on field :input/type.

form-field-valid? clj/s multimethod

Extensible form field validation. Triggered by symbols. Arguments (args) are declared on the fields themselves.

form-ident clj/s

(form-ident form-props)

Get the ident of this form's entity

form-key clj/s

Query this in all of your form components, else form support will fail! (often in subtle/obscure ways, WIP on how to better catch & report this)

form-reduce clj/s

(form-reduce form init F)

(form-reduce form xf init F)

Reduces over a form acquired via prim/props on a component, at each step calls F with each form. init is the initial value for the reduce.

Optionally takes a transducing function as an extra second argument & therefore calls transduce.

form-root-key clj/s

Query this in your top level form component of a nested for set. It is okay to have multiple 'root' components on screen at once, as om and react will optimize the rendering step.

get-form-spec clj/s

(get-form-spec class)

Get the form specification that is declared on a component class. Works in clj and cljs.

get-forms clj/s

(get-forms state-map root-form-class form-ident)

Reads the app state database starting at form-ident, and returns a sequence of :

{:ident ident :class form-class :form form-value}

for the top form and all of its declared subforms. Useful for running transforms and collection across a nested form.

If there are any to-many relations in the database, they will be expanded to individual entries of the returned sequence.

get-on-form-change-mutation clj/s

(get-on-form-change-mutation form field-name kind)

Get the mutation symbol to invoke when the form changes. This is typically used in the implementation of form field renderers as part of the transaction to run on change and blur events.

Returns a valid symbolic data structure that can be used inside of transact:

(prim/transact! `[~@(get-on-form-change-mutation form :f :blur)])

will convert to something like:

(prim/transact! `[(your-change-handler-symbol {:form-id [:form 1] :field :f :kind :blur})])

This function returns a list of mutations expressions to run (which will contain zero or one). Use list unquote to patch it into place.

get-original-data clj/s

(get-original-data form-props)

(get-original-data form-props field)

Get the unmodified value of the form (or field) from when it was first initialized.

html5-input clj/s

(html5-input name type & options)

Declare an input with a specific HTML5 INPUT type. See text-input for additional options. Type should be a string that is a legal HTML5 input type.

id-field clj/s

(id-field name)

Declare a (hidden) identity field. Required to read/write to/from other db tables, and to make sure tempids and such follow along properly.

IForm clj/s≠ protocol

form-spec clj/s

(form-spec this)

Returns the form specification, i.e.: what the form is made of, e.g.: fields, subforms, form change listener.

iform? clj/s

(iform? x)

Returns true if the given class is an IForm. Works on clj and cljs.

init-form clj/s

(init-form app-state-map form-class form-ident)

Recursively initialize a form from an app state database. Will follow subforms (even when top-levels are initialized). Returns the new app state (can be used to swap! on app state atom). Will not add forms where there is not already an entity in the database. If there are subforms, this function will only initialize those that are present AND uninitialized. Under no circumstances will this function re-initialize a form or subform.

app-state-map The map of the current app state. form-class The defui class that defines the top-level form. form-ident The ident of the entity's data in app state.

init-many clj/s

(init-many state base-form subform-spec visited)

init-one clj/s

(init-one state base-form subform-spec visited)

initialized-state clj/s

(initialized-state empty-form-state field-keys-to-initialize entity)

INTERNAL. Get the initialized state of the form based on default state of the fields and the current entity state

initialized? clj/s

(initialized? form)

Returns true if the given form is already initialized with form setup data. Use server-initialized? to detect if it was initialized in clj, which means it won't work right on the UI without being re-initialized.

integer-input clj/s

(integer-input name & options)

Declare an integer input on a form. See text-input for additional options.

invalid? clj/s

(invalid? root-form)

(invalid? form field)

Returns true iff the form or field has been validated, and the validation failed. Using this on a form ignores unchecked fields, so you should run validate-entire-form! before trusting this value on a form.

SEE ALSO would-be-valid? if you'd like to pretend that full-form validation has been run in a query-only sort of way.

root-form is the props of a top-level form. Evaluates form recursively. form is the props of a specific form field is a field to check on a specific form

is-form? clj/s

(is-form? ?form)

Do the given props represent the data for a form? Remember that you must query for f/form-key in your component or your props cannot act as a form.

is-subform? clj/s

(is-subform? form-field-description)

(is-subform? form-props field-key)

Returns whether the form-field description (or the given field by field-key in the form), is a subform.

on-form-change clj/s

(on-form-change mut-sym)

(on-form-change mut-sym refresh)

(on-form-change mut-sym params refresh)

Declare a Fulcro mutation (as a properly namespaced symbol) that will be triggered on each form change. Only one such mutation can be defined for a form.

You may also supply mutation parameters and a refresh list of data that will change and should be refreshed in the UI.

The mutation can do anything, but it is intended to do extended kinds of dynamic form updates/validations.

Add this to your IForm declarations:

(defui ^:once PhoneForm
  static prim/InitialAppState
  (initial-state [this params] (f/build-form this (or params {})))
  static f/IForm
  (form-spec [this] [(f/id-field :db/id)
                     (f/on-form-change 'some-ns/global-validate-phone-form)
                     ...])
...)

When invoked, the target mutation params will include:

:form-id The ident of the form. You may use the app state in env to do anything you want to do (validate, etc.) :field The name of the field that changed :kind The kind of change: :blur The user finished with the given field and moved away from it. :edit The user changed the value. Text fields edits will trigger one of these per keystroke.

option clj/s

(option key label)

Create an option for use in a dropdown. The key is used as your app database value, and label as the label.

placeholder clj/s

(placeholder form-props field)

Returns the current value of the placeholder, which may be a lambda or a string.

radio-button-id clj/s

(radio-button-id form field choice)

Returns the generated ID of a form field component. Needed to label radio buttons

radio-input clj/s

(radio-input name
             options
             &
             {:keys [label-fn default-value className]
              :or {default-value :fulcro.ui.forms/none className ""}})

Declare an input that will render as some number of radio buttons.

name : The field name options : A set of legal values. Can be anything that pr-str and read-string can convert to/from strings.

Radio button rendering is done via the params of form-field. If you declare:

(radio-input :rating #{1 2 3 4 5})

then in your rendering you will render the field five times:

(dom/div nil
  (form-field form :rating :choice 1) 1
  (form-field form :rating :choice 2) 2
  (form-field form :rating :choice 3) 3
  (form-field form :rating :choice 4) 4
  (form-field form :rating :choice 5) 5)

reduce-forms clj/s

(reduce-forms state-map form starting-value form-fn)

Similar to reduce, but walks the forms. Useful for gathering information from nested forms (eg: are all of them valid?). At each form it calls (form-fn accumulator {:keys [ident form class]}). The first visit will use starting-value as the initial accumulator, and the return value of form-fn will become the new accumulator.

Returns the final accumulator value.

reset-entity clj/s

(reset-entity form-props)

Resets the form back to the original state, ie when it was first created/initialized. Returns new props.

reset-from-entity! clj/s

(reset-from-entity! comp-or-reconciler form)

Reset the form from a given entity in your application database using a transaction and update the validation state. You may compose your own transactions and use (f/reset-from-entity {:form-id [:entity id]}) directly.

server-initialized? clj/s

(server-initialized? form)

Returns true if the state of the form's state was set up by server-side rendering. If this is the case on the client then you must call initialize on the form before interacting with it.

set-current-value clj/s

(set-current-value form-props field value)

Sets the current value of a field in a form, and marks it as :unchecked. Returns the new form state (props).

subform-element clj/s

(subform-element field form-class cardinality & {:keys [isComponent]})

Declare a subform as an element of the current form. Used as an entry to a form class's specifiation: It declares that the current form links to subforms through the given entity property in a :one or :many capacity. this must be included in your list of form elements if you want form interactions to trigger across a form group.

Additional named parameters:

isComponent - A boolean to indicate that references to instances of this subform are the only uses of the target, such that removing the reference indicates that the target is no longer used and can be removed from the database. This affects how a diff is reported when calculated for submission.

text-input clj/s

(text-input
  name
  &
  {:keys [validator validator-args className default-value placeholder
          validate-on-blur?]
   :or {placeholder "" default-value "" className "" validate-on-blur? true}})

Declare a text input on a form. The allowed options are named parameters:

:className nm Additional CSS classnames to include on the input (as a string) :validator sym A symbol to target the dispatch of validation :validator-args Arguments that will be passed to the validator :placeholder The input placeholder. Supports a lambda or string :default-value A value to use in the field if the app-state value is nil :validate-on-blur? Should the field be validated on a blur event (default = true)

textarea-input clj/s

(textarea-input name & options)

Declare a text area on a form. See text-input for additional options.

When rendering a text input, the params passed to the field render will be merged with the textarea HTML props.

ui-field? clj/s

(ui-field? form-props field)

Is the given field for use in the UI only?

It is possible that you'd like a UI-only field to participate in a form interaction (e.g. for validation or other interaction purposes). If a field's name is in the ui namespace, then it will never be included in data diffs or server interactions.

update-current-value clj/s

(update-current-value form-props field f & args)

Like update but updates the current value of a field in a form (with a fn f) and marks it as :unchecked. Returns the new form props (e.g. use within a mutation).

update-forms clj/s

(update-forms state-map form form-update-fn)

Similar to update, but walks your form declaration to affect all (initialized and preset) nested forms. Useful for applying validation or some mutation to all forms. Returns the new app-state. You supply a form-update-fn of type (fn [{:keys [ident class form]}] => form), where:

• :class The component class that has the form,
• :ident of the form in app state,
• :form the value of the form in app state.

Returns the updated state map.

valid? clj/s

(valid? root-form)

(valid? form field)

Returns true iff the form or field has been validated, and the validation is ok.

Please make sure you've read and understood the form state lifecycle with respect to validation.

SEE ALSO would-be-valid? if you'd like to pretend that full-form validation has been run in a query-only sort of way.

root-form is the props of a top-level form. Evaluates form recursively. form is the props of a specific form field is a field to check on a specific form

validatable-fields clj/s

(validatable-fields form-props)

Get all of the names of the validatable fields that are defined on the (initialized) form (non-recursive).

validate-entire-form! clj/s

(validate-entire-form! comp-or-reconciler form & {:as opts})

Trigger whole-form validation as a TRANSACTION. The form will not be validated upon return of this function, but the UI will update after validation is complete. If you want to test if a form is valid use validate-fields on the state of the form to obtain an updated validated form. If you want to trigger validation as part of your own transaction (so your mutation can see the validated form), you may use the underlying (f/validate-form {:form-id fident}) mutation in your own call to transact!.

validate-field* clj/s

(validate-field* form field)

Given a form and a field, returns a new form with that field validated. Does NOT recurse into subforms.

validate-fields clj/s

(validate-fields form & [{:keys [skip-unchanged?]}])

Runs validation on the defined fields and returns a new form with them properly marked. Non-recursive.

validate-forms clj/s

(validate-forms app-state-map form-ident & [opts])

Run validation on an entire form (by ident) with subforms. Returns an updated app-state. Usable from within mutations.

validator clj/s

(validator form field)

Returns the validator symbol from the form field.

form The form props field The field name

validator-args clj/s

(validator-args form field)

Returns the validator args from the form field

form The form props field The field name

would-be-valid? clj/s

(would-be-valid? form-props)

Checks (recursively on this form and subforms from prim/props) if the values on the given form would be considered valid if full validation were to be run on the form. Returns true/false.