Winterfell

Generate complex, validated and extendable JSON-based forms in React

Winterfell allows you to build up complex, multi-page forms with conditional questions, validation and conditional-page switching via a JSON schema, rendered by React.

Winterfell was initially made for a project in a sector that required a large, complex form with questions that would result in more questions or different pages when you clicked next. With an easy to write schema and a high level of customisation, comes a great power.

View Demo - Follow me on Twitter

Usage

First install Winterfell via npm

$ npm install winterfell --save

Winterfell uses a JSON schema to render your form. We will go through that later.

var Winterfell = require('winterfell');
var schema     = require('./schema');

React.render(
  <Winterfell schema={schema} />,
  document.getElementById('form')
);

Features

• Easy, quick and extendable
• JSON schema
• Design agnostic and customisable
• Multi-page forms
• Infinitely-recursive conditional questions
• Conditional page switching
• Conditional form submitting
• Disable regular submissions
• Instant form validation
• Decide when to validate per field
• Validation against other fields values
• Predefined validation types
• Predefined error messages
• Custom validation types
• Custom error messages
• Custom error rendering
• Custom required asterisk rendering
• Custom classes
• Custom InputTypes
• Question pre and post text
• Question panel header and text
• Question set header and text
• Ability to disable buttons
• Default values
• Events

Schema

The schema is built up of three main parts, formPanels, questionPanels and questionSets.

Form Panels

The initial formPanels entry is used as a page of questions, or questionPanels in Winterfell's case.

{
  "formPanels": [
    {
      "index": 1,
      "panelId": "intro-panel"
    },
    {
      "index": 2,
      "panelId": "register-panel"
    },
    {
      "index": 3,
      "panelId": "final-panel"
    }
  ]
}

Question Panels

Question Panels are the fleshed-out details about a page of questions. We defined the questionSets that exist on this page, any conditions for submitting the panel and button information. You should have one of these for every panel defined in formPanels above.

Each questionPanel has the ability to have a header and some text along with it that is displayed above the questions. You can define these via the panelHeader and panelText fields.

Supported actions are GOTO and SUBMIT. When using GOTO, the target can be any questionPanelId. SUBMIT places the target in to the action field of the form element.

{
  "questionPanels": [
    {
      "panelId": "intro-panel",
      "panelHeader": "A quick survey?",
      "panelText": "Please could you take a few minutes to fill out our survey?",
      "action": {
        "conditions": [
          {
            "questionId": "existing-user",
            "value": "no",
            "action": "GOTO",
            "target": "register-panel"
          }
        ],
        "default": {
          "action": "GOTO",
          "target": "final-panel"
        }
      },
      "button": {
        "text": "Next",
        "disabled": false
      },
      "": {
        "text": "Back",
        "disable": false
      },
      "questionSets": [
        {
          "index": 1,
          "questionSetId": "intro-set"
        }
      ]
    }
  ]
}

Question Sets

Questions Sets are groups of questions. Here is where you define questions with their validations, types, conditions etc. conditionalQuestions are recursive and will work as expected.

The questionSet below has an initial radio button with yes and no options. When you select yes, a question asking for the users email address will render.

Each question has the ability to have some text associated with it which gets rendered below the questions-label and some postText which will be rendered below the questions input.

{
  "questionSets": [
    {
      "questionSetId": "intro-set",
      "questionSetHeader": "I am a question set header",
      "questionSetText": "I am a question set text",
      "questions": [
        {
          "questionId": "existing-user",
          "question": "Are you an existing user?",
          "text": "We'd just like to know so we can get you in the right place.",
          "input": {
            "type": "radioOptionsInput",
            "default": "yes",
            "options": [
              {
                "text": "Yes",
                "value": "yes",
                "conditionalQuestions": [
                  {
                    "questionId": "register-user-email",
                    "question": "Please enter the email address your account is registered with",
                    "postText": "We will not spam your email address.",
                    "input": {
                      "type": "emailInput",
                      "placeholder": "Email Address"
                    },
                    "validateOn": "blur",
                    "validations": [
                      {
                        "type": "isLength",
                        "params": [
                          1
                        ]
                      }
                    ]
                  }
                ],
                "validations": [
                  {
                    "type": "isLength",
                    "params": [
                      1
                    ]
                  }
                ]
              },
              {
                "text": "No",
                "value": "no",
                "conditionalQuestions": []
              }
            ]
          }
        }
      ]
    }
  ]
}

The validateOn property is used to dictate when to validate the field. The default for this is blur, which results in the field being validated when the user unfocusses from the field. You can also set this field to change which will validate the field as the user types, or changes their answer. Setting validateOn to submit will result in the field being validated when the next or submit button being pressed and only then.

Validations are handled via the Validator package on npm. In the validations key item, you can set your types of validation for the field. The type must be a method on the Validator package, or a custom defined method.

A validation-items params key must be an array of parameters for the validation method. The value will be unshifted to the start of the array and called up on the validation method in order. For example:

Validation item where the value must be a minimum length of 1.

{
  "type": "isLength",
  "params": [
    1
  ]
}

Validation item where the value must be a minimum length of 1 and a maximum of 20.

{
  "type": "isLength",
  "params": [
    1,
    20
  ]
}

You can also add a custom error message for the questions validaton item by using the message property.

{
  "type": "isLength",
  "params": [
    1
  ],
  "message": "Please select an option"
}

To validate a questions answer against another questions answer, you can wrap curly-braces around a parameter in the params property and it will be turned in to a questions answer. For example:

{
  "type": "equals",
  "params": [
    "{password}"
  ],
  "message": "Confirm Password must match the Password field"
}

HTML Classes

Winterfell allows you to define classes for the rendered form in multiple different areas. To use them, place them in the root of the form-schema like so:

{
  "formPanels": [],
  "classes": {
    "form": "form-wrapping-class",
    "label": "question-label"
  }
}

The table below describes the current set of classes.

Class Name | Description --- | --- form | The form element itself questionPanels | The div that wraps around the active questionPanel questionPanel | The div that wraps around the active questionSets and the button bar questionPanelHeaderContainer | The div that wraps around the questionPanels header text and text questionPanelHeaderText | The h3 tag that holds the questionPanel header text questionPanelText | The p tag that holds the questionPanel text questionSetHeader | The h4 tag that holds the questionSet header questionSetText | The p tag that holds the questionSet text questionSetHeaderContainer | The div that wraps around the header and text of a questionSet questionSets | The div that wraps around the questionSets inside of a questionPanel questionSet | The div that wraps around the questions inside a questionSet question | The div that wraps around the question questionText | The p tag that holds the question text questionPostText | The p tag that holds the question post-text label | Label inside of a question backButton | Panel-back button, shown when on a second panel controlButton | Typically the Next or Submit button, depending on panel buttonBar | The div wrapped around the buttons described above errorMessage | Error Message div class - Not used if custom renderError method used input | Assigned to the inputs for types textInput, textareaInput, emailInput and passwordInput select | Assigned to the selectInput select-element file | Assigned to the fileInput file-element checkboxInput | The div that wraps around the