JSON Forms – Make-It-Happen Blog Series – Pilot

JSON Forms is a framework to efficiently build form-based web UIs. These UIs are targeted at entering, modifying and viewing data and are usually embedded within an application. JSONForms eliminates the need to write HTML templates and Javascript for manual databinding to create customizable forms by leveraging the capabilities of JSON and JSON schema as well as by providing a simple and declarative way of describing forms. Forms are then rendered within a UI framework – currently based on AngularJS. If you would like to know more about JSON Forms the JSON Forms homepage is a good starting point.

In this blog series, we would like to introduce the framework based on a real-world example application called “Make It happen”. Step by Step, we will add new features to that example application and demonstrate, how JSON Forms eases the development for you. For a better overview, the development steps are organized in days, although we do not expect that it takes anywhere near a full work day to complete the individual steps :-). This series will provide an overview of all features and explain how they work. For a step-by-step and hands-on tutorial how to implement the described features, please see here.

If you would like to follow this blog series please follow us on twitter. We will announce every new blog post on JSON Forms there.

Before we get started, let us explain the big picture on “Day 0”

Day 0 – Basic Requirements

The example application we want to implement is a simple task tracker called “Make it Happen”. We have chosen this example as it is easy to understand, simple, but still provides the opportunity to show the core features of JSON Forms. Therefore, we will try to focus the requirements of the example application on demonstration purposes rather than real world concerns. In our example application, we want to be able to create, view, and modify one entity: tasks. Tasks have attributes such as a name, description, due date, and so on. The UI we would like to create contains a general view of all tasks, as well as a detailed view showing the details of one task. We will leave aside cross-cutting concerns such as authentication and authorization. Let us envision a basic UI capable of fulfilling these requirements. The UI shall show a list of all tasks, once you select a task, it should display the details on the right side (as shown in the following mock).

final_mockup

But enough about requirements for now, we will detail them iteratively while we demonstrate the implementation of the respective UI. So let us start the development with day 1 and create some simple forms.

Day 1 – A Simple Form

This article describes how to define simple forms with JSON Forms including explanatory examples. For a quick start with three steps only, please see here.

We will start to implement the described UI bottom-up. The first elements will be the detail view, for showing the details of an individual task. These views will display controls for all attributes of the entity (a task). Based on the specific attributes, corresponding controls should be used, e.g. a text field for a String attribute, a drop-down box for a Enum, or a date picker for selecting a date. To keep it simple, we will just add three basic attributes in the first iteration as shown in the following mock-up. We will enhance the forms in a later iteration, demonstrating how JSON Forms performs on an evolution of the data schema. In the first iteration, we will add the attributes:

  • “Name” (String) – mandatory
  • “Description” (String)
  • “Done” (Boolean).

The “Name” attribute is a mandatory one, so there should be a validation message, if the user fails to enter something here.

image09

Even for such a simple form, all three controls would have to be manually developed and data-bound. This includes additional features, such as input validation. JSON Forms directly utilizes a data schema based on the JSON schema standard. Therefore, we must only describe which attributes a task consists of. Defining a data schema is very useful even when one is not using JSON Forms, for example, it can be used to validate the data.

The following data schema (a.k.a. JSON Schema) defines the task entity:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "done": {
      "type": "boolean"
    }
  },
  required: [“name”]
}

With the listed schemata as an input, JSON Forms can already render a fully functional form-based UI, including data binding and validation. The only thing, we need to embed into our website is the following HTML tag:

 <jsonforms schema="taskSchema" data="taskData"></jsonforms>

The two properties “schema” and “data” point to JavaScript variables, which need to be defined in the scope of the directive. The variable “schema” points to the data schema as mentioned above, the variable “data” points to a JSON object, following this data schema. This object will be bound to the UI and therefore, is updated once you start editing the form.

The final result is a web page (shown in the screenshot below), which already shows a fully functional form-based UI.

day1_form

Data we enter in this form is already bound to an underlying data object. JSON Forms automatically renders the correct control for each data type. For the enumeration, a drop down would show the valid values.  Additionally, the form will automatically validate the data we enter. As an example, we have specified in the data schema, that the name of a user is mandatory, therefore, JSON Forms will shows us an error marker, if we do not enter a value for the name property.

This form is already a good starting point, however, there are obviously some customization requirements. As an example, we might want to change the order of controls, their label, and the layout which they are shown in. Additionally, the description field shall be rendered as multi-line. All this is possible with JSON Forms, and will be described on day 2 of this series.

If you are interested in trying out JSON Forms, please refer to the Getting-Started tutorial. It explains how to set up JSON Forms in your project and how you can try the first steps out yourself. If you would like to follow this blog series, please follow us on twitter. We will announce every new blog post on JSON Forms there.

We hope to see you soon for the next day!

 

List of all available days to date:

3 Responses to “JSON Forms – Make-It-Happen Blog Series – Pilot”

  1. David Wegener says:

    Thank you for your work creating JSONForms and putting this series together. I’m looking forward to following the subsequent days.

    I would like to make one suggestion with regard to Getting Started tutorial referenced. There is an important Angular “plumbing” requirement left out of the complete source section that ties the schemas/data to the controller dependency list. The schema files have to declare a module value in order for them to be passed as parameters to the controller initialization function. I didn’t understand how these linked together until I went and looked at the source in the git repo.

    The module declaration doesn’t belong in the example JSON that defines each schema since these are just showing what is required for the schema. However, a note at the end mentioning that the module declaration is needed to hook them up to the controller parameters would be helpful.

  2. Hi David, thank you for taking the time to write us! We will implement your proposal and update the tutorial.

  3. Edgar Mueller says:

    Hi David,
    thanks for your suggestions. I’ve updated the ‘Getting started’ section with the missing pieces.

Leave a Reply

3 responses so far

Written by . Published in Categories: Planet Eclipse

Looking for a job?

X
Karlsruhe / Remote
JavaScript
Mobile
Karlsruhe / Victoria / Remote
Windows
Mobile
Karlsruhe / Victoria / Remote
Java
Android
Mobile