Form Inputs

`checkbox-group`

A group of checkboxes, allowing the user to toggle on or off related items. You can specify site-specific options, similar to components in a component-list. Uses Keen's UICheckboxGroup.

    input: checkbox-group
    options:
      - foo (site1)
      - bar (not: site1)
      - baz (site1, site2)

Checkbox Group Arguments

options - an array of strings or objects (with name, value, and optionally sites)
help - description / helper text for the field
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

If you specify options as strings, the label for each will simply be the option converted to Start Case. If this behavior is run on a site with no available options, an error message will appear. Please use _reveal on the field to conditionally hide/show it based on site.

field1:
  _has:
    input: checkbox-group
    options:
      - foo
      -
        name: Bar
        value: bar
      -
        name: Baz Qux
        value: baz-qux
        sites: site1, site2

Checkbox Group Data Format

Checkbox group formats its value as an object, where each option is a key with a true / false value. For example, the data for the options above (foo, bar, baz-qux) might look like:

{
  foo: true,
  bar: false,
  'baz-qux': true
}

`checkbox`

A single checkbox, allowing the user to toggle something on or off. Uses Keen's UICheckbox.

In practice, it's usually best to use a conversational tone / question as the checkbox label, e.g.

field1:
  _label: Should we use a special logo in this component?
  _has: checkbox

Checkbox Arguments

help - description / helper text for the field

Single checkboxes don't have validation.

Checkbox Data Format

Checkbox data is a boolean, true or false.

`codemirror`

A syntax-highlighted text area. Useful for writing css, sass, yaml, or other code in the editor.

Codemirror Arguments

mode (required) the language used
help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

The mode of the editor sets syntax highlighting, linting, and other functionality. Currently, we support these modes:

text/css - css mode
text/x-scss - sass/scss mode (useful for per-instance styles)
text/x-yaml - yaml mode (useful for writing elasticsearch queries)

We will add more supported modes as we find use cases for them. See the full list of modes supported in codemirror.

Codemirror Data Format

Codemirror inputs, no matter what mode you select, will return a string of plaintext.

`complex-list`

An array of objects with arbitrary properties. Each property may have any inputs a field is allowed to have, including custom inputs. Complex-list is similar to Angular's transcluded directives or Advanced Custom Fields' repeater field, in that each item in the list is treated like a separate field. Like fields, items must also have _label, but may not have _placeholder.

Complex List Arguments

props an array of objects, representing the fields in each item. Each item should have a name, defined by prop: 'name', as well as _label and the input that item uses.
collapse a property that should be used as the title for items. If collapse is set, all but the current item will be collapsed, only displaying its title. This is useful for lists with lots of complicated items.
filter boolean determining if the items may be filtered. If true, will add a search box at the top of the list.
enforceMaxlength - boolean preventing user from adding items when list is at max length (from validate.max)

Complex List Usage

When a complex-list is empty, it will display a add button to add the initial item
Items can be added by clicking the add button
When a complex-list is not empty, the focused item will have actions it, with add and remove buttons
Items can be removed by clicking the remove button
Items can be reordered by clicking the up and down carets next to their location
If complex-list is filterable, typing in the search box will match all text inputs in the list items

links:
  _has:
    input: complex-list
    collapse: title
    filter: true
    props:
      -
        prop: url
        _label: URL
        _has:
          input: text
          type: url
      -
        prop: title
        _label: Title
        _has: text

Complex lists don't have any of the common shared arguments, and don't display a field label.

Complex List Data Format

Complex lists will always return an array of objects, where each object has the properties defined as props in the Schema.

`csv`

A button that allows uploading CSV data. Note: the data isn't editable once it's uploaded, but should be re-uploaded from a CSV file when it needs to be changed.

CSV Arguments

delimiter - alternate delimiter (defaults to comma, of course)
quote - alternate quote to use (defaults to one double-quote)
help - description / helper text for the field

Note: Certain spreadsheet editors like Google Spreadsheets will use triple-quotes if you use both quotes and commas in your cells. Make sure you account for that by changing the quote argument:

_has:
  input: csv
  quote: '"""'

CSV buttons don't have validation or attached buttons.

CSV Data Format

CSV inputs will format data as an *array of objects, where each object corresponds to a row and each object's keys are derived from the CSV's column headers.

`datepicker`

A material design calendar picker. Allows specifying minimim and maximum dates. Uses Keen's UIDatepicker.

Datepicker Arguments

help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.min - minimum date, specified in YYYY-MM-DD
validate.max - maximum date, specified in YYYY-MM-DD
validate.requiredMessage - will appear when required validation fails
validate.minMessage - will appear when minimum validation fails
validate.maxMessage - will appear when maximum validation fails

Datepicker Data Format

Datepicker returns a string with the date in YYYY-MM-DD format.

`wysiwyg`

A multi-line text input which allows a rich editing experience. Uses Quill. Inline inputs (which can only be wysiwyg) have the same arguments as normal wysiwyg, but will inherit styles from their parent component.

WYSIWYG Arguments

buttons - array of button names (strings) or groups (arrays) for text styling, passed directly into Quill (defaults to "remove formatting")
type - single-line, multi-line, or multi-component. (defaults to single-line)
pseudoBullet - boolean to enable tab to create pseudo bullet points
paste - array of paste rules for parsing pasted content and creating new components
help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.min - minimum length that the field must meet
validate.max - maximum length that the field must not exceed
validate.pattern - regex pattern
validate.requiredMessage - will appear when required validation fails
validate.minMessage - will appear when minimum validation fails
validate.maxMessage - will appear when maximum validation fails
validate.patternMessage - will appear when pattern validation fails (very handy to set, as the default message is vague)

The buttons allowed in our wysiwyg behavior are defined in Quill's documentation

The default type -- single-line -- allows entering one line of rich text, but prevents users from creating new paragraphs or applying paste rules.

multi-line is used for components like blockquotes or lists, and allows paste rules to create new block-level elements in the same component's field (but not create different components).

multi-component (which is usually used when the input is inline, but may be used in normal wysiwyg inputs) enables more affordances, including:

keyboard navigation across components (up and down arrows)
enter creating new components (and splitting text in front of the cursor into them)
delete removing components (and merging text in front of the cursor into the previous component)
full paste rule affordances, including creating different components

Paste is an optional array of pasting rules that's used for parsing and creating different components. This is useful for transforming pasted links into embeds, catching pasted blockquotes, etc. Rules have these properties:

match - regex to match the pasted content. all rules will be wrapped in ^ and $ (so they don't match urls inside links in the content)
matchLink - boolean to determine whether links containing the regex should also match. Should be true for embeds, false for components that could potentially contain links inside them.
component - the name of the component that should be created
field - the name of the field that the captured data should be populated to on the new component. the (last) new component will focus this field after it's added (note: this is limited to a single regex capture group)
group - (optional) the group that should be focused when the (last) new component is added (instead of the specific field). this is useful for components with forms that contain both the specified field and other things, and preserves the same editing experience as editing that component normally

paste:
  - match: (https?://twitter\.com/\w+?/status/\d+)
    matchLink: true
    component: clay-tweet
    field: url
  - match: (https?://www\.facebook\.com/.+?/posts/\d+)
    matchLink: true
    component: clay-facebook-post
    field: url
    group: inlineForm
  - match: <blockquote>(.*?)(?:</blockquote>)?
    component: blockquote
    field: text
  - match: (.*)
    component: clay-paragraph
    field: text

WISYWIG Data Format

WYSIWYG returns a string of HTML.

`inline`

A multi-line text input which allows a rich editing experience, but appears inline rather than in a form. It will inherit styles from the component you're editing, rather than looking like a Kiln text input. It supports exactly the same arguments and returns the same format as wysiwyg.

`lock`

Appends a lock button to an input. The input will be locked until the user clicks the lock button. This provides a small amount of friction before editing important (and rarely-edited) fields, similar to macOS's system preferences.

`magic-button`

Append a magic button to an input.

Magic Button Arguments

field - a field to grab the value from (in the current complex list, form, or component)
component - a name of a component to grab the component ref/uri from
transform - a transform to apply to the grabbed value
transformArg - an argument to pass through to the transform
store - to grab data from the client-side store
url - to get data from
property - to get from the returned data
moreMagic - to run the returned value through more transforms, api calls, etc
tooltip - text that will display in a tooltip. used to explain what each button is doing, so make it concise!

Magic Button Usage

☆.。.:・°☆.。.:・°☆.。.:・°☆.。.:・°☆

Magic buttons are extremely powerful, but can be a little confusing to configure. This is what they generally look like:

specify a field or component. The button will grab the value or ref, respectively. If you specify either as an array, it will look for the first field/component, then fall back to the next ones specified in the array if necessary (if the field is empty, or the component isn't on the page)
specify a transform. Transforms are useful when doing api calls with that data. You may add custom transformers (or overwrite built-in ones) via window.kiln.transformers
specify a transformArg if you need to send more information to the transform.
specify a store path or url if you need to grab data from somewhere. The request will be prefixed with the store/url string you pass in.
specify a property to grab from the result of that api call. You can use _.get() syntax, e.g. foo.bar[0].baz. If you specify as an array, it will grab the first property in the array that's not empty in the component above.
add moreMagic if you need to do anything else to the returned data

All of these arguments are optional!

Here are some examples:

Note: MediaPlay is the name of our image server.

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "just grab the primary headline"

field: primaryHeadline
tooltip: Use Primary Headline

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab a caption from mediaplay"

field: url
transform: mediaplayUrl (to change the image url into a string we can query mediaplay's api with)
url: [mediaplay api url]
property: metadata.caption
tooltip: Fetch caption from Mediaplay

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab the url of the first mediaplay-image on this page"

component: mediaplay-image
store: components
property: url
tooltip: Fetch First Image

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab a list of items keyed by some component uri"

component: mediaplay-image
transform: getComponentInstance (this transforms the full component uri into a ref we can pop onto the end of our site prefix)
url: $SITE_PREFIX/_lists/images (this is a ~ special token ~ that evaluates to the prefix of current site, so you can do api calls against your own clay instance)
tooltip: Fetch Images

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab the image url from a lede component, then ask mediaplay for the caption"

component: feature-lede
store: components
property: imgUrl
moreMagic:
  -
    transform: mediaplayUrl (to change the image url into a string we can query mediaplay's api with)
    url: [mediaplay api url]
    property: metadata.caption
tooltip: Fetch Caption For Lede Image

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab the tv show name and use it to automatically format an image url"

field: showName
transform: formatUrl
transformArg: [base image url]/recaps-$DATAFIELD.png ($DATAFIELD is the placeholder in our formatUrl transform)
tooltip: Fetch TV Show Image

(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧ "grab an image url from either a mediaplay-image (url) or lede-gallery (ledeImageUrl) (whichever is higher on the page)"

component:
  - mediaplay-image
  - lede-gallery
store: components
property:
  - url
  - ledeImageUrl
tooltip: Fetch First Image

Options may also contain a _reveal property containing rules for when it should display. The config is the same as the field-level _reveal property.

☆.。.:・°☆.。.:・°☆.。.:・°☆.。.:・°☆

`radio`

A group of radio buttons, allowing the user to select one of a few related options. You can specify site-specific options, similar to components in a component-list. Uses Keen's UIRadioGroup.

    input: radio
    options:
      - foo (site1)
      - bar (not: site1)
      - baz (site1, site2)

Radio Arguments

options - an array of strings or objects (with name, value, and optionally sites)
help - description / helper text for the field
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

field1:
  _has:
    input: radio
    options:
      - foo
      -
        name: Bar
        value: bar
      -
        name: Baz Qux
        value: baz-qux
        sites: site1, site2

Radio Data Format

Radio will return a string with the value of the selected option.

`range`

A slider that allows selecting between a range of numerical values. May use two points (known as a dual-point range). Uses noUISlider under the hood, styled based on KeenUI's slider.

    input: range
    min: 0
    max: 10

Range Arguments

start - default value, or an array of two values (for dual-point ranges)
min - hardcoded minimum value selectable in the range, defaults to 0
max - hardcoded maximum value selectable in the range, defaults to 10
minLabel - label that will be displayed on the left side of the range, defaults to the min value
maxLabel - label that will be displayed on the right side of the range, defaults to the max value
step - define step increments, defaults to 1,
tooltips - boolean that determines whether value tooltips will display above the points, defaults to true
help - description / helper text for the field
validate.min - minimum value allowed
validate.max - maximum value allowed
validate.minMessage - will appear when minimum validation fails
validate.maxMessage - will appear when maximum validation fails

Note that you should use min/max to set the hardcoded limits for the range input and validate.min/validate.max to set a (more limited) publishable range, if necessary.

Range Returned Value

If you specify the start as a single (numerical) value, Range will return a single number. If you specify the start as an array of two (numerical) values, Range will return an array of numbers with two values. Note that the start value and the data of this input's value must be of the same type. This input will error if start is an array and the value passed from the component data is a number, or vice versa.

`segmented-button`

A group of buttons allowing the user to select one (or more!) of a few related options.

Segmented Button Arguments

multiple - allow multiple things to be selected. false by default
options - an array of options
help - description / helper text for the field
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

Each option should be an object with icon, text, and value properties. Icons will be displayed in the buttons, and text will be used for tooltips.

Segmented Button Data Formats

By default (when multiple is false or unset), this will return data as a string with the value of the selected option. If multiple is true, this will return an object where each option is a key with a true / false value. Note that the single-select mode is the same format as a radio input, and the multi-select mode is the same as a checkbox-group.

`segmented-button-group`

A group of segmented buttons allowing the user to select one (or more!) of a few related options.

Segmented Button Group Arguments

multiple - allow multiple things to be selected. false by default
options (required) an array of options
help - description / helper text for the field
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

Each option should be an object with title and values properties. The values should be an array of objects with icon, text, and value properties, which will be passed into each segmented-button.

Options may also contain a _reveal property containing rules for when they should display. The config is the same as the field-level _reveal property.

Segmented Button Group Data Formats

`select`

An enhanced browser <select> element, allowing the user to select one (or more!) of a few related options. Uses Keen's UISelect.

Select Arguments

multiple - allow multiple options to be selected. data will be an object with options as keys, similar to checkbox-group
search - allow users to type stuff in to filter options. Extremely useful for longer options lists
list - The key list is where the value is the name of a list that Amphora knows about accessible via /<site>/_lists/<listName>.
options - an array of strings or objects (with name, value, and optionally sites)
keys passthrough option for Keen to specify keys for input objects, especially for use when you don't control the input shape, e.g. lists. Defaults to {label: 'name', value: 'value'}
storeRawData normally only the value of each option is stored, but with this option you can store the entire input object. note that this only works when multiple is false
help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

field1:
  _has:
    input: select
    options:
      - foo
      -
        name: Bar
        value: bar
      -
        name: Baz Qux
        value: baz-qux
        sites: site1, site2

Usage Notes

you may have a value for a 'None' option. this is useful for components that have defaults that you want to be able to revert to after selecting an option
your "default" value may use the label 'None' or 'Default'
if a 'None' option is not specified, it is generated and you don't need to specify an empty option in the schema
you can specify site-specific options, similar to components in a component-list

fn: select
options:
  - foo (site1)
  - bar (not: site1)
  - baz (site1, site2)
  # ...

specialFeature:
  fn: select
  options:
    - name: None
      value: General
    - name: Interview
      value: interview
    - name: Slideshow
      value: slideshow
    - name: Live Blog
      value: live-blog

Select Data Formats

`simple-list`

An array of strings (or objects with a text property, if you add the propertyName argument). Useful for lists of items such as tags, keywords, or author names.

Simple List Arguments

propertyName - appends double-click functionality to items in the list. The data will be an array of objects with text properties, as well as the value of this argument. e.g. propertyName: bar will make the data look like [{ text: 'foo', bar: 'baz' }]
badge - name of the icon (or a two-character string) that should be displayed in the simple list item when editing. Icon names can be anything from the Material Design Icon Set, or you can use two initials
allowRepeatedItems - allow the same item more than once. defaults to false
ignoreComma - do not listen for comma key input to deliminate list items. defaults to false
autocomplete - object with autocomplete options. The key list is where the value is the name of a list that Amphora knows about accessible via /<site>/_lists/<listName>. The key allowRemove enables an X in the autocomplete that allows the user to remove that item from the autocomplete list. If the key allowCreate is set to true, Kiln will add the item to the list via the store.
help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.max - maximum number of items that the field must not exceed
validate.requiredMessage - will appear when required validation fails
validate.maxMessage - will appear when maximum validation fails

  -
    fn: simple-list
    autocomplete:
      list: authors

Simple List Usage

Type something and press enter, tab, or , (comma) to add it as an item
Delete items by clicking the x button or selecting them and pressing backspace
Select items using → / ← or tab and shift + tab. You may select the last item in the list from the text input
Pressing backspace in an empty text input will select the last item in the list
If propertyName is defined, you can double-click items to set the "primary" item. This will add a badge to the primary item. Only one item may be "primary" at a time
Double-clikcing the "primary" item will unset it as the "primary" item

tags:
  _label: Tags
  _has:
    input: simple-list
    propertyName: featureRubric
    badge: FR # or, say, `star` if you want to use a material design icon
    autocomplete:
      list: tags

Simple List Data Format

Simple List will format data as an array of objects, where each object has a text property. If the propertyName argument is set, each object will also have a property (denoted by the value of the propertyName argument) that will be a boolean. Only one of the objects (the "primary item") will have this custom property set to true.

`static`

A static, non-editable bit of text. Useful for displaying data in a list when only overrides are editable

title:
  _label: Title from Service
  _has: static
titleOverride:
  _label: Title Override
  _has: text

Static Arguments

help - description / helper text for the field
text - optional interpolated string to use rather than simply printing the value of the property

title:
  _label: Title from Service
  _has:
    input: static
    text: ${title} (generated)
    help: Non-editable title

Static inputs don't have validation.

`text`

A basic text input. Can be single line or multi-line. Uses the float label pattern. Uses Keen's UITextbox.

Text Arguments

type - input type, which can match any native <input type=""> or can be set to multi-line for a multi-line text area
rows - number of lines the textarea should have. to be used with multi-line
step - define step increments (for numberical inputs only)
enforceMaxlength - prevent user from typing more characters than the maximum allowed (from validate.max)
help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.min - minimum number (for type=numer) or length (for other types) that the field must meet
validate.max - maximum number (for type=number) or length (for other types) that the field must not exceed
validate.pattern - regex pattern
validate.requiredMessage - will appear when required validation fails
validate.minMessage - will appear when minimum validation fails
validate.maxMessage - will appear when maximum validation fails
validate.patternMessage - will appear when pattern validation fails (very handy to set, as the default message is vague)

Text Data Formats

Most text inputs format data as a string of plaintext. If type is set to number, data will be a number.

`timepicker`

A basic time picker. Uses native time inputs when available, but falls back to relatively-simple natural language parsing.

Timepicker Arguments

help - description / helper text for the field
attachedButton - an icon button that should be attached to the field, to allow additional functionality
validate.required - either true or an object that described the conditions that should make this field required
validate.requiredMessage - will appear when required validation fails

Natural Language Parsing

On browsers without native time pickers, users may enter in the time without worrying about the format. The simple NLP engine can handle things like "10am", "4:15 PM", "13:00", and even "midnight".

Timepicker Data Format

Timepicker returns a string with the time in h:mm A format.

PreviousEditing Components NextDeep Linking

Last updated 5 years ago