untangled.ui.forms — navis/untangled-ui 1.0.0-alpha7

assert-or-fail cljs

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

build-form cljs

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

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

Declare a checkbox on a form

commit-state cljs

(commit-state form)

Commits the state of the form to the entity, making it the new original data.

commit-to-entity! cljs

(commit-to-entity! component & {:keys [remote rerender] :or {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.

css-class cljs

(css-class form field)

Gets the css class for the form field

current-validity cljs

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

(current-value form field)

Gets the current value of a field in a form.

DBAdapter cljs protocol

gen-tempid cljs

(gen-tempid this)

Generates a db tempid.

commit! cljs

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

transact! cljs

(transact! this tx)

Execute a transaction!

parse-tx cljs

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

default-state cljs

(default-state fields)

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

diff-form cljs

(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? cljs

(dirty-field? form field)

dirty? cljs

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

(dropdown-input name
                options
                &
                {:keys [default-value className]
                 :or {default-value :untangled.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 cljs

(element-names form)

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

entity-xform cljs

(entity-xform state form-id xf)

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

fail! cljs

(fail! msg)

(fail! msg ex-data)

(fail! obj msg ex-data)

field-config cljs

(field-config form name)

Get the configuration for the given field in the form.

field-type cljs

(field-type form name)

Get the configuration for the given field in the form.

form-component cljs

(form-component form)

Get the UI component that declared the given form.

form-field cljs

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

Function for rendering form fields. Call this to render, but defmethod on form-field*.

form-field* cljs

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

form-field-valid? cljs

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

form-ident cljs

(form-ident form)

Get the ident of this form's entity

form-key cljs

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 cljs

(form-reduce form init F)

(form-reduce form xf init F)

Reduces over a form acquired via om/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 cljs

Query this in your top level form component. Is okay to have multiple 'root' components on screen at once, as om and react will optimize the rendering step.

form-switcher-input cljs

(form-switcher-input field FormClass select-key)

Create a field that understands it points to a to-many list of subforms, only one of which can be interacted with at a time, but all of which will be affected by top-level form operations like commit and validate. Functions like valid? check the validity of the list of subforms when applied to such a field. Rendering such a field requires that you pass the desired value of select-key to select the subform.

get-forms cljs

(get-forms app-state 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-original-data cljs

(get-original-data form)

(get-original-data form field)

Get the unmodified copy of the form state from when it was first initialized.

id-field cljs

(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 cljs protocol

form-spec cljs

(form-spec this)

Returns the form specification, ie: what the form is made of, eg: fields, subforms, form change listeners.

init-form cljs

(init-form app-state 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 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 cljs

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

init-one cljs

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

initialized-state cljs

(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? cljs

(initialized? form)

Returns true if the given form is already initialized with form setup data

integer-input cljs

(integer-input name & options)

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

invalid? cljs

(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? cljs

(is-form? ?form)

is-subform? cljs

(is-subform? element)

(is-subform? form field-key)

Returns whether the element, or the field-key in the form, is a subform.

on-form-change cljs

(on-form-change mut-sym)

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

Add this to your IForm declarations:

(defui ^:once PhoneForm
  static uc/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 cljs

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

(placeholder form field)

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

radio-button-id cljs

(radio-button-id form field choice)

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

radio-input cljs

(radio-input name
             options
             &
             {:keys [default-value className]
              :or {default-value :untangled.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 cljs

(reduce-forms app-state 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 cljs

(reset-entity form)

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

reset-from-entity! cljs

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

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

set-current-value cljs

(set-current-value form field value)

Sets the current value of a field in a form, and marks it as :unchecked.

subform-element cljs

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

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

text-input cljs

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

(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? cljs

(ui-field? form field)

For checking if a field is only a ui concern. eg: should therefore not be sent to the server.

update-current-value cljs

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

Updates the current value of a field in a form (with a fn) and marks it as :unchecked.

update-forms cljs

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

Similar to update-in, 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 is the component that has the form,
• :ident is of the form in app state,
• :form is the value of the form in app state.

valid? cljs

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

(validatable-fields form)

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

validate-entire-form! cljs

(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* cljs

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

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

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

validate-forms cljs

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

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

validator cljs

(validator form field)

Returns the validator symbol from the form field.

form The form props field The field name

validator-args cljs

(validator-args form field)

Returns the validator args from the form field

form The form props field The field name

would-be-valid? cljs

(would-be-valid? form)

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