@sixdeex/jaf NPM

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

default Sans-Serif
default column
default nowrap
default 1
default 0
default flex-start
default stretch
default none
default 0px
default 0px
default --jaf-font-family
default 1em
default center
default bold
default 10px
default --jaf-button-margin
default --jaf-button-margin
default --jaf-button-margin

Form component variables

default 5px
default --jaf-font-family
default .75em
default --jaf-font-family
default 1em
default 1px
default 1px
default 0px
default 0px

Form controls

default .75em
default 1px solid darkgray
default 0px
default --jaf-control-border-radius
default --jaf-control-border-radius
default --jaf-control-border-radius
default --jaf-control-border-radius

Errors

default yellow
default black
default red

form json schema builder client validation css theme webcomponent polymer litelement front-end

uuid lit-element lit-html

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago