theophilusx.yorick.input

A collection of convenience functions and components to support obtaining input from the user.

button

(button title action & {:keys [classes attrs]})

A basic button component. The title argument is a string which will be used for the button text. The action argument is a function with no arguments that is called when the button is clicked. The component also supports an optional :classes keyword argument, which is a map of strings or vectors of strings representing CSS class names. The map supports the keys :field, :control and :button. The :attrs optional keyword argument is a map of HTML attributes. Keys for the map are HTML attribute names as keywords e.g. :disabled.

checkbox

(checkbox _ sid & {:keys [model change-fn]})

Provides a basic checkbox component. The label argument is a string used as the label to be associated with the checkbox. The sid argument is a keyword storage identifier used to define the storage key within the document model atom. A number of optional keyword arguments are also supported

Keyword Description
:model a reagent atom to use as the document model for this
checkbox
:change-fn a function of 1 argument called when the input changes to
update the data in the document model
:classes a map of string or vectors of strings representing CSS
class names. Supported keys are :field, :control,
:label and :input
:checked boolean used to set the HTML attribute checked
:attrs a map of HTML attributes. The keys are the HTML attribute
name as a keyword e.g. :required

default-option

(default-option options)

defoption

(defoption title & {:keys [value option-class disabled label selected]})

Define an option for a selection list. The title argument is a string used as the text label for the option. This component supports a number of optional keyword arguments

Keyword Description
:value A value to use when this option is selected
:option-class A string or vector of strings representing CSS classes
:disabled boolean. If true, this option will be disabled
:label A shorter label to be used rather than the title
:selected Boolean. True if this option is to be selected by default

editable-field

(editable-field _ src sid & _)

Provides a utility component which will display a value with a ‘pencil’ icon, which when clicked, will change the displayed value to be a text input area where the value can be edited. Adds a ‘save’ and ‘cancel’ button to save or cancel the edit. The type argument is a keyword representing one of the HTML input types e.g. :text, :email. The src argument is a reagent atom representing the document model atom holding the data to be edited. The sid argument is a storage identifier keyword which specifies the path into the document model atom where the value to edit is stored. This component also supports two optional keyword arguments, :label and :classes. The :label keyword argument is a string which specifies a text label to associate with the field. The :classes keyword argument is a map of strings or vectors of strings representing CSS class names. The map supports the following keys

Key Description
:edit-input CSS classes to associate with the edit input
element
:display-input CSS classes to associated with the div around
display of the value
:save-btn-field CSS classes to associate with the field div
wrapping the save button
:save-btn-control CSS classes to associate with the control div that
wraps the save button
:save-btn-button CSS classes to associate with the save button
element
:cancel-btn-field CSS classes to associate with the field div wrapping
the cancel button
:cancel-btn-control CSS classes to associate with the control div
wrapping the cancel button
:cancel-btn-button CSS classes to associate with the cancel button
:label CSS classes to associate with the label
:field-edit CSS classes to associate with the field when editing
values
:field-edit-body CSS classes to associate with the field body when
editing values
:field-display CSS classes to associate with the field when
displaying values
:field-display-body CSS classes to associate with the field body when
displaying values

field

(field body & {:keys [label classes]})

Generate a field container to hold input labels or fields. The body argument is typically a user input component or a <div> element with the control class. Also supports two optional keyword arguments

Keyword Description
:label A string label to use with the field
:classes A map of strings or vector of strings representing CSS
class names. Supported keys are :field and :label

file

(file sid & {:keys [action model change-fn]})

Provides a basic file selection component. The required sid argument is a storage identifier keyword that determines where the selected filename will be stored within the document model atom. Additional optional keyword arguments are supported:

Keyword Description
:model A reagent atom to be used as the document model store
:change-fn A function of one argument which is called when the input
data changes. The argument is the change event object. This
function is responsible for storing the selected filename(s)
into the document model atom and for calling the action
function to perform some action using the filename
:action A function of 1 argument which is called when a fiile has
been selected. The argument is the File object for the
file which was selected This function is called by the
default change-fn function.
:classes A map of strings or vectors of strings representing CSS
class names. Supported keys are :field, :file, :label
:input and :file-cta
:label The text label to associate with the file selector box
:right Place label to the right of the selection box if true
:fullwidth Use the full width of the surrounding container if true
:boxed Use a boxed version of the upload component. Useful for
managing layout
:size Set the size of the selection box. Possible values are
:small, :medium and :large.
:position Set the position of the select box within enclosing
container. Possible values are :center and :right

horizontal-field

(horizontal-field label body & {:keys [classes]})

Generate a horizontal field with label as the field label and body as the contents of the field. An optional keyword argument of :classes is supported. The value is a map which can contain keys for :label, :field and :body. The value for the keys is either a CSS class name or a vector of CSS class names. CSS class names are strings. The :label key lists classes to be associated with the field label, the :field key for classes associated with the outer field container and the :body for classes associated with the field body element.

input

(input _ sid & {:keys [model change-fn]})

A basic text input component. This component is often used as the body for a field or horizontal-field component. Mandatory arguments are:

Argument Description
type Input type. An HTML input type name as a keyword e.g. :text
sid A storage path keyword e.g. :data.value.

|———-|—————————————————————|

This component also supports a number of optional keyword arguments:

Keyword Description
:model A reagent atom to be used for storing user input
:change-fn A function of 1 argument called when user enters data in
the field.
:classes A map of CSS classes to add to elements in the component.
The value for each key is either a string CSS class name
or a vector of CSS class name strings. Supported keys are
:control and :input
:icon-data Either an icon data map or vector of icon data maps. See
theophilusx.yorick.icon for details on icon data map.
Add sability to add icons to an input component
:attrs A map of HTML attributes. The map keys are the HTML
attribute as a keyword e.g. :required

input-field

(input-field label type sid & {:keys [classes icon-data model change-fn attrs]})

Convenience component which combines field and input components to create a simple input component. The label argument is text to be used assoc the field label. The type argument specifies the input field type. It is a keyword representing one of the HTML5 input types e.g. :text, :email, etc. The sid argument is a storage identifier which specifies the key(s) to use when storing the input in the document model atom. This component also supports a number of optional keyword arguments.

Keyword Description
:classes a map of CSS class name strings or vectors of class name
strings. Supported keys are :field, :label and :input
:icon-data an icon data map or vector of icon data maps. See the
theophilusx.yorick.icon namespace for details
:model A reagent atom to be used as the document model
:change-fn a function of one argument called to update the value
in the document model atom when input changes
:attrs A map of HTML attributes. Keys in the map are the HTML
attribute as a keyword e.g. :required

input-helper

(input-helper type sid doc chg-fn & {:keys [class attrs]})

This function is a helper for text input field components. It is not meant to be called directly, but rather used by other components. The function has the following mandatory arguments:

Argument Description
type The input field type. One of the HTML input types
sid A storage id keyword value used as an spath when storing
input into the doc atom
doc A reagent atom object used to store user input
chg-fun A function of 1 argument which is called whenever input data
changes. The argument is the new value of the input data.

|———–|————————————————————–|

The function also accepts a number of optional keyword arguments:

Keyword Description
:class CSS class names or vector of CSS class names to add to the
input element
:attrs A map of HTML attributes. Each key is the HTML attribute name
as a keyword e.g. :required

number

(number sid & {:keys [model change-fn value]})

A basic number input component. The sid is a storage identifier keyword which sets the location for storing input data in the document model atom. The component also accepts a number of optional keyword arguments:

Keyword Description
:model a reagent atom to be used as the document model store
:change-fn a function of one argument called when the input data
changes. The argument is the new input data.
:value the default value used to initialise the component
:min Set the minimum acceptable value
:max Set the maximum acceptable value
:step The step size for the numbers
:classes a map of strings or vectors of string representing
CSS class names. Supported keys are :control and
:input
:attrs a map of HTML attribute values. Keys are the HTML
attribute names as keywords e.g. :id

number-field

(number-field sid & {:keys [model change-fn value min max step attrs classes label]})

A number input field component. Essentially, this is the number-input component wrapped in a field component. The sid argument is a storage identifier keyword used to determine where the input data will be stored within the document model store. The component supports the following optional keyword arguments:

Keyword Description
:model a reagent atom to use as the document model store
:change-fn a function of 1 argument called when the input data
changes. The argument is the new input data. Used to
update the document model store
:value a default value to use to initialise the component
:min the minimum acceptable value for input
:max the maximum acceptable value for input
:step the step size for number increment/decrement
:classes a map of strings or vectors of strings representing
CSS class names. Supported keys are :field, :label
:control and :input
:label a string to use as the label for the input field
:attrs a map of HTML attribute values. The keys are HTML
attribute names as keywords e.g :id

radio

(radio sid labels & {:keys [model click-fn]})

A radio button component. The sid argument is a keyword used as the storage identifier to store data in the document model atom. The labels argument is a vector of maps specifying each radio button. The map has the following keys

Key Description
:title the text or label to associate with a radio button
:value the value to store in the document model atom when a button
sis elected. If not provided, the title, converted to a
keyword, is used
:checked if true, the button will be rendered checked. Only one of
the button definitions should have this value set to true

The component also supports a number of optional keyword arguments

Keyword Description
:model a reagent atom used as the document model for this
component
:change-fn a function of one argument called when the input changes
to update the document model atom
:classes A map of strings or vector of strings specifying CSS
class names. Supported keys are :control, input and
:label
:attrs a map of HTML attributes. Keys are the HTML attribute
name as a keyword e.g. :required

range-field

(range-field sid _ _ & {:keys [model change-fn value]})

A simple range input component. The sid argument is a storage identifier keyword. The min and max arguments set the minimum and maximum values for the range. A number of optional keyword arguments are supported:

Keyword Description
:model a reagent atom to use as the document model store
:change-fn a function of 1 argument which is called to update the
document model store when input changes. The argument is
the new input data
:value The default value to use as initial value for the range
:label A string label to associate with the range field
:classes A map of strings or vectors of strings representing CSS
class names. Supported keys are :input, :field and
:label
:step Set the step size for the range. Defaults to 1

select

(select sid options & {:keys [model change-fn]})

A basic select list component. The sid argument is a storage identifier keyword. The options argument is a vector of option component representing each option for the select list. Each option can be defined using the defoption function. The component also supports a number of optional keyword arguments

Keyword Description
:model A reagent atom to be used as the document model where
the selected value will be stored
:change-fn A function of one argument that is called when a value
is selected. The argument is the new data value selected
:select-class A string or vector of strings representing CSS class
names to associate with the select element
:multiple Boolean. If true, allow multiple options to be selected
:rounded Boolean. If true, use rounded corners
:select-size Sets the size of the select box. Can be :large,
:medium or :small
:icon-data An icon-data map defining an icon to include with the
select box (see theophilusx/yorick/icon
:size Number of options to display in select box
:attrs a map of HTML attribute values. The keys are the HTML
attribute as a keyword e.g. :disabled

select-field

(select-field sid options & {:keys [title classes multiple rounded select-size icon-data model change-fn attrs]})

This component is a convenience component which wraps a select component inside a field div to ensure appropriate spacing and layout. The sid argument is a storage identifier keyword. The options argument is a vector of option elements (see defoption for details). The following optional keyword arguments are also supported

Keyword Description
:title A string used as the label to associated with the select
box
:classes A map of string or vectors of strings representing CSS
class names. The following keys are supported - :field,
:title and :select
:multiple A boolean which if true allows multiple options to be
selected
:rounded A boolean which if true will set rounded corners on
select box
:select-size Specifies the size of the select box. Possible values are
:small, :medium and :large.
:icon-data An icon definition map. See theophilusx/yorick/icon for
details.
:model A reagent atom used as the document model store
:change-fn A function of one argument called when the input data
changes. The argument is the new data value
:attrs a map of HTML attribute values. Keys are HTML attribute
names as keywords e.g. :disabled

textarea

(textarea _ sid & {:keys [model change-fn]})

A basic text area component. The label argument is a string containing the text to be used as a label for the text area. The sid argument is a storage identifier keyword used to determine where the data entered is stored within the document model atom. The component supports the following optional keyword arguments

Keyword Description
:model A reagent atom representing the document model used to
store input
:change-fn A function of one argument called when the data changes.
The argument is the new data.
:classes A map of CSS class names or vectors of CSS class names
which are added to component elements. Supported keys are
:field, :label and ’:textarea| |:attrs| a map of HTML attribute values. The keys are the HTML | | | attribute name as a keyword e.g.:placeholder`