hl-json-forms

Hotelinking Json Forms

This library is used to paint forms using the Hotelinking design system.

Prerequisites

This project requires NodeJS (version 16.19.0 or later) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
9.8.0
v20.5.1

Installation

The recommended way to install the latest version of the Hotelinking Json Forms library is by running the command below:

npm install hl-json-forms

Documentation

For extra information about the project, visit our Confluence https://hotelinking.atlassian.net/wiki/spaces/MA/pages/3014590503/JSON+Forms.

Usage

In the App.vue file you can see a demo example that uses this library. You can see the result running this command:

npm run dev

In summary, the App.vue file renders a form using the JSONForms library. It imports the JsonForms component, which is the primary and only export of this library. The form is configured using a JSON schema, a UI schema, and data passed as props to the JsonForm component. Similarly, the JsonForm component must be imported and used in the different projects that consume it. This setup allows for dynamic rendering and interaction with form data. 'Data'contains the initial form data. 'Schema' defines the structure and constraints of the form data. It ensures that the form adheres to specific rules and validation criteria. 'Uischema' specifies the layout and appearance of the form. It dictates how the fields defined in the schema should be rendered, including their order, grouping, and specific UI controls. Renderers are components responsible for rendering the individual form controls based on the schema and UI schema. Each renderer is specialized to handle a particular type of data or control (e.g., dropdown, checkbox, input), using our design system. Each renderer has an entry file where it is defined. This file includes the renderer's implementation and a tester function. The tester function determines whether the renderer is appropriate for a given schema and UI schema combination. It evaluates the schema and UI schema and returns a score indicating its suitability. The renderer with the highest score is chosen to render the form control.

Here is a basic example of use. In it, we render a form with two components, uiToggle and uiDropdown, for the form fields availability and language, respectively. In the example, we set language as required and give to it a initial value.

1. In the project that uses jsonForms, import jsonForm component.

   import { JsonForm } from "hl-json-forms";

2. Pass it through props schema, uiSchema, data (if I want to initialize the form with certain values) and onChange.

   <JsonForm
      :data="data"
      :schema="schema"
      :uiSchema="uiSchema"
      :onChange="onChange"
   />

3. Schema:

const schema = {
  type: "object",
  properties: {
    availability: {
      type: "boolean",
    },
    language: {
      type: "string",
      enum: ["Español", "Inglés"],
    },
  },
  required: ["language"]
} 

uiSchema:

   const uischema = {
      type: "VerticalLayout",
      elements: [
         {
            type: "Control",
            scope: "#/properties/availability",
            label: "Habitación no disponible",
         },
         {
            type: "Control",
            scope: "#/properties/language",
            uiComponent: "dropdown",
            label: "Elegir idioma",
         },
      ]
   }   

Data:

   const data = ref({
      language: "Español"
   })

onChange:

   const onChange = (event) => {
      console.log("Data", event.data)
      console.log("Errors", event.errors)
   };

Project Structure

The project is organized into several directories under the src folder:

• components: Contains the main JsonForm component and related interfaces.
• jsonformSchema: Defines the JSON schema and UI schema for the forms.
• locales: Contains internationalization files for different languages.
• renderers: Includes various renderers for different form elements and layouts.

Internationalization

The project supports internationalization (i18n) with translations available for English and Spanish. The localization files are located in the src/locales directory.

Local development

If you need to make changes to this library and test in a local project, you can bind the dependency of the library to a project without publishing the library on every change. Use this commands to view the changes in your local repository.

In the project to bind

1. npm link hl-json-forms
2. Go to vite.config and add

   optimizeDeps: {
      exclude: ["hl-json-forms"],
   }
   

In this repo

  npm link
  npm run build:watch

Back to Normal

   cd ~/projects/my-app
   npm unlink hl-json-forms
   npm i hl-json-forms

You can clean up the global link, though its presence won't interfere with my-app.

   cd ~/projects/some-dep
   npm uninstall  # Delete global symlink

its presence won't interfere with my-app.**

   cd ~/projects/some-dep
   npm uninstall  # Delete global symlink