Introduction to JSONForms

1. Overview

In the first article of this series we introduced the concept of JSON Schema and how to use it for validating the format and structure of a JSON Object.

In this article we’ll see how to build form-based web UIs by leveraging the capabilities of JSON and JSON Schema.

To achieve our goal we’ll use a framework called JSON Forms. It eliminates the need to write HTML templates and Javascript for data binding by hand to create customizable forms.

Forms are then rendered with a UI framework, currently is based on AngularJS.

2. Components of a JSON Form

To create our form we need to define two main components.

The first component is the data schema defines the underlying data to be shown in the UI (object types and their properties).

In this case we can use the JSON Schema that we used in the previous article to describe a data object “Product”:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from the catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

As we can see, the JSON Object shows three properties named id, name and price. Each of them will be a form field labeled by it’s name.

Also each property has some attributes. The type attribute will be translated by the framework as the type of the input field.

The attributes minimum, exclusiveMinimum specifically for the price property tells the framework that at validation time of the form the value of that input field must be greater than 0.

Finally, the required property, which includes all the properties previously defined specifies that all form fields are required to be filled.

The second component is the UI schema describes the layout of the form and which properties of the data schema are to be rendered as controls:

{
    "type": "HorizontalLayout",
    "elements": [
        {
            "type": "Control",
            "scope": { "$ref": "#/properties/id" }
        },
        {
            "type": "Control",
            "scope": { "$ref": "#/properties/name" }
        },
        {
            "type": "Control",
            "scope": { "$ref": "#/properties/price" }
        },
    ]
}

The type property defines as the form fields will be ordered in the form. In this case we have chosen a horizontal fashion.

Also, the UI Schema defines which property of the data schema will be displayed as a form field. This is obtained by defining an element Control in the elements array.

Finally, Controls directly reference the data schema by the scope property, so that the specification of data properties, such as their data type, does not have to be replicated.

3. Use JSON Forms in AngularJS

The created data schema and UI schema are interpreted during runtime, which is when when the web page that contains the form is displayed on the browser, and translated into an AngularJS based UI, which is already fully functional including data binding, validation, etc.

Now, let’s see how to embed JSON Forms inside an AngularJS based web application.

3.1. Setup the Project

As a prerequisite to setup our project we need node.js installed in our machine. If you haven’t installed it before you can follow the instruction at the official site.

node.js also come with npm, which is the package manager used to install the JSON Forms library and the other needed dependencies.

Once installed node.js and after cloning the example from GitHub, open a shell and cd into the webapp folder. This folder contains among other the package.json file. It shows some information about the project and mostly tells to npm which dependencies it must download. The package,json file will look like as the following:

{
    "name": "jsonforms-intro",
    "description": "Introduction to JSONForms",
    "version": "0.0.1",
    "license": "MIT",
    "dependencies": {
         "typings": "0.6.5",
         "jsonforms": "0.0.19",
         "bootstrap": "3.3.6"
     }
}

Now, we can type the npm install command. This will start the download of all the needed libraries. After the download we can find these libraries inside the node_modules folder.

For more details you can refer the jsonforms npm’s page.

4. Define the View

Now that we have all the needed libraries and dependencies, let’s define an html page Showing the Form.

In our page we need to import the jsonforms.js library and embed the form by using the dedicated AngularJS directive jsonforms:

<!DOCTYPE html>
<html ng-app="jsonforms-intro">
<head>
    <title>Introduction to JSONForms</title>
    <script src="node_modules/jsonforms/dist/jsonforms.js" 
      type="text/javascript"></script>
    <script src="js/app.js" type="text/javascript"></script>
    <script src="js/schema.js" type="text/javascript"></script>
    <script src="js/ui-schema.js" type="text/javascript"></script>
</head>
<body>
    <div class="container" ng-controller="MyController">
        <div class="row" id="demo">
            <div class="col-sm-12">
                <div class="panel-primary panel-default">
                    <div class="panel-heading">
                        <h3 class="panel-title"><strong>Introduction 
                          to JSONForms</strong></h3>
                    </div>
                    <div class="panel-body jsf">
                        Bound data: {{data}}
                        <jsonforms schema="schema" 
                          ui-schema="uiSchema" data="data"/>
                    </div>
                </div>
            </div>
        </div>
    </div>
</body>
</html>

As parameters of this directive, we need to point to the data schema and the UI schema defined above, plus a JSON object that will contain the data to be displayed.

5. The AngularJS Controller

In an AngularJS application, the values needed from the directive are typically provided by a controller:

app.controller('MyController', ['$scope', 'Schema', 'UISchema', 
  function($scope, Schema, UISchema) {

    $scope.schema = Schema;
    $scope.uiSchema = UISchema;
    $scope.data = {
        "id": 1,
        "name": "Lampshade",
        "price": 1.85
    };
}]);

6. The App Module

Next we need to inject the jsonforms in our app module:

var app = angular.module('jsonforms-intro', ['jsonforms']);

7. Showing the Form

If we open the html page defined above with the browser we can see our first JSONForm:

8. Conclusion

In this article we have seen how to use the JSONForms library to build an UI Form. Coupling a data schema and an UI schema it eliminates the need to write HTML templates and Javascript for data binding by hand.