Skip to content

Editing Components with Forms

Jump to bottom
Nelson Pecora edited this page Jun 26, 2017 · 9 revisions

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

There are three ways Kiln displays forms, governed by the _display property: inline, overlay, and settings. Besides allowing different functionality, certain displays are better for editing certain types of content.

Inline means that the form will replace the content inline. It is best when there's a 1:1 match between how your content looks and how it's edited. Some examples:

  • clicking into a paragraph should display a wysiwyg text editor inline
  • clicking into a header should allow you to edit that header (a single text field) in place
  • clicking on an image should allow you to change that image

Overlay is the default way forms display, and means they'll open up in an overlay pane when clicked. It's best when there's a 1:many match between how your content looks and how it's edited. Some examples:

  • an article headline displays a single line of text, but when editing you want to specify long, short, social, and seo headlines
  • links look like a single line of text, but when editing need a url and title

Settings is a special kind of overlay form that's best when there's a many:many match between how your content looks and how it's edited. Some examples:

  • a social share component allows you to enable or disable a large number of social media services
  • an article has metadata that's never displayed, but is used to generate feeds and gets sent to analytics
  • a feed component specifies the exact elasticsearch query it uses to populate items

Settings

While settings forms look similar to overlay forms, they don't correspond to a data-editable attribute that people can click. Instead, added a settings form will show a gear icon in the component selector, allowing the end user to access it.

Tabbed Form Sections

Overlay and settings forms may also use tabbed sections. Specify them in the fields property of your group by wrapping the section name in parenthesis (similar to how you specify site-specific components in a component list)

_groups:
  settings:
    fields:
      - alt
      - imageLink
      - creditOverride
      - slideshowJSONPath (Slideshow)
      - slideshowButtonText (Slideshow)
      - slideshowType (Slideshow)
      - sass (Custom Styles)

If you specify sections for some fields but leave the other fields blank, they'll be added to a "General" section. Fields and sections will appear in the form in the order they've been listed.

Clone this wiki locally