Editing Components with Forms

Editing Components with Forms

The main way people interact with components is through forms. These allow you to edit single fields, groups of fields, and component settings in a consistent and manageable way. The simplest possible form is a single field in the schema:

title:
  _has: text

And a corresponding data-editable attribute in the template:

<span data-editable="title">{{ title }}</span>

When someone clicks on the title, a form will open with a single text input, allowing them to edit it.

Behaviors

Each field in a form is composed of "behaviors": Small, self-contained templates with styles and logic that can be combined together. Kiln has many built-in behaviors, and custom behaviors can be added through the API.

To add behaviors to a field, list them in the order they should display in the UI:

title:
  _has:
    - label
    - required
    -
      fn: description
      value: A concise description of this field
    -
      fn: wysiwyg
      type: single-line
      buttons:
        - bold
        - italic

As you can see, Kiln provides some syntactical sugar to make writing behaviors easier. They can be specified as strings, objects, or arrays of objects, depending on how complex your field is.

# if you have a single behavior with no arguments, you can simply use a string
hasOneBehaviorWithNoArguments:
  _has: text

# if you have a single behavior but it has arguments, use an object
hasOneBehaviorWithArguments:
  _has:
    fn: text # fn points to the behavior, e.g. behaviors/text.js
    required: true

# if you have multiple behaviors, use an array
hasMultipleBehaviors:
  _has:
    - label
    - text

# you can mix and match strings (behaviors without arguments) and objects (behaviors with arguments) in your arrays
hasMultipleBehaviorsWithArguments:
  _has:
    - label
    - required
    -
      fn: description
      value: Write stuff here
    -
      fn: text
      type: url

Field Label

By default, field labels (in forms, validation messages, and other places) will use the name of the field. You may specify a different label by adding _label to a field:

title:
  _label: Post Title
  _has:
    - label
    - text

The label behavior (and any other place where the field name would display) will now use "Post Title" instead of simply "Title".

Display