item-editing v2.22.2

Item Editing

The package responsible for generating UI to edit Items.

The home of form-gen, the home of FieldEditors, etc..

• Item Form / Form Gen
  • Form Elements
    • Common Form Properties
    • Field Element
      • Inline Item Field Element
    • Copy Element
    • Submit Element
    • Hyper Link Element
    • Image Element
    • Custom Field Element
  • Mechanics and Life Cycle
• Field Editors

Item Form

Forms are generated from nestable JSON coniguration. As with all of items, the configs are completely serializable and contain no in memory functions. All behavior must somehow be described by static configuration.

Form Elements

Common Form Properties

All form elements can contain the following optional properties:

Field Element

Field elements are the primary element of forms. They essentially create an editor to edit a particular field value.

Inline Item Field Element

Configured by the inlineItemOpts property of a field element. When no configuration is specified, the UI will simple be a list of all items stored on the field value with a delete button on each and an add button to add new. For each item, all the fields of that type are added in a row as editors.

Copy Element

Renders text. A copy element may also be represented as just a plain string for convenience. The object form allows access to base element properties such as style.

Submit Element

Says submit, but may be used for any button style element. Interpolations may be used within text.

Hyper Link Element

Renders a standard hyperlink with non dynamic behavior (aka only href not javascript). Both href and text may contain interpolations.

Image Element

Renders an img. Currently no interpolations allowed but this is likely a bug.

Custom Field Element

Renders custom fields (fields not known and named in code).

Mechanics and Life Cycle

Item forms are rendered in specific stages, partially to help with reentry and validation outside of component rendering. The config based to item form is first run the the prepareElementTree function, which recursively evaluates the conditions of the elements against the rootItem and extraCtx (just as in item actions) and a fieldMap (which is passed in order to allow non-code and customField definitions). If the condition for an element doesn't pass it simply isn't returned in the prepped tree. If it does, all interpolations in it's text properties are replaced against the context and any sub-elements or configs (label element, form config, inlineItemOpts.formConfig) are prepared recursively exactly the same way. The result of this phase is a prepped element tree of type IItemPreppedFormElement[]. There are prepped versions of all the element types, because the prepped elements have numerious things replaced or removed before ever rendering.

The form components then somewhat dumbly render the prepped tree (also recursively but simply using components). Whenever, a component renders a prepped element it fires its initActions up the tree (this should eventually be handled outside of the component tree but isn't for now). If it finds in img element it renders an img tag, a submit element renders a button etc. On any change to the properties or state of the form (including field value changes from the rendered editors) the tree is re-prepped and simply rendered again (this is highly efficient because of react's shadow dom and diffing).

When a field element is found, if it is of type ITEM a special <InlineItemFieldFormElement> component is rendered. This component takes care of automatically capturing field value edits from the child field editors within it, writing them into the particular inline item being rendered, and then bubbling the change to that item into the ITEM field's field value up the tree. It also can handle removing an item from or adding an item to the array of inline item field values.

Field Editors

The code responsible for editing the value of one particular field on an item using it's type and options to decide the behavior.

A field editor takes in a field along with a field value and handles rendering the appropriate editor for that field, taking into account any editorType or editorOptions. Editor options and their function are documented in to the item package.

It fires any field value change through an onChange callback. It handles validating the user entered field values and rendering invalid states as danger color borders etc. If a value is valid synchronously (according to the field's validations property), it submits any field value changes to an asyncValidation callback. If the validity value has changed from false to true or vice versa it fires an onValidatyChange callback to alert parent components.

Field editors use the item package's field-processor code to format and render the field values to user readable strings, and to parse user entered strings into raw fieldvalues for saving (when the ui is text based unlike a date select for example). They also run all validations through the field processor. This allows the meat and bones of that logic to be UI agnostic and highly testable, while the editor handles any UI specific concerns for the field. Again see the item package for how field types are treated in regard to format, parse, and validations.

Random Stuff to Later Organize

• all field ids are aggregated from the config and attempted to be fetched before rendering by checkout. currently assumes only the application item and wierd CHECKOUT fields but that must soon change.