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/jafimport { 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