@helios-interactive/reggie

Reggie

A plugin intent on making complex form flows simple, and easily changeable.

Installation

npm install @helios-interactive/reggie --save

Usage

To use Reggie, you need to have a target div on the page, and also need to configure Reggie.

Configuring Reggie

Reggie Accepts a configuration object on instantiation. This object is described here, and broken up by levels of nesting.

Reggie Top Level Options

key	type	default	description	required
noSubmit	boolean	false	If set to true, then the reggie generated submit button will be hidden. It will still be present in the DOM to allow for form submission	false
targetDiv	string		The ID of the target div. Reggie will generate the forms within this div.	true
initial	string		The step that Reggie will start on. Should match the name of one of the defined steps	true
formClasses	string		A string of all classes that should be added to the form when it is generated	false
steps	array		The steps provided will determine what content the form collects, and in what order that content should be displayed. Reference the Step Options for details on configuring each of these.

Step Options

key	type	default	description	required
name	string		The name of this step. This must be unique, with no other step names matching it. This name is what you will use later when referencing the step for navigation flow.	true
next	string		The name of the step which should be transitioned to if reggieInstance.next() is called.	false
submitButton	object		If a submit button is provided here, then it will overwrite the default submit button that reggie uses. It will overwrite for this step only. You can pass the class (accepts a string, and can include multiple classes), and the text which will be the text displayed within the button. Ex:{class: 'submit-btn', text: 'Submit'}	false
pieces	array		Pieces defines each field that will be in this step of the form. Reference the Piece Options for details on configuring each of these.	true

Piece Options

key	type	default	description	required
name	string		The name of the piece. This should be unique for all pieces. When reggie constructs a model based on the form it will use the piece name to associate the input data with this piece.	true
type	string	'input'	The type of piece to be created. A list of available piece types can be found in the Piece Types section.	true
class	string		A string of all classes that should be added to the piece when it is generated	false
containerClass	string		Every piece has a container div that is created. All classes defined here will be added to the container div.	false
placeholder	string		If the piece type allows for placeholder text, then this text will become the placeholder	false
validations	array		Validations accepts an array of objects. Each object is a validation, and all validations will be run on a validation check. Each object must contain a regex key and a error key. The regex key will be run against the value of the piece, and if it does not get a match, then an error will be triggered. The error key contains the text of the error. Ex: {regex: /\w+/, error: 'Last name is required'}	false
options	array		The options array is used when the piece type needs options (select, and radio). It will define what options are rendered in the piece.	sometimes - when type requires it. Reference the Piece-Options Options for details on configuring each of these.
pieces	array		If the piece type is declared to be 'group' then an additional array of pieces can be nested within the current piece. These pieces accept the same options as the current piece. This is primarily used for grouping elements together on the UI.	sometimes - when type requires it.
label	string		The text of the label that will be associated with the piece in the UI. If no text is present, then no label will be created. Labels also allow for the user to create a named span that can be refereced later, most commonly to treat it as a link. A label with the following { Text content, span-id } syntax will create a span with the content being that which comes before the comma (trimmed), and the id being that which comes after the comma (trimmed).	false
labelClass	string		A string of all classes that should be added to the label when it is generated	false
autocomplete	boolean	true	If an input allows autocomplete, then this can be used to toggle that on or off.	false

Piece-Options Options

key	type	default	description	required
name	string		The name of the option. In a select piece, this will determine the text shown for the select option.	true
label	string		The text of the label that will be associated with the option in the UI. If no text is present, then no label will be created. If the parent piece is type select, then no label is shown. Labels also allow for the user to create a named span that can be refereced later, most commonly to treat it as a link. A label with the following { Text content, span-id } syntax will create a span with the content being that which comes before the comma (trimmed), and the id being that which comes after the comma (trimmed).	false
labelClass	string		A string of all classes that should be added to the label when it is generated	false
value	any		The value of the piece if this option is choosen.	true
class	string		A string of all classes that should be added to the option when it is generated	false

Piece Types

type	description	requirements
group	A group piece allows for other pieces to be grouped within it. It will create a container div within the DOM to place all child pieces inside of. In this way you can break apart each step into sections within the DOM	A group type must have child pieces.
radio	Creates a radio group with all of the given options as radio buttons	A radio type must have options that declare the radio butons.
radio-pill	Creates a radio group with all of the given options as radio buttons.In addition, this radio group is styled in a pill shape with each option having a equal section of the pill.	A radio type must have options that declare the radio butons.
input	This is the default input box
select	This will created a styled reggie select element.	A select type must have options that declare the select options.
email	This will create an imput box of the type email.
checkbox	This will create a checkbox input.
tel	This will create an input box of the type tel.

Using Reggie

Attributes

Attributes that are available on the reggie instance.

attribute	description
model	A object defined by the pieces that are sent to reggie. This object is single level, and each key is associated with a piece. Each piece must be unique for the model to work properly. The model will be updated with the latest values from the pieces. The model can be accessed and updated directly using this attribute.
options	The options sent to reggie on instantiation
steps	The steps array from within the options sent to reggie

Methods

method	arguments	description	example
new	options - object. See Configuring Reggie	Creates and returns a new reggie instance.	new Reggie(reggieOptions)
updateModel	form	Accepts a form, and will update the model based on the content of the form passed in.	reggie.updateModel(document.getElementById('reggie-form'))
validateStep	form, updateDOM	Accepts a form (or defaults to the reggie form), and a boolean for updateDOM, if true, then validation errors will show in the DOM, if false, then errors will not be placed on the DOM. This method will run all validations for the current step, and return an array with any errors that are present. If no errors are present it will return an empty array.	if ( reggie.validateStep(null, false).length > 0 ) { alert('please correct the errors') };
updateDOM		Forces a re-render of the reggie DOM. This can be used to incorporate model updates made by your app.	reggie.model.firstName = 'foobar'; reggie.updateDOM();
currentStep		Returns the current step as an object	reggie.currentStep()
currentAttributes		Returns an array of attributes that are in the currentStep	reggie.currentAttributes()
next		Will go to the step defined in the current step's next attribute	reggie.next()
previous		Will go to the previous step	reggie.previous()
goto	target, recordTransition	Accepts a target (step name), and will render that step to the DOM. The second argument, recordTransition (boolean), will determine if this transition is recorded for use with the previous method. Will go to the given step name.	reggie.goto('lastStep')
reset		Will reset reggie back to the initial state, and clear out the model to be empty again.	reggie.reset()
submitStep		Will submit the current step	reggie.submitStep()

Events

Each event will provide a details object that contains reggie specific information.

event	details	description
reggieStepStart	{to: 'stepThatIsStarting', from: 'stepThatJustEnded', model: {contains: 'current snapshot of the model'}}	Triggers at the beginning of a step, providign an update as to the current state.
reggieStepEnd	{to: 'stepThatIsStarting', from: 'stepThatJustEnded', model: {contains: 'current snapshot of the model'}}	Triggers at the end of a step, providing an update as to the current state.
reggieStepSubmit	{from: 'stepThatJustEnded', model: {contains: 'current snapshot of the model'}}	Triggers at the submission of a step, and allows the user to then direct what reggie should do next.

Example Usage

const reggieOptions = {
  noSubmit: false,
  targetDiv: 'reggie-div',
  initial: 'startStep',
  formClasses: 'reggie-form',
  steps: [
      {
      name: "startStep",
      next: "finalStep",
      submitButton: {
        class: 'submit-btn',
        text: 'Custom Submit Button'
      },
      pieces: [
          {
            type: "group",
            class: "input-group",
            pieces: [
              {
                name: "firstName",
                type: "input",
                autocomplete: false,
                placeholder: "First Name",
                class: 'input-box',
                containerClass: 'container-class',
              },
              {
                name: "lastName",
                type: "input",
                autocomplete: false,
                placeholder: "Last Name",
                class: 'input-box'
              }
            ]
          },
          {
            name: "email",
            type: "email",
            placeholder: "Email",
            class: 'input-box',
            containerClass: 'email-container'
          }
        ]
      },
      {
        name: "optionalStep",
        next: "finalStep",
        pieces: [
          {
            name: 'bestNumber',
            type: 'select',
            placeholder: 'Number 1-3',
            label: 'Pick the best number.',
            labelClass: 'reggie-label',
            class: 'reggie-select',
            options: [
              {
                name: '1',
                value: '1'
              },
              {
                name: '2',
                value: '2'
              },
              {
                name: '3',
                value: '3'
              }
            ]
          }
        ]
      }
      {
        name: "finalStep",
        pieces: [
            {
              name: 'gender',
              type: 'radio-pill',
              class: 'reggie-radio-pillbox-custom',
              options: [
                {
                  name: 'male',
                  label: 'MALE',
                  value: 'male'
                },
                {
                  name: 'female',
                  label: 'FEMALE',
                  value: 'female'
                },
                {
                  name: 'unspecified',
                  label: 'UNSPECIFIED',
                  value: 'unspecified'
                }
              ],
              validations: [
                {
                  regex: /\w+/,
                  error: 'Please select a gender'
                }
              ]
            },
            {
              name: 'over18',
              type: 'checkbox',
              containerClass: 'reggie-checkbox-container reggie-form-field',
              class: 'reggie-checkbox',
              label: 'I am at least 18 years old',
              labelClass: 'reggie-label reggie-checkbox-label'
            }
          ]
      }
  ]
}

// Instantiate reggie, and draw the initial step into the DOM
const reggie = new Reggie(reggieOptions);

// Set default values for pieces
reggie.model.gender = 'unspecified';
// Update the DOM. You can do this when setting defaults so that they populate the
// current step. If the defaults pertain to a step that is yet to come, then they will
// automatically populate when that step is rendered.
reggie.updateDOM();

// Handle reggie submission events. You can control the flow of the form here
document.addEventListener('reggieStepSubmit', (event) => {
  // if they are coming from the startStep, and provided an email
  // then make them do the optional step
  // Otherwise just call the step's given next option
  if ( event.detail.from === 'startStep' && reggie.model.email ) {
    reggie.goto("optionalStep");
  } else {
    reggie.next();
  }
})

// Handle reggie step start events.
document.addEventListener('reggieStepSubmit', (event) => {
  // If the user has completed all steps, then behave appropriately
  if ( event.detail.to === 'done' ) {
    let modelKeys = Object.keys(event.detail.model);
    let finalModel = [];
    modelKeys.forEach(key => {
      finalModel.push(`${key}: ${event.detail.model[key]}`);
    });

    alert(`You made it through, here's your data!\n\n${finalModel.join('\n')}`);
  }
}

License

MIT License

Copyright (c) [2017] [Adam McFadden]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.