Form Inputs
checkbox-group
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.
Checkbox Group Arguments
options - an array of strings or objects (with
name
,value
, and optionallysites
)help - description / helper text for the field
validate.required - either
true
or an object that described the conditions that should make this field requiredvalidate.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.
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:
checkbox
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.
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
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 requiredvalidate.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 modetext/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
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 itemItems can be added by clicking the
add
buttonWhen a complex-list is not empty, the focused item will have actions it, with
add
andremove
buttonsItems can be removed by clicking the
remove
buttonItems 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
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
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:
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
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 requiredvalidate.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
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
, ormulti-component
. (defaults tosingle-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 requiredvalidate.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 createdfield
- 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
WISYWIG Data Format
WYSIWYG returns a string of HTML.
inline
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
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
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
orcomponent
. 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) viawindow.kiln.transformers
specify a
transformArg
if you need to send more information to the transform.specify a
store
path orurl
if you need to grab data from somewhere. The request will be prefixed with thestore
/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"
(ノ◕ヮ◕)ノ*:・゚✧ "grab a caption from mediaplay"
(ノ◕ヮ◕)ノ*:・゚✧ "grab the url of the first mediaplay-image on this page"
(ノ◕ヮ◕)ノ*:・゚✧ "grab a list of items keyed by some component uri"
(ノ◕ヮ◕)ノ*:・゚✧ "grab the image url from a lede component, then ask mediaplay for the caption"
(ノ◕ヮ◕)ノ*:・゚✧ "grab the tv show name and use it to automatically format an image url"
(ノ◕ヮ◕)ノ*:・゚✧ "grab an image url from either a mediaplay-image (url) or lede-gallery (ledeImageUrl) (whichever is higher on the page)"
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
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.
Radio Arguments
options - an array of strings or objects (with
name
,value
, and optionallysites
)help - description / helper text for the field
validate.required - either
true
or an object that described the conditions that should make this field requiredvalidate.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.
Radio Data Format
Radio will return a string with the value
of the selected option
.
range
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.
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
valuemaxLabel - label that will be displayed on the right side of the range, defaults to the
max
valuestep - 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
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 defaultoptions - 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 requiredvalidate.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
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 defaultoptions (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 requiredvalidate.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
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
.
select
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 optionallysites
)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 whenmultiple
is falsehelp - 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 requiredvalidate.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.
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
Select 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
.
simple-list
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 keyallowRemove
enables an X in theautocomplete
that allows the user to remove that item from the autocomplete list. If the keyallowCreate
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 requiredvalidate.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
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 backspaceSelect 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 timeDouble-clikcing the "primary" item will unset it as the "primary" item
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
static
A static, non-editable bit of text. Useful for displaying data in a list when only overrides are editable
Static Arguments
help - description / helper text for the field
text - optional interpolated string to use rather than simply printing the value of the property
Static inputs don't have validation.
text
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 tomulti-line
for a multi-line text arearows - 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 requiredvalidate.min - minimum number (for
type=numer
) or length (for other types) that the field must meetvalidate.max - maximum number (for
type=number
) or length (for other types) that the field must not exceedvalidate.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
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 requiredvalidate.requiredMessage - will appear when required validation fails
Timepicker Data Format
Timepicker returns a string with the time in h:mm A
format.
Last updated