HBP-QuickFire

HBP-QuickFire is a React components library built on top of MobX and React-Bootstrap.

Its goal is to provide a set of useful react components that let you build a consistent user interface with very little boilerplate code. The main focus of the framework is to provide a simple but powerful entry forms management for React applications.

A documentation application is available here : https://hbp-quickfire.apps.hbp.eu/

The source code is available here : https://github.com/HumanBrainProject/hbp-quickfire

Installation:

npm i -s hbp-quickfire

Peer dependencies

In order to use hbp-quickfire in an application, the following peer dependencies need to be installed:

• mobx >=4.0
• mobx-react >=5.0
• react >=15.4.0
• react-dom" >=15.4.0
• react-bootstrap >=0.32

Getting started

HBP-QuickFire form mechanism is based on a declarative configuration of the form structure as a Javascript (or JSON) Object, like so:

{
  fields:{
    username: {
      type: "InputText",
      label: "Your username"
    },
    age: {
      type: "InputText",
      label: "Your age",
      inputType: "number"
    },
    preferedColor: {
      type: "InputText",
      label: "Your prefered color",
      inputType: "color",
      value: "#FF0000"
    }
  }
}

Once this object matching your form data structure this object is provided to a FormStore instance provided by this library, you can use this store object and provide it to the <Form/> component. HBP-QuickFire lets you decide how you want to layout your form, or you can use one of the provided automatic layout (feature coming soon...). Check the example below:

import React from "react";

import { observer } from "mobx-react";
import { Row, Grid, Col } from "react-bootstrap";
import { Form, FormStore, Field } from "hbp-quickfire";

let peopleFormStructure = {...}; //See example definition above

@observer
export default class PeopleForm extends React.Component {
  constructor(props) {
    super(props);

    this.formStore = new FormStore(peopleFormStructure);
  }

  render() {
    return (
      <Form store={this.formStore}>
        <Grid>
          <h2>People Form</h2>
          <Row>
            <Col xs={4}>
              <Field name="username" />
            </Col>
            <Col xs={4}>
              <Field name="preferedColor" />
            </Col>
            <Col xs={4}>
              <Field name="age" />
            </Col>
          </Row>

          <h2>Result</h2>
          <Row>
            <Col xs={12}>
              <pre>{JSON.stringify(this.formStore.getValues(), null, 4)}</pre>
            </Col>
          </Row>
        </Grid>
      </Form>
    );
  }
}

See this example live

Getting the form data

At any time (e.g. when submitting the form), the getValues() method of the FormStore object returns the processed field values in a structured object matching the definition.

Documentation

To get a more detailed documentation with plenty of examples open a console in the package root and run:

npm install

Then change your current directory to ./docs/ and run :

npm install
npm run start

API Documentation

You can also find the API documentation below:

Table of Contents

• Stores
  • FormStore
    • getValues
    • values
    • values
    • injectValues
    • reset
    • update
    • parentPath
    • genSiblingPath
    • prefetchOptions
    • validate
    • registerCustomValidationFunction
    • registerAxiosInstance
    • toggleReadMode
  • ClipboardStore
    • reset
• Form
  • values
• FormFields
  • InputTextField
    • Options
  • InputTextMultipleField
    • Options
  • TextAreaField
    • Options
  • NestedField
    • NestedRemoveButton
    • NestedMoveUpButton
    • NestedMoveDownButton
    • NestedDuplicateButton
    • Options
    • addInstance
    • duplicateInstance
    • moveInstance
    • removeInstance
  • SelectField
    • Options
  • DropdownSelectField
    • Options
  • TreeSelectField
    • Options
  • CheckBoxField
    • Options
  • GroupSelectField
    • Options
  • DataSheetField
    • HeaderOptions
  • Slider
    • Options
  • FieldLabel
• SingleField
• ActionIcon
• GenericList

Stores

Define stores namespace.

FormStore

Mobx store to manage the Form React Component

Parameters

• structure json the underlying form definition

getValues

Get the form field values

Parameters

• fields
• applyMapping (optional, default true)

Returns object a structured object of the form field values

values

Syntaxic shortcut accessor that calls getValues

values

Syntaxic shortcut accessor that calls injectValues

Parameters

• values object structured object of the form field values

injectValues

Inject values into form fields, must be input the same format as valuesmethod output

Parameters

• values object structured object of the form field values
• merge boolean whether or not to reset the whole form or merge with the passed in values (optional, default false)
• fields
• path string base path for change

reset

Parameters

• fields
• basePath string optional, base path to reset from Resets the form to their default values from the base path or completely if no path is provided

update

updates the underlying field definition

Parameters

• path string the field path
• updated object the updated field definition

parentPath

returns the parent path for a field

Parameters

• field (string | field) can be either be a field path or a field object

genSiblingPath

Parameters

• field (string | field) can be either a field path or a field object
• name string name of the sibling

prefetchOptions

Parameters

• optionsUrls array an array of URLs to fetch and put in cache
• axiosInstance

validate

validates all form fields at once

registerCustomValidationFunction

registers a custom validation functions that can be used in all fields

Parameters

• name string a name to uniquely identify the rule
• func function The definition of the validation function. The function parameters are the field value and attribute name. Can be a sync or async function. Expected return value either boolean or promise, indication if validation was successful.
• errorMessage string The error message in case the validation fails
• formStore

registerAxiosInstance

registers a custom axios instance - useful for APIs requiring tokens

Parameters

• axiosInstance object a valid axios instance

toggleReadMode

toggles or force readMode to display form values as pure text instead of input fields

Parameters

• status boolean optional, a boolean indicating what the readMode state should be. If none is passed then the state is toggled

ClipboardStore

A Store handling a virtual clipboard of text selected inside the current browser window. Importing this module will always return the same instance of that store

reset

Clear the value stored in the virtual clipboard

Form

Form component that wraps the underlying Fields

Properties

• store object required - An instance of the FormStore class

values

Get the form field values

Returns object a structured object of the form field values

FormFields

Field is a generic react component that supports all kinds of different input types

Properties

• name string required - Name of the field as defined in the definition object passed to the FormStore
• onChange function Event handler triggered when changes occur to the underlying field value

InputTextField

A simple text input

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "InputText"
• value string "" - The current value of the field
• defaultValue string "" - The defaultValue of the field
• inputType string "text" - The input type of the field (e.g. text, password, email)
• autoComplete boolean false - Sets the autocomplete attribute of the input element
• placeholder string "" - A placeholder that is displayed when the field is empty
• path string "" - Field path
• useVirtualClipboard boolean false - Flag if virtual clipboard feature is enabled for this field
• emptyToNull boolean true - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input
• validationRules array [] - A list of validation rules
• customErrorMessages object {} - Definition for custom error messages in the form: {rule: errorMessage}
• validationOptions object {onBlur: true, onChange: false} - Validation options to define when validation is executed

InputTextMultipleField

Allows the input of multiple values

Options

Parameters

• label string "" - The field label
• type string "InputTextMultiple"
• value array [] - The current value of the field
• defaultValue array [] - The defaultValue of the field
• path string "" - Field path
• max number Infinity - Maximum values that the field can have
• useVirtualClipboard boolean false - Flag if virtual clipboard feature is enabled for this field
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readAndDeleteOnly boolean false - Is the field readAndDeleteOnly or not, a readAndDeleteOnly field will allow deletes but won't be writable for new values, but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

TextAreaField

Textarea input field. Field options are the same as for the InputTextField

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "InputText"
• value string "" - The current value of the field
• defaultValue string "" - The defaultValue of the field
• path string "" - Field path
• emptyToNull boolean true - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input
• autosize boolean true - If true, the textarea resizes automatically
• rows number 1 - How many rows are displayed by default. Represents the min value
• maxRows number null - How many rows are displayed at most before the field does not grow anymore (only possible if autosize is enabled)
• resizable boolean false - If true, the textarea is horizontally resizable by the user

NestedField

Allows the implementation of a nested field structure

NestedRemoveButton

Action button to remove a nested instance, has to be called by the app with <Field.Remove/> component

NestedMoveUpButton

Action button to move up a nested instance in the list, has to be called by the app with <Field.MoveUp/> component

NestedMoveDownButton

Action button to move down a nested instance in the list, has to be called by the app with <Field.MoveDown/> component

NestedDuplicateButton

Action button to duplicate a nested instance in the list, has to be called by the app with <Field.Duplicate/> component

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• buttonLabel string "Add an item" - The label used for adding an item to the repeatable fields
• type string "Nested"
• min number 1 - min of nested children the field can have
• max number 1 - max of nested children the field can have
• fields object {} - The nested fields definitions
• value string [] - The value of the field
• defaultValue array [] - The defaultValue of the field
• path string "" - Field path
• topAddButton string true - Whether or not to display the Add button before the fields
• bottomAddButton string true - Whether or not to display the Add button after the fields
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

addInstance

add a new instance to a nested field

duplicateInstance

duplicates a nested instance at a given index

Parameters

• index integer the instance to duplicate index

moveInstance

move a nested instance at a given index to a new given index

Parameters

• index integer the instance to move
• newIndex integer the index that instance will have

removeInstance

removes a nested instance at a given index

Parameters

• index integer the instance to remove index

SelectField

A simple select input field

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "Select"
• value string "" - The current value of the field
• defaultValue string "" - The defaultValue of the field
• options array [] - an array of strings or objects with value and label defined by the mapping
• optionsUrl string null - url to fetch the select options from
• cacheOptionsUrl string false - whether to cache optionsUrl fetching response
• path string "" - Field path
• mappingValue (string | array) "value" - The name(s) of the option object field(s) related to the option value, used to match passed in values to actual options
• mappingLabel string "label" - the name of the option object field related to the option label
• defaultLabel string "null" - The label to be displayed as a default value when set
• emptyToNull boolean true - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

DropdownSelectField

Form component allowing to select multiple values from a drop-down list with an option to allow custom values entered by the user. The handling of the a custom value is delegated to the application level through the call of the "onAddCustomValue" callback passed in paramter

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "DropdownSelect"
• value array [] - The current value of the field
• defaultValue array [] - The defaultValue of the field
• options array [] - The options of the dropdown, must be an array of objects
• optionsUrl string null - url to fetch the select options from
• cacheOptionsUrl string false - whether to cache optionsUrl fetching response
• path string "" - Field path
• allowCustomValues boolean false - if the field should try to accept user inputed values
• customValueLabel string "Add a value:" - Label that gets displayed when entering a new custom value. allowCustomValues need to be true for this to show up.
• mappingValue (string | array) "value" - The name(s) of the option object field(s) related to the option value, used to match passed in values to actual options
• mappingLabel string "label" - the name of the option object field related to the option label
• mappingReturn (string | array) null - the property/properties of the option object used to return the value(s) - null will return the whole object
• returnSingle boolean boolean - wether or not to return the first value or an array of values
• max number Infinity - Maximum values that the field can have
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• listPosition string "bottom" - Can be "top" or "bottom", whether to display the dropdown list above or below the field
• closeDropdownAfterInteraction boolean false - Whether the dropdown should close after adding, removing a value or stay open
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

TreeSelectField

Form component allowing to select multiple values from a tree structure

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "TreeSelect"
• value array [] - The current value of the field
• defaultValue array [] - The defaultValue of the field
• data array {} - The tree structure to select from, must be an object with eventually an array of children
• dataUrl array null - url to fetch the tree structure from
• cacheDataUrl string false - whether to cache dataUrl fetching response
• path string "" - Field path
• mappingValue (string | array) "value" - The name(s) of the node object field(s) related to the node value, used to match passed in values to actual tree nodes
• mappingLabel string "label" - the name of the node object field related to the node label
• mappingChildren string "children" - the name of the node object field related to the node children
• mappingReturn (string | array) null - the property/properties of the option object used to return the value(s) - null will return the whole object
• returnSingle boolean boolean - wether or not to return the first value or an array of values
• max number Infinity - Maximum values that the field can have
• selectOnlyLeaf boolean false - If enabled, only leaves can be selected and not the intermediary nodes
• expandToSelectedNodes boolean false - If enabled, tree selection modal will recursively expand to all the already selected values
• defaultExpanded array [] - an array of arrays describing a path of nodes expanded by default (tested on node labels, path parts are considered as RegExp)
• showOnlySearchedNodes boolean false - Flag that determines if nodes that doesn't match the text search should be hidden
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input
• groupByNodes array [] - If provided, will display selected values grouped by the provided node matches
• groupByLevel integer null - If provided, will display selected values grouped by level
• otherGroupLabel string "Other values" - Label used for the group that contains values that doesn't fit into a group

CheckBoxField

A simple checkbox

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "CheckBox"
• value string false - The current value of the field
• defaultValue string false - The defaultValue of the field
• path string "" - Field path
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

GroupSelectField

Form component allowing to select on/multiple values from a group of checkboxes/radioboxes

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "GroupSelect"
• value array [] - The current value of the field
• defaultValue array [] - The defaultValue of the field
• options array [] - The options of the dropdown, must be an array of objects
• optionsUrl string null - url to fetch the select options from
• cacheOptionsUrl string false - whether to cache optionsUrl fetching response
• path string "" - Field path
• mappingValue (string | array) "value" - The name(s) of the option object field(s) related to the option value, used to match passed in values to actual options
• mappingLabel string "label" - the name of the option object field related to the option label
• mappingReturn (string | array) null - the property/properties of the option object used to return the value(s) - null will return the whole object
• returnSingle boolean boolean - wether or not to return the first value or an array of values
• max number Infinity - Maximum values that the field can have
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• displayInline boolean false - Display choices in line, default is display as a list
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input

DataSheetField

Form component allowing to edit a spreadsheet-like data It uses the react-datasheet npm package to display to field

HeaderOptions

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "DataSheet"
• value array [] - The current value of the field
• defaultValue array [] - The defaultValue of the field
• headers array [] - The headers of the datasheet, must be an array of objects dscribing at least a "label" and a "key" property
• path string "" - Field path
• min number 0 - Minimum rows that the field can have
• max number Infinity - Maximum rows that the field can have
• rowControlRemove boolean true - Flag option for specifying if a row delete button should be displayed
• rowControlMove boolean true - Flag option for specifying if row move buttons should be displayed
• rowControlDuplicate boolean true - Flag option for specifying if a row duplicate button should be displayed
• rowControlAdd boolean true - Flag option for specifying if row add buttons should be displayed
• clipContent boolean false - Whether cells content should wrap or clip the text content
• emptyToNull boolean false - Flag that determines if empty values are transformed to null in the value function of the formStore
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input
• key string "" - The column key that will be used in the values row for input and output
• label string "" - The column label
• show boolean undefined - If false, the column will not be displayed at all
• readOnly boolean undefined - If true, the column will be displayed as read only cells
• defaultValue string "" - The default value the column will take when creating a new row
• duplicatedValue string "" - The default value the column will take when duplicating an existing row
• width string undefined - The column width (e.g. "50px" or "25%")

Slider

Slider input field

Options

Parameters

• label string "" - The field label
• labelTooltip string "" - The field label tooltip message
• labelTooltipPlacement string "top" - The field label tooltip message position
• type string "Slider"
• value (number | Range) null - The current value. If only a number is provided, a single slider will get rendered. If a range object {min:x, max:y} is provided, two sliders will get rendered.
• defaultValue (number | Range) null - The defaultValue of the field
• path string "" - Field path
• disabled boolean false - Is the field disabled or not, a disabled field won't be editable or processed by FormStore.getValues()
• readOnly boolean false - Is the field readOnly or not, a readOnly field won't be editable but will be processed by FormStore.getValues()
• readMode boolean false - If true, displays the field as label and value without the actual form input
• min number null (required) - minimum value. You cannot drag your slider under this value.
• max number null (required) - maximum value. You cannot drag your slider beyond this value.
• step number 1 - The default increment/decrement is 1. You can change that by setting a different number to this property.

FieldLabel

Label for all fields

SingleField

SingleField is a generic react component that supports all kinds of different input types without a form component

ActionIcon

ActionIcon component

Properties

• icon string required - glyphicon to display https://getbootstrap.com/docs/3.3/components/#glyphicons
• onClick function optional - callback for when action is clicked

GenericList

Generic List component that renders a list of items using Bootstrap Panels

Properties

• items array required - an array of items to be displayed in the list. Can be an array of primitives or objects
• expanded boolean optional - if the panel is expanded by default
• itemTitle object optional - react component to render the title for individual items. Gets passed the item to be rendered as a prop. Default value: ({ item }) => item
• itemBody boolean optional - react component to render the body for individual items. Gets passed the item to be rendered as a prop. Only necessary if you want a body to be displayed
• actions array required - an array of actions. An actions can be any react components that get rendered in the top right corner of the panel. For callback, implement the onClick which gets called with the selected item.