🌜
🌞
jsonform

jsonform

v2.2.5

Client-side JavaScript library that generates HTML forms from structured data models expressed using a JSON schema, possibly completed by a form layout description.

npm install jsonform

README

JSON Form

MIT license PRs Welcome Maintained Release NPM: released

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 3-friendly HTML form that matches the schema.

The generated HTML form includes client-side validation logic that 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 submitted values to create the JavaScript data structure that matches the data model.

The layout of the generated HTML form may be entirely fine-tuned through a simple declarative mechanism.

Getting started

The example below creates a form that asks for the user's name and age. The user's name is a required field, while the age is optional.

<!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>

Loading this page in a browser renders a form with two input fields and a submit button. The onSubmit function is called upon form submission. If you press "Submit" without entering values or if the age you enter is not a number, error messages appear next to the input fields.

NB: Paths in this example are relative to the root of the JSON Form project.

Documentation

You can do much more with the JSON Form library. You may define a more complex data model that includes arrays and objects for instance, or you may control the layout of the form to include fieldsets, expandable sections or tabs. For more information, check the reference documentation for JSON Form.

Playground

If you're more of the acting type than of the reading type, the JSON Form Playground is a simple JSON Form editor that lets you try out and extend all the examples in the doc.

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:

  • ACE is needed to render rich text input fields. The deps/opt/ace folder contains a minimal set of files from ACE to render a JSON input field. Beware that the code of ace.js needs to be encapsulated in (function(require,define,requirejs) {...})(undefined,undefined,undefined); before it may be used within JSON Form.
  • Bootstrap v3.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 for now, 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.

License

The JSON Form library is licensed 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 and the ACE editor licensed under the Mozilla tri-license (MPL/GPL/LGPL).

Release Notes

2.2.5
By Cyril Chapellier • Published on September 20, 2021

This is a minor release following various bug fixes and improvements from the community

Fixes: #365 — Add a range slider live value indicator #367 — Only apply templating when the default is of type string

New features: #305 — Add support for minLength #377 — Add support for accept attribute for file input

Documentation: #379 — Add example in playground for file upload

2.2.4
By Cyril Chapellier • Published on June 10, 2021

This is a minor release following various bug fixes and improvements from the community

Fixes: #321 — Accessibility of inputs #341 — Accessibility of forms #349 — Fix field init when default is available #361 — Fix selectfieldset style

  • Various style / linting fixes

New features: #348 — Add support for draggable property #354 — Add the ability to select tabarray with rel

2.2.3
By Cyril Chapellier • Published on March 23, 2021

This is a minor release following various bug fixes and improvements from the community

Fixes: #326 — Updates loop to ignore null value

Added: New template in the playground for HTML Wysiwyg

2.2.2
By Cyril Chapellier • Published on December 22, 2020

This is a minor release following various bug fixes and improvements from the community

Fixes: #308 — radiobuttons type does not show passed value #295 — Context error in formNode.prototype.updateElement #292 — Expanded fieldset get closed when "Add new" button is clicked

Features: #303 — Add navigation tabs

2.2.1
By Cyril Chapellier • Published on July 20, 2020

This is a utility release (no change in code) to fix npm release (v2.2.0) that had extra unwanted console.log()

2.2.0
By Cyril Chapellier • Published on June 10, 2020

This is a minor release following various bug fixes and improvements from the community

Fixes: #246 — Legend to show enum values #264 — User can now remove items if minItem is set (cf. #83 too) #279 — Improve selectfieldset behaviour

Features: https://github.com/jsonform/jsonform/commit/1b1daf239ee8dafffe89642b0a730d64d8c25f69 — Add htmlClass for sections https://github.com/jsonform/jsonform/commit/78787fbba8061ccef82d4ca683e809181b282134 — Prevent activating a selectfieldset in a tabarray Correct https links, indentation, spaces, etc

Maintenance: The jsonform.github.io website is now built from the master branch.

2.1.6
By Cyril Chapellier • Published on January 30, 2020

This is a minor release following various bug fixes and improvements from the community

Fixes : #261 — Allow number type fields to accept decimal numbers #246 — Updated the binding of changes when using a legend

2.1.5
By Cyril Chapellier • Published on June 19, 2019

This is a minor release following various bug fixes and improvements from the community

Fixes : https://github.com/jsonform/jsonform/issues/231 — Fix whitespaces in id / classnames https://github.com/jsonform/jsonform/issues/232 — Fix multiselect checkboxes not working with tabarray https://github.com/jsonform/jsonform/issues/233 — Fix expanded class on tabarray

Features : https://github.com/jsonform/jsonform/pull/230 — Allow numeric step "any" https://github.com/jsonform/jsonform/pull/239 — Update template {{values}} data on drag and drop

2.1.4
By Cyril Chapellier • Published on May 2, 2019

This is a minor release following various bug fixes and improvements from the community

Fixes : https://github.com/jsonform/jsonform/issues/138 — Array-elements are deactivated within selectfieldsets https://github.com/jsonform/jsonform/issues/210 — Nested array initial value not populated correctly https://github.com/jsonform/jsonform/issues/226 — AdvancedFieldSet Title / Legend can't be changed

Features : https://github.com/jsonform/jsonform/issues/86 — HTML5 input "range" and maximum with exclusiveMaximum=true

2.1.3
By Cyril Chapellier • Published on January 8, 2019

This is a minor release following various bug fixes from the community

We also add the htmlMetaData field to enable adding custom properties to elements.

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
2,542
Community Interest
3,059
Number of Forks
553

Maintenance

Commits
11/2110/2203
Last Commit
Open Issues
15
Closed Issues
324
Open Pull Requests
3
Closed Pull Requests
30

Versions

Versions Released
11/2110/2201
Latest Version Released
Sep 20, 2021
Current Tags
latest2.2.5

Dependencies

Dependencies (0)
Dev Dependencies (0)

Contributors

sylvinus
sylvinus
Commits: 68
tchapi
tchapi
Commits: 64
tidoust
tidoust
Commits: 28
steren
steren
Commits: 14
tbassetto
tbassetto
Commits: 12
dfs123d
dfs123d
Commits: 4
joelguittet
joelguittet
Commits: 3
sdetweil
sdetweil
Commits: 3
elibus
elibus
Commits: 2
kimsey0
kimsey0
Commits: 2
michaelmairegger
michaelmairegger
Commits: 2
coreyfournier
coreyfournier
Commits: 2
flisky
flisky
Commits: 2
semanticdreamer
semanticdreamer
Commits: 2
JoshuaFortriede
JoshuaFortriede
Commits: 2