Skip to content

Home

Jump to bottom Edit New page
François Daoust edited this page Jun 19, 2012 · 44 revisions

This documentation is work in progress and very incomplete for the time being. Please check the JSON Form Reference in the meantime.

Overview

The JSON Form library is a JavaScript client-side library that takes a structured data model defined using JSON Schema as input and returns a Bootstrap-friendly HTML form that matches the schema. The layout of the generated HTML form may be entirely fine-tuned through a simple declarative mechanism.

The generated HTML form includes client-side validation logic and provides direct inline feedback to the user upon form submission (provided a JSON Schema validator is available). If values are valid, the JSON Form library uses the submitted values and the data model to create the appropriate JavaScript data object.

This wiki contains the documentation of the JSON Form Library.

Table of Contents

  1. Getting started
  2. Outline of a JSON Form object
  3. Using JSON Schema to describe your data model
    1. Basic JSON Schema example
    2. Hey, that's not pure JSON Schema!
    3. Supported types
    4. Building more complex structures
    5. Dealing with arrays
  4. Default form layout
    1. From schema element to form field
    2. Common schema properties
  5. Controlling the layout of the form
    1. A list of fields
    2. Referencing nested schema properties
    3. Common field properties
      1. append
      2. description
      3. htmlClass
      4. notitle
      5. prepend
      6. title
    4. Text input fields
      1. text
      2. password
      3. textarea
      4. wysihtml5
      5. ace
      6. color
    5. Checkbox fields
      1. checkbox
    6. Selection fields
      1. select
      2. radios
      3. checkboxes
    7. Groups of fields
      1. fieldset
      2. advancedfieldset
      3. authfieldset
      4. section
      5. actions
    8. Arrays
      1. array
      2. tabarray
    9. Alternative sections
      1. selectfieldset
    10. Buttons
      1. submit
      2. button
    11. File upload
      1. file
      2. file-transloadit
    12. Miscellaneous fields
      1. help
      2. hidden
  6. Form submission
    1. Validation
    2. Error reporting
    3. Accessing submitted values
  7. Extending JSON Form
    1. Field's view
    2. Binding to onBeforeRender
    3. Binding to onInsert
  8. Using previously submitted values to initialize a form
  9. JSON Form options
  10. Examples
  11. References
  12. Dependencies
  13. License

Getting started

To get started with JSON Form, you need to retrieve a copy of the repository, either cloning the git repository or downloading the repository as a zip file.

Once you have a local copy on your local hard drive, open the example.html file which contains the following example in your favorite Web browser.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Getting started with JSON Form</title>
    <link rel="stylesheet" style="text/css" href="deps/opt/bootstrap.css" />
  </head>
  <body>
    <h1>Getting started with JSON Form</h1>
    <form></form>
    <div id="res" class="alert"></div>
    <script type="text/javascript" src="deps/jquery.min.js"></script>
    <script type="text/javascript" src="deps/underscore.js"></script>
    <script type="text/javascript" src="deps/opt/jsv.js"></script>
    <script type="text/javascript" src="lib/jsonform.js"></script>
    <script type="text/javascript">
      $('form').jsonForm({
        schema: {
          name: {
            type: 'string',
            title: 'Name',
            required: true
          },
          age: {
            type: 'number',
            title: 'Age'
          }
        },
        onSubmit: function (errors, values) {
          if (errors) {
            $('#res').html('<p>I beg your pardon?</p>');
          }
          else {
            $('#res').html('<p>Hello ' + values.name + '.' +
              (values.age ? '<br/>You are ' + values.age + '.' : '') +
              '</p>');
          }
        }
      });
    </script>
  </body>
</html>

This page creates a form that asks for user's name and age. The user's name is a required field, while the age is optional. The form gets rendered with two input fields and a submit button. The onSubmit function is called upon form submission. If you hit the Submit button without entering values or if the age you entered is not a number, error messages appear next to the input fields.

Back to top

Outline of a JSON Form object

The $.jsonForm function takes a JSON Form object as parameter. The basic outline of a JSON Form object is:

{
  "schema": {
    // Object that describes the data model
  },
  "form": [
    // Array that describes the layout of the form
  ],
  "onSubmitValid": function (values) {
    // Callback function called upon form submission when values are valid
  }
}

The schema property is required. It describes the structured data model that must be created when the form is submitted. It is a JSON object that follows the properties definition of the JSON Schema specification. JSON Schema lets you describe the data structure that you'd like to generate from the form as well as constraints on possible values, such as the maximum number of characters that a string may contain. Check Using JSON Schema to describe your data model below for more info.

The form property is an array that describes the list and order of fields that compose the form. This property is optional. In its absence, a default form is generated from the schema. The structure of a form is not necessarily flat: an item in the form array may describe a group of fields or an array. See Controlling the layout of the form below.

The onSubmitValid callback is optional as well but chances are you will want to do something with the values entered by the user when the form is submitted and that callback is the easiest way around. It receives the object generated from the submitted values and the schema, provided the values are valid. If you need to do something special when submitted values are invalid for some reason, rather use the onSubmit callback, called whenever the form is submitted, that receives the list of errors as first parameter. Check Accessing submitted values below for an overview of the different possibilities.

Back to top

Using JSON Schema to describe your data model

JSON Schema is a JSON based format for defining the structure of JSON data. The RFC specification describes the possible contents of the schema property in the JSON Form object.

Basic JSON Schema example

Here is an example of a simple schema with two string properties: a name property and a gender property. The gender is a string that must match one of "male", "female" or "alien".

{
  "name": {
    "title": "Name",
    "description": "Nickname allowed",
    "type": "string"
  },
  "gender": {
    "title": "Gender",
    "description": "Your gender",
    "type": "string",
    "enum": [
      "male",
      "female",
      "alien"
    ]
  }
}

The JSON Form library uses the data schema to validate submitted values. For instance, the following JSON object is valid against the above schema:

{
  "name": "François Daoust",
  "gender": "male"
}

... whereas the following object is not both because the name is not a string and because the gender is not one of the allowed values:

{
  "name": 42,
  "gender": "machine"
}

More importantly, the JSON Form library uses the data schema to build the corresponding form. For instance, JSON Form would create the following form for this basic example (note the use of a select field for the gender enumeration):

TODO: upload image

Back to top

Hey, that's not pure JSON Schema!

If you've already played with JSON Schema, something may bug you in the above example: it is not fully compliant with JSON Schema. The example should rather be:

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "description": "Nickname allowed",
      "type": "string"
    },
    "gender": {
      "title": "Gender",
      "description": "Your gender",
      "type": "string",
      "enum": [
        "male",
        "female",
        "alien"
      ]
    }
  }
}

In other words, the wrapping object is missing:

{
  "type": "object",
  "properties": {
    contents
  }
}

True. Good catch, thanks for noticing... It just happens that, in basically all cases in JSON Form, the first level is going to be an object, so you may simply omit that level and start with the contents part directly. That said, if you prefer to stick to a pure JSON Schema format, you can! In fact, if your contents part defines a property named properties, you must define the wrapping context, otherwise JSON Form won't know that you're talking about a properties property and will rather think that you're talking about an object whose properties are the children of the properties property. See the problem? Don't worry if you don't, simply avoid fields named properties and you'll be safe no matter what.

Back to top

Supported types

JSON Form supports all JSON Schema types that make sense in the context of an HTML form:

  • string for strings
  • number for numbers, including floating numbers
  • integer for integers
  • boolean for booleans
  • array for arrays
  • object for objects.

In particular, null is not supported because it does not mean much in an HTML form, and any is not supported either because it's hard to come up with a practical input field that can create any type of data.

Types are the most straightforward constraint you can put on property values. All properties must have a type, otherwise JSON Form will go berserk and attempt to destroy the Earth. You may add more constraints using other JSON Schema properties. We've already seen required to enforce the presence of a value and enum as a way to define a list of possible values. You may also use maxLength or pattern for instance to add constraints that match your needs.

Back to top

Building more complex structures

The object type is interesting because it allows to nest objects and build more complex structures. For instance, you may want to separate properties about an author from the rest of the properties to produce the following data structure:

{
  "message": some text,
  "author": {
    "name": name,
    "gender": gender,
    "magic": magic_number
  }
}

The following JSON Schema would do the trick (omitting the wrapping object as usual):

{
  "message": {
    "type": "string",
    "title": "Message"
  },
  "author": {
    "type": "object",
    "title": "Author",
    "properties": {
      "name": {
        "type": "string",
        "title": "Name"
      },
      "gender": {
        "type": "string",
        "title": "Gender",
        "enum": [ "male", "female", "alien" ]
      },
      "magic": {
        "type": "integer",
        "title": "Magic number",
        "default": 42
      }
    }
  }
}

By default, JSON Form groups all the input fields created from the properties of an object together in a fieldset:

TODO: upload image

Back to top

Dealing with arrays

Arrays are a pain to support in a form. By essence, the number of items in an array is up to the user of the form so there needs to be some way to add/remove items. That's just the first step though. You'll quickly want some way to reorder items in an array as well, or to define array items that are more than just a simple input field. Oh, by the way, nesting arrays would be good too, kthxbai.

Well, good news, JSON Form does it all for you! Use the array type in the schema and... that's it! For instance, let's say you would like the user to input a list of friends, in order to generate an array such as:

[
  { "nick": "tidoust", "gender": "male", "age": 34 },
  { "nick": "titine", "gender": "female", "age": 6 },
  { "nick": "E.T.", "gender": "alien" }
]

Here is the schema that you would use:

{
  "friends": {
    "type": "array",
    "items": {
      "type": "object",
      "title": "Friend",
      "properties": {
        "nick": {
          "type": "string",
          "title": "Nickname",
          "required": true
        },
        "gender": {
          "type": "string",
          "title": "Gender",
          "enum": [ "male", "female", "alien" ]
        },
        "age": {
          "type": "integer",
          "title": "Age"
        }
      }
    }
  }
}

And here is a screenshot of the form generated by JSON Form. You can add/remove items using the corresponding buttons at the end of the array. You can also reorder items using drag-and-drop.

TODO: upload screenshot

NB: reordering items is only available when the jQuery.ui.sortable plug-in is up and running. To set it up, just add the following lines to your HTML page to complete the list of scripts:

<script type="text/javascript" src="deps/opt/jquery.ui.core.js"></script>
<script type="text/javascript" src="deps/opt/jquery.ui.widget.js"></script>
<script type="text/javascript" src="deps/opt/jquery.ui.mouse.js"></script>
<script type="text/javascript" src="deps/opt/jquery.ui.sortable.js"></script>

There is one important restriction to keep in mind: while JSON Schema allows to define arrays whose items follow different schemas depending on their position in the array, JSON Form only supports arrays whose items are all identical. In other words, the items property of an array property in the schema definition must be an object. For example, while a valid JSON Schema, the following schema is not allowed in JSON Form:

{
  "boo": {
    "type": "array",
    "items": [
      { "type": "string" },
      { "type": "number" }
    ]
  }
}

Back to top

Default form layout

From schema element to form field

To generate the form, the JSON Form library parses the schema recursively and checks the type and options of the properties it defines to decide upon the type of HTML form input to append to the form. The following mapping is used:

  • A string property that defines a list of possible values in an enum property generates a selection field, i.e. a <select> element
  • A generic string property generates a text input otherwise, i.e. an <input type="text"> element.
  • A number property generates a text input, i.e. an <input type="text"> element.
  • An integer property generates a text input as well, i.e. an <input type="text"> element.
  • A boolean property generates a checkbox, i.e. an <input type="checkbox"> element.
  • An object property generates a fieldset, i.e. a <fieldset> element. The fieldset contains the sub-form generated by the object's properties.
  • An array property generates an array wrapper that features Add/Remove buttons and items reordering. Each array item is generated from the sub-form defined in the items property of the array (which must be an object and not an array as mentioned in the previous section). The array is initially rendered with one item. That item cannot be removed (note the user may decide to leave that item empty though, meaning the submitted array may well be empty).

Back to top

Common schema properties

The JSON Form library uses the information available in the JSON schema to complete each generated field. In particular:

  • The title property serves as label for the input.
  • The description property is displayed next to the input field to guide user input.
  • The default property sets the initial value of a field.

Other schema properties are typically used for validation purpose (the required property for instance). The mapping and markup generated may evolve in the future, in particular to take advantage of the new form input types introduced in HTML5 when most browsers support them.

JSON Form automatically generates an ID for all input fields. IDs are prefixed by jsonform_ and a form counter to avoid conflicts (and allow JSON Form to be used more than once at the same time in a given page). Check the JSON Form options section if you need to override the default prefix for some reason.

JSON Form also sets the name attribute of all input fields to the id of the schema property that gave birth to it (the id is basically the path that leads to the property in the schema).

Back to top

Controlling the layout of the form

So far, we've seen how JSON Form turns a JSON schema into an HTML form all on its own. That's great but... the truth is, as soon as you start using JSON Form, you'll come up with new use cases that are not covered by default such as:

  • It you ask for a password, you may want to generate a password input.
  • You may want to add a Cancel button, or a snippet of HTML in between two input fields
  • You may want to provide your own validation error messages.
  • You may want to provide alternative sub-forms based on some initial choice.
  • You may want to hide some input fields in an Advanced options section.
  • You may want to display a textarea for a string property, or radio buttons for a selection field
  • You may want to use a super dooper image selector when the field lets the user choose between icons
  • and so on...

In other words, JSON Form's default behavior is all very nice, but it's not quite enough. Power to the people! Great, let's do that... Controlling the layout of the form is precisely the raison d'être of the form section in the JSON Form object:

{
  "schema": {
    // Data model
  },
  "form": [
    // This is where you can control the layout of the form!
  ]
}

Note the split between the data model and the layout. That's on purpose!

A list of fields

The form section describes the list of fields that compose the HTML form. It is a JSON array. Each item in the list describes a section of the resulting form. The order of the sections in the generated HTML form follows the order of the items in the array.

An array item may be:

  • A string with the specific value "*". When JSON Form encounters that value, it generates a form with one field per property defined in the schema, using the default form layout. Use this specific value for simple forms when you simply want to override the remaining form elements (the Submit button in particular). For instance:
[
  "*",
  {
    "type": "submit",
    "title": "Eat this!"
  }
]
  • A string that references the name of a property in the schema. The JSON Form library generates the default field that matches the property. Use this method when you do not need to override the generated field by itself, but simply its position within the resulting form. If you wonder how you may reference properties that are at a nested level (when the schema includes object properties), hold on, we'll cover that in a minute. An example that would work for the Basic JSON Schema example:
[
  "name",
  {
    "type": "help",
    "helpvalue": "The rest of the form is entirely optional, feel free to ignore."
  },
  "gender",
  {
    "type": "submit",
    "title": "Roger"
  }
]
  • A JSON object whose key property references the name of a property in the schema. The object may also override some of the properties of the schema property and/or define additional properties to control how JSON Form generates the resulting field. Use this method to change the visual aspect of an input field. For instance, to replace the text input by a textarea in the first example:
[
  {
    "key": "name",
    "type": "textarea"
  },
  "gender",
  {
    "type": "submit",
    "title": "Roger"
  }
]

In case you're wondering, using "gender" to reference the schema is strictly equivalent to using { "key": "gender" }, only a bit shorter and more convenient to write.

  • A JSON object not linked to any property in the schema. Use this method to produce additional sections in the form, such as fieldsets, helper text, or expandable sections. We've already seen examples en passant with the help and submit element types. You could also wrap optional fields in an Optional fieldset:
[
  "name",
  {
    "type": "fieldset",
    "title": "Optional",
    "items": [
      "gender"
    ]
  },
  {
    "type": "submit",
    "title": "Roger"
  }
]

When you don't define a form section, JSON Form creates a default one for you and generates the corresponding form:

[
  "*",
  {
    "type": "actions",
    "items": [
      {
        "type": "submit",
        "title": "Submit"
      }
    ]
  }
]

In other words, it produces a form that contains all properties defined in the schema (represented by the \* value) followed by an actions fieldset that contains a submit button.

Back to top

Referencing nested schema properties

The examples of the previous section stuck to flat schemas, i.e. schemas that do not contain object or array properties. Adding these possibilities back in the mix produces nested properties. Property names that appear at a deeper level may not be globally unique across the schema so you cannot simply reference them by their name. To reference a property that is listed in the properties section of an object element, simply use a dotted notation to describe the path that leads to the property in the schema. For instance, taking the following schema:

{
  "author": {
    "type": "object",
    "properties": {
      "name": {
        "type": "object",
        "properties": {
          "firstname": { "type": "string", "title": "First name" },
          "lastname": { "type": "string", "title": "Last name" }
        }
      }
    }
  }
}

To reference the firstname property from an element in the form section, use "author.name.firstname", as in:

[
  "author.name.firstname",
  "author.name.lastname"
]

Similarly, to reference a property that is listed in the items section of an array element, simply use square brackets next to the array property name combined with the previous dotted notation. For instance, completing a bit the previous schema to turn it into an array of authors:

{
  "authors": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "firstname": { "type": "string", "title": "First name" },
            "lastname": { "type": "string", "title": "Last name" }
          }
        }
      }
    }
  }
}

To reference the firstname property from an element in the form section, use "authors[].name.firstname" as in:

[
  {
    "type": "array",
    "items": {
      "authors[].name.firstname",
      "authors[].name.lastname"
    }
  }
]

Beware: It is relatively easy to create an invalid form when the schema contains arrays. You can only reference array items from an element in the form section that is itself part of an array. Said differently, the array depth of an element in the form section must match that of the element it references in the schema. The following form section is not valid because the form element is not part of an array but still references an array item:

[
  "authors[].name.firstname",
  "authors[].name.lastname"
]

Back to top

Common field properties

Most fields (except groups of fields) react to a few common properties that fine-tune the look-and-feel of the field generated by JSON Form. These properties are listed below in alphabetic order.

append

Use this property to insert a suffix after the generated form input. The property accepts an HTML fragment string as value. Note that the suffix is not appended to the final value when the form is submitted.

See also prepend

description

By default, JSON Form displays the description property defined in the schema next to the input field to guide user input. Set this property in the form section to override that of the schema element (or to define it if the schema does not).

htmlClass

Use this property to define additional classes for the generated field. Classes must be separated by whitespaces. Note classes are set to the <div> element that wraps the input field, not to the input field itself.

notitle

Sometimes, you may want JSON Form not to insert a label for the input field. Use this property to ignore the title property of the schema element.

prepend

Use this property to insert a prefix before the generated form input. The property accepts an HTML fragment string as value. Note that the prefix will not appear in the final value when the form is submitted.

See also append

title

By default, JSON Form uses the title property defined in the schema as label for the generated input field. Set this property in the form section to override that of the schema element (or to define it if the schema does not).

Back to top

Now that you know how to author the form section, reference properties in the underlying schema and fine-tune a few common properties, let's see how we can go a step further and actually change the type of field that gets generates. JSON Form includes about 25 different fields, ranging from the usual text input field to tabs and wysiwyg HTML editors. That list will grow over time ; if you cannot find the field you're looking for in the list below, no big deal, check the Extending JSON Form section and create your own!

Text input fields

Text input fields are linked to string properties in the schema. They may be used to gather anything from a word to a large HTML snippet.

Check Selection fields if the string property defines an enum property.

text

JSON Form generates a text field by default for all schema properties of type string (save enumerations and colors). Not much to say about it, that's just a regular <input type="text"> input field!

password

If you need to gather a password, simply set the type of the form field's type to password to have JSON Form generate an <input type="password"> input field.

{
  "schema": {
    "pwd": {
      "type": "string",
      "title": "Your secret"
    }
  },
  "form": [
    {
      "key": "pwd",
      "type": "password"
    }
  ]
}

textarea

The name says it all. Use textarea to generate a <textarea> field.

{
  "schema": {
    "comment": {
      "type": "string",
      "title": "Your thoughts"
    }
  },
  "form": [
    {
      "key": "comment",
      "type": "textarea"
    }
  ]
}

wysihtml5

ace

color

JSON Form generates a color input field by default for all schema properties of type string that also have a format property set to color.

{
  "schema": {
    "maincolor": {
      "type": "string",
      "title": "Main color",
      "format": "color"
    }
  }
}

Internally, JSON Form uses the Spectrum library to create the color picker, so make sure that you include the spectrum.js and spectrum.css libraries before using this type of field.

Back to top

Checkbox fields

Checkbox fields are linked to boolean properties in the schema. They may also be linked to array properties whose items schema defines a list of possible values in an enum property.

checkbox

JSON Form generates a checkbox field by default for all schema properties of type boolean. The default checkbox is kind of dull because it really displays a little checkbox. You'll probably want some way to define an inline message next to the checkbox for the user. Good news, that's precisely the purpose of the inlinetitle property.

{
  "schema": {
    "flag": {
      "type": "boolean",
      "title": "Adult"
    }
  },
  "form": [
    {
      "key": "flag",
      "inlinetitle": "Check this box if you are over 18"
    }
  ]
}

checkboxes

If you need the user to select one or more options among a list of choices, the checkboxes form field is for your. It applies to an array property whose items schema explicitly defines a list of possible values in an enum property.

If you want to replace the values that appear in the schema by more user-friendly values, simply define the mapping between the values and the option's label in a titleMap as in the following example.

{
  "schema": {
    "menu": {
      "type": "array",
      "title": "Options",
      "items": {
        "type": "string",
        "title": "Option",
        "enum": [
          "starter",
          "maincourse",
          "cheese",
          "dessert"
        ]
      }
    }
  },
  "form": [
    {
      "key": "menu",
      "type": "checkboxes",
      "titleMap": {
        "starter": "Starter would be great",
        "maincourse": "No way I'll skip the main course",
        "cheese": "Cheddar rules!",
        "dessert": "Thumbs up for a dessert"
      }
    }
  ]
}

Back to top

Selection fields

Selection fields are linked to string properties in the schema that define an enum property with an enumeration of possible values. Such fields allow the selection of one or more options depending on the type of field.

The enumeration defined in the schema sets the list of values that your application will receive once the form is submitted. If you want to replace these values in the form by more user-friendly messages, define the mapping in the titleMap property.

{
  "schema": {
    "gender": {
      "type": "string",
      "title": "Gender",
      "enum": [ "male", "female", "alien" ]
    }
  },
  "form": [
    {
      "key": "gender",
      "titleMap": {
        "male": "Dude",
        "female": "Dudette",
        "alien": "I'm from outer space!"
      }
    }
  ]
}

select

JSON Form generates a select field by default for all schema properties of type string that define an enumeration list. See above for a typical example.

radios

If you'd rather see the list of options rendered as radio buttons, use the radios type.

{
  "schema": {
    "language": {
      "type": "string",
      "title": "Best language",
      "enum": [ "JavaScript", "Python", "PHP", "Java", "C++", "other" ]
    }
  },
  "form": [
    {
      "key": "language",
      "type": "radios"
    }
  ]
}

Groups of fields

It is often convenient to group a set of fields together in a form to ease readability and thus improve the user experience. JSON Form provides a few types for that purpose.

fieldset

JSON Form generates a fieldset for all schema properties of type object, but you may also want to generate a fieldset without referencing a schema property at all. As you might expect from the name, a fieldset field simply produces a <fieldset> element in the resulting form.

When set, the expandable boolean property tells JSON Form to render the fieldset's title and only expand the fieldset's section when the user clicks on it. This is typically useful for advanced options that users could skip on first read.

If you're using Bootstrap to style the resulting form, please note that it does not include styles for expandable sections at first. You might want to add a few extra stylesheet properties to your CSS to add a visual hint that the section can be expanded/collapsed, for instance:

.expandable > legend:before {
  content: '\25B8';
  padding-right: 5px;
}
.expanded > legend:before {
  content: '\25BE';
}
{
  "schema": {
    "comment": {
      "type": "string",
      "title": "Comment"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "age": {
      "type": "number",
      "title": "Age"
    }
  },
  "form": [
    {
      "key": "comment",
      "type": "textarea"
    },
    {
      "type": "fieldset",
      "title": "Author",
      "expandable": true,
      "items": [
        "name",
        "age"
      ]
    }
  ]
}

advancedfieldset

The advancedfieldset type is a shortcut type. It is the same thing as an expandable fieldset whose title is Advanced settings.

{
  "schema": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "age": {
      "type": "number",
      "title": "Age"
    }
  },
  "form": [
    "name",
    {
      "type": "advancedfieldset",
      "items": [
        "age"
      ]
    }
  ]
}

authfieldset

The authfieldset type is a shortcut type. It is the same thing as an expandable fieldset whose title is Authentication settings.

{
  "schema": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "key": {
      "type": "string",
      "title": "Access key"
    }
  },
  "form": [
    "name",
    {
      "type": "authfieldset",
      "items": [
        "key"
      ]
    }
  ]
}

section

From time to time, you'll want to group fields without generating a proper <fieldset>. This might be for styling purpose, or as a convenient way to define a tab in a tabarray. The generic section type generates a group of fields without title wrapped in a <div> element.

{
  "schema": {
    "comment": {
      "type": "string",
      "title": "Comment"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "age": {
      "type": "number",
      "title": "Age"
    }
  },
  "form": [
    {
      "key": "comment",
      "type": "textarea"
    },
    {
      "type": "section",
      "title": "Author",
      "items": [
        "name",
        "age"
      ]
    }
  ]
}

actions

To highlight the section that contains form buttons, use the actions type to wrap button fields in a <div class="form-actions"> container.

{
  "schema": {
    "search": {
      "type": "string",
      "title": "Search"
    }
  },
  "form": [
    "search",
    {
      "type": "actions",
      "items": [
        {
          "type": "submit",
          "title": "Submit"
        },
        {
          "type": "button",
          "title": "Cancel"
        }
      ]
    }
  ]
}

Back to top

Back to top

Arrays

array

tabarray

Back to top

Alternative sections

selectfieldset

Back to top

Buttons

submit

button

Back to top

File upload

file

file-transloadit

Back to top

Miscellaneous fields

help

hidden

Back to top

Form submission

Validation

Error reporting

Accessing submitted values

Back to top

Using previously submitted values to initialize a form

Gathering user input is great but that's seldom something you'll do once and for all. Whether it is to fix some value, adjust settings or simply because you can, you'll most probably want to allow your users to get back to a form that they previously submitted and change some values.

In order to enable that possibility, there needs to be some way to initialize a form with previously submitted values. There's a JSON Form property for that, it's called value. Simply set that property to the object generated when the form was previously submitted, and JSON Form will initialize the form accordingly.

Taking back the friends example, here is how you could pass on the list of friends that JSON Form might have generated when the form was submitted:

{
  "schema": {
    "friends": {
      // See "Dealing with arrays"
    }
  },
  "value": {
    "friends": [
      { "nick": "tidoust", "gender": "male", "age": 34 },
      { "nick": "titine", "gender": "female", "age": 6 },
      { "nick": "E.T.", "gender": "alien" }
    ]
  }
}

Back to top

Extending JSON Form

Field's view

Binding to onBeforeRender

Binding to onInsert

Back to top

JSON Form options

Back to top

Examples

References

Dependencies

At a minimum, the JSON Form library depends on:

The JSON Form library may require further libraries, depending on the features you need for the forms you need to render. In particular:

  • Bootstrap v2.0.3 or above is more or less needed (unless you enjoy ugly forms, that is) if you don't provide your own styles. JSON Form only needs the bootstrap.css file.
  • The JSON Schema Validator is used to detect and report validation errors upon form submission. The deps/opt folder contains a "build" of the JSON Schema Validator for use in JSON Form.
  • Bootstrap Dropdowns v2.0.3 or above is needed for imageselect fields.
  • jQuery UI Sortable v1.8.20 or above is required for drag-and-drop support within arrays and tabarrays. Note the plugin itself depends on jQuery IU Core, jQuery UI Mouse, and jQuery UI Widget.
  • wysihtml5 is required if the form uses wysihtml5 textarea fields.
  • Spectrum is required if the form uses color fields.

All of these libraries are in the deps folder, although you might want to check their respective Web site for more recent versions.

NB: JSON Form also uses JSON.parse and JSON.stringify which is normally already natively supported by all modern browsers. You may use a JSON library otherwise.

License

The JSON Form library is available under the MIT license.

All the libraries that JSON Form may depend on are licensed under the MIT license, except for the JSON Schema Validator, licensed under the BSD 3 Clause license.

Back to top

Add a custom footer
Add a custom sidebar
Clone this wiki locally