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 |
search
(search _ & _)A simple search box component. The action argument is a function of one argument which is executed when the user hits the search button. The argument is the text entered into the search field. The component also accepts a number of optional keyword arguments
| Keyword | Description |
|---|---|
:classes |
A map of strings or vector of strings representing CSS |
class names. Supported keys are :field, :input and |
|
:button |
|
:icon-data |
An icon data map (see theophilusx/yorick/icon) |
:button-text |
Text to be used on the search button. Defaults to |
Search if none provided. Set to nil when you just |
|
want an icon and use :icon-data to set the icon |
|
:attrs |
a map of HTML attribute values. Keys are HTML |
attribute names as keywords e.g. :disabled |
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` |