@sixdeex/jaf

Just Another Form: a webcomponent to build forms using json schema

Usage no npm install needed!

<script type="module">
  import sixdeexJaf from 'https://cdn.skypack.dev/@sixdeex/jaf';
</script>

README

Just Another Form

Description

Render a simple form starting from an embedded or referenced schema. The form supports client side internationalization and client, and server, side errors.

See

  • examples/index.html
  • examples/login.html
  • examples/style.html

for examples and

  • docs/jaf-definition.schema.json

for the overall schema.

Usage

It is possible to import the webcomponent using

npm i --save @sixdeex/jaf

import { JafForm } from '@sixdeex/jaf'

which make the element available.

Using CDN (not really, TODO, but I would like to replace the gitlab wiki file):


<!DOCTYPE html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Hello Jaf component</title>
  <script src="https://gitlab.com/morphy76/jaf/-/wikis/uploads/f91ecbd7ea6d0517590751db3c3ea3d8/jaf.js"></script>
</head>

<body>
  <div class="form">
    <jaf-form id="loginForm" title="Sign In" src="/form-definition.json"></jaf-form>
  </div>
</body>

</html>

Definition schema

Form schema

See docs/form.schema.json

Validation schema

See docs/validate.schema.json

Initial values schema

Part of docs/jaf-definition.schema.json

Errors schema

See docs/errors.schema.json

Internationalization schema

See docs/labels.schema.json

How validation works

Fields with validation rules provide client side validation; the rules are:

  • required, the value cannot be null or undefined, blank strings are allowed;
  • not_blank, like required but not allowing blank values;
  • is_digit, the field value must be made of digits;
  • min, like is_digit but the value must be greater than a given minimum;
  • max, like is_digit but the value must be lesser than a given maximum;
  • is_date, the field value is a date;
  • regex, the field value must match a given regular expression;
  • is_email, like regex with a preconfigured regular expression to check emails.

Validation happens when the definition validate element is provided; oherwise, rules in the definition schema element are just for rendering purposes.

{
  "schema": {
    "field1": {
      "type": "text",
      "required": true # used for rendering rules of the field
    }
  },
  "validate": {
    "field1": {
      "not_blank": "Field one is mandatory" # used for client side validation
    }
  }
}

How internationalization works

Translations are provided in the definition labels element, if the translation is not found, the key is printed as is.

Translation keys can be provided for every textual content.

{
  "schema": {
    "field1": {
      "type": "text",
      "title": "Field one", # printed as is because no key is matched in the labels
      "required": true
    }
  },
  "validate": {
    "field1": {
      "not_blank": "field.one.mandatory" # a key is matched, hence this value is translated
    }
  },
  "labels": {
    "default": "en",
    "translations": {
      "en": {
        "field.one.mandatory": "Field one is mandatory"
      },
      "en": {
        "field.one.mandatory": "Field one รจ obbligatorio"
      }
    }
  }
}

Events

on-submit

Catch the custom event on-submit which holds the form values in the detail attribute, e.g.:

document.getElementById('myJafForm').addEventListener('on-submit', onSubmitEvent => console.log(onSubmitEvent.detail));

API

addErrors

Inject a JSON object defined by the error schema in order to provide server side state about fields and errors; e.g.:

document.getElementById('loginForm').addErrors({
  form_messages: 'Login failed',
  values: onSubmitEvent.detail,
  messages: {
    username: 'Not found'
  }
});

Theming

Theming is acieved defining CSS variables in the document using the Jaf Form.

Form CSS variables

--jaf-font-family

default Sans-Serif

--jaf-form-direction

default column

--jaf-form-wrap

default nowrap

--jaf-form-grow

default 1

--jaf-form-shrink

default 0

--jaf-form-justify-items

default flex-start

--jaf-form-align-items

default stretch

--jaf-form-border

default none

--jaf-form-margin

default 0px

--jaf-form-padding

default 0px

--jaf-title-font-family

default --jaf-font-family

--jaf-title-font-size

default 1em

--jaf-title-align

default center

--jaf-title-font-weight

default bold

--jaf-button-margin

default 10px

--jaf-button-margin-left

default --jaf-button-margin

--jaf-button-margin-right

default --jaf-button-margin

--jaf-button-margin-top

default --jaf-button-margin

Form component variables

--jaf-group-margin-bottom

default 5px

--jaf-label-font-family

default --jaf-font-family

--jaf-label-font-size

default .75em

--jaf-control-font-family

default --jaf-font-family

--jaf-control-font-size

default 1em

--jaf-control-margin-top

default 1px

--jaf-control-margin-right

default 1px

--jaf-control-margin-bottom

default 0px

--jaf-control-margin-left

default 0px

Form controls

--jaf-button-font-size

default .75em

--jaf-control-border

default 1px solid darkgray

--jaf-control-border-radius

default 0px

--jaf-control-border-top-left-radius

default --jaf-control-border-radius

--jaf-control-border-top-right-radius

default --jaf-control-border-radius

--jaf-control-border-bottom-left-radius

default --jaf-control-border-radius

--jaf-control-border-bottom-right-radius

default --jaf-control-border-radius

Errors

--jaf-error-background-color

default yellow

--jaf-error-main-color

default black

--jaf-error-notification-color

default red