forms-generator
Advanced tools
Forms Generator is a library for Node.js that helps with HTML forms.
A very simple and concise JS description is used to define forms. Form definitions are separate from things like label values, label internationalisation, style attributes and field data validation. Such separation provides a way not to mix model and view related things, but still eliminating typical HTML forms redundancy.
This demonstration will show the basic workflow for express with Jade and i18n integration.
So lets create a simple singup form:
var regForm = new Form(
"regForm", null, { action : "forms/regForm" },
[ "name", "text" ],
[ "pass", "password" ],
[ "mail", "email"],
[ "mailVisibility", "radio", null, "none", "friends", ["all" , {checked : true}]],
[ "acceptTerms", "checkbox"],
[ "register", "button"]);
This will create the form definition, with the custom action route (by
default a generated action for this form is "regFormSend").
Then lets assign a data validator for the name field:
function validateName(data, i18n, cb) {
process.nextTick(
function() {
if(!data || !validator.isLength(data[0], 4, 20)) {
cb(i18n.__("error_short_name"));
} else {
cb(false);
}});
}
regForm.setValidator("name", validateName);
It will emulate some DB based login checking, which is an asynchronous operation. Note that error data can be an arbitrary non-false object, using i18n is optional here.
The form send route with parsing, validation and response will be:
regForm.setFormRoute(app, function(req, res, next) {
var cbFAIL = function(errors) {
res.setHeader('Content-Type', 'text/html');
res.send(JSON.stringify(errors));
};
var cbOK = function(fields, files) {
res.send(JSON.stringify(null));
};
var parser = new fg.FormParser();
parser.parse(req, function(err, fields, files) {
console.log("Fields:\n%s\nFiles:\n%s", util.inspect(fields), util.inspect(files));
regForm.validate(fields, files, req, cbOK, cbFAIL);
});
});
setFormRoute method will add a route to an application/router
according to forms action and method attributes.
Form get route is simple:
app.use('/', function(req, res) {
res.render("index", {
regForm: regForm.getContent(req)
});
});
It will pass regForm object to the index template. getContent method
will populate and cache labels for the request locale (or the default
locale, if the request one is not enabled).
The procces of creating field labels is separated and depends on language settings. Here is our en.json file with the labels mapping for "en" locale:
{
"regForm-name": "Username",
"regForm-pass": "Password",
"regForm-mail": "Mail",
"regForm-mailVisibility-none": "None",
"regForm-mailVisibility-friends": "Friends only",
"regForm-mailVisibility-all": "Everyone",
"regForm-mailVisibility": "Show mail to:",
"regForm-acceptTerms": "I accept the Terms of Service",
"regForm-register": "Submit",
"error_short_password": "Short password",
"error_malformed_mail": "Malformed mail",
"error_terms": "You have to agree with the Terms of Service",
"error_short_name": "Short name"
}
Another separate operation is form styling. Here is index.jade file:
mixin link(name, url)
a(href=url) #{name}
doctype html
html
head
meta(charset='utf-8')
link(rel='stylesheet', href='http://yui.yahooapis.com/pure/0.6.0/pure-min.css')
script(src='https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js')
script(src='/res.js')
body
+Form( regForm, { "@::attributes" : { "class" : "pure-form pure-form-stacked" },
"@-acceptTerms--name::after" : [ "link", "(?)", "/terms.txt" ] } )
hr
div#response
From mixin call renders an actual HTML form. The second argument is
additional information that is inserted into rendered forms. Here we
are adding class attributes to the form tag and appending results of
link mixin to the acceptTerms label element. So elements, that are
used only in styling and not affecting server form parsing, are kept
separate.
And the last thing is res.js browser code.
function regFormOnload() {
var response = $("#regFormIframe").contents().find("body").text();
$("#response").text(response);
}
regFormOnload function name and regFormIframe are generated from
the form definition. It will just output a server response, but errors
object is a simple name to object store, so displaying errors in a
pretty way is rather trivial.
Note that no any browser code is provided with the library and no any
assumptions about client side stack are made. But integration with
existing solutions for client side validation, live
validation/completion is possible. For example HTML5 data-
attributes in a form definition can be used for mapping client side
functions.
The full application code is in a tutorial directory. For more
information look at Description, Example and API sections.
The main interface is Form class, which creates form
definitions. These definitions could be directly rendered to HTML via
render method. Or getContent method could be used to get an object
suitable as an argument for Jade Form mixin. In this case HTML will
be rendered as a part of Jade template.
Note: Neither i18n nor jade are included in the production
dependencies, but rather they are expected by some methods as
arguments. Jade should be compatible with version ^1.9.0 (also
pug 1.x may be used) and i18n with version ~0.5.0 or ~0.8.0.
Each form field should have an ID that is used for several
purposes. All IDs should match /^~?[a-zA-Z_][a-zA-Z0-9_]*$/ regular
expression. ~ prefix is stripped from actual IDs.
The first one is generating HTML ID attributes. All fields IDs are
prefixed with a form ID. Also field entries (they are used for some
field types like radio buttons) are prefixed with a field ID. So
generated HTML ID attributes will look like
FormID-FieldID-EntryID. Single - is used as a nesting separator,
-- is used to separate ID suffixes for additional elements like
labels or wrappers.
The second one is generating translation labels for fields. By default
translation IDs generation algorithm is the same as the HTML one, but
using non-prefixed IDs is allowed. nTP function disables prefixing
for a single ID. Prefixing ID with ~ is similar to using nTP
function. Also from class constructor options allow customisation of
form translation IDs generation. HTML ID attributes are not affected
by any of these options.
The last one is form data format. Forms field names will be the same as IDs. Also radio, select and checkbox field values will contain values matching theirs entries IDs.
By default no any validation is performed. User supplied asynchronous
functions can be used in a validation. Validators can be set by
setValidator and setGlobalValidator methods. Each field can have
one validation function that validates only a field data. Global
validator can be used for a more complex validation that requires an
access to all fields data. It is possible to run a full validation
with validate method, or execute just one validator with
runValidatator and runGlobalValidatator methods. All data for
validation should be in the Multiparty parser (it is provided by
FormParser class) format.
/^~?[a-zA-Z_][a-zA-Z0-9_]*$/"div" | "fieldset" | "textarea" | "select" |
"button" | "datalist" | "keygen" | "output" | "text" |
"password" | "radio" | "checkbox" | "file" | "hidden" |
"image" | "reset" | "submit" | "color" | "date" |
"datetime-local" | "email" | "month" | "number" | "range"
| "search" | "tel" | "time" | "url" | "week"attributes-object | null | attributes-arrayattributes-object , [ attributes-object , attributes-object , attributes-object ]
]attributes-object , [ attributes-object , attributes-object , attributes-object ]
]group : group-array }Subfields can be used only with with several field types. Entries are
allowed for "checkbox", "radio", "select" and "datalist"
types. Entries groups are only allowed for "select", the depth must
be only of one level (it makes possible to define HTML select
optgroups). "radio" and "select" fields must contain one or more
entries. Fields nesting is only allowed for "div" and "fieldset"
types, nested fields are wrapped with respective tags. "fieldset"
must contain one or more fields, but "div" can be empty.
attributes-object with attribute : value pairs is used to set
input HTML elements attributes. attributes-array is used to set
attributes to the following elements: attributes-array[0] - actual
form input attributes, attributes-array[1] - wrapper attributes,
attributes-array[2] - label attributes, attributes-array[3] -
attributes for an additional element (it is used for datalist,
checkbox/radio field names and form iframe elements). If there is no
such element, then its attributes are ignored.
This operations doesn't alter a form definition, separating view style operations. As a result a form can have several custom view renders.
It is possible to insert attributes and HTML elements into generated forms with an object. Object key are the following selectors prefixed by an element HTML ID:
::before insertion before an element::after insertion after an element::attributes insertion of element attributesFor ::before and ::after selectors values can be either HTML
strings or arrays with mixin name and arguments (up to 9 mixin
arguments are supported). Or attribute objects for ::attributes
selector. Class attributes are concatenated, preserving classes
defined in a form constructor.
Another way to insert attributes, based on tag/type combination, is a
user supplied attrsExtender function. It should return an
attributes-object and it recieves the following arguments:
tag - string HTML tag name.type - string almost the same as field type, with the exeption
of "checkboxSingle"type, that is used for single checkboxes.class - string with a class that is added to some form elements
by default or null.IDs can be abbreviated with the help of @ syntax, so selectors will
look like @-FieldID-EntryID::Selector.
Express 4 example application with pure-form CSS style is in an
example directory.
Constructor
Throws:
Error with a string description on malformed item definitions.Arguments:
id - string matching /^~?[a-zA-Z_][a-zA-Z0-9_]*$/ regular
expression, or a result of nTP function.options - object with form options or null. Fields:
i18nNoPrefix - boolean option to turn off all prefixes for
translation ids, false by default.i18nFormID - string with a form ID, overrides a default form
ID in translations.i18nNoEntryPrefix - boolean option to turn off entries
prefixing with field IDs, false by default.attributes - object or array for form tag attributes or
null....fields - Rest arguments are interpreted as field definitions.Method
Express form receive route helper.
Arguments:
router mutable - Express router.callback - Express route callback.Method [async]
Asynchronous form validation against previously defined validators via
setValidator function. Order of fields and files validation
functions execution is undefined. After passing all local validations,
global validator set by setGlobalValidator is executed. Local,
global or both validators can be undefined, meaning that any data pass
validation stage.
NOTE: For legacy reasons this method does not follow node style callbacks convention.
Arguments:
fields - object with Multiparty fields data or null.files - object with Multiparty files data or null.i18n - i18n translation library.callbackPass - Function called on successful form
validation. Arguments:
fields - object with Multiparty fields data.files - object with Multiparty files data.callbackFail - function called when form validation
fails. Arguments:
errors - object with validation errors or null. It
contains either field : error pairs for field validation
errors, or an object with one "form-error" : error pair for a
global validation error.Method [async]
Runs only a specific field validator.
Arguments:
fieldID - string with a field ID.data - object with Multiparty field data.i18n - i18n translation library.
callback - function callback to run after validation. Arguments:
error - true value with an error or false value.data - object with Multiparty field data or null.Method [async]
Runs only a global validator.
Arguments:
fields - Multiparty fields data or null.files - Multiparty files data or null.i18n - i18n translation library.callback - function callback to run after validation.
error - true value with an error or false value.fields - Multiparty fields data or null.files - Multiparty files data or null.Method
Validation helper. Returns expected values for fields that contain a fix set of entries.
Arguments:
fieldID - string with a field ID.Returns:
Array with expected string values, or an empty Array if no
specific values are expected, or undefined if a form has no
such field.Method
Check whether or not a form has a field with a supplied ID.
Arguments:
fieldID - string with a field ID.Returns:
boolean true if a form has a field with an ID, false
otherwise.Method [mutable]
Field validator setter. Validator should always call a callback and
expect data to be undefined or null.
Arguments:
fieldID - string with a field ID.validator - function validator. Arguments:
data - Array of Multiparty file/field data.i18n - i18n translation library.cb - function callback to run after validation. Arguments:
error - true value with an error or false value.Method [mutable]
Global validator setter. Validator should always call a callback and
expect fields, files or both to be null, undefined or miss
some fields data.
Arguments:
globalValidator - function global validator. Arguments:
fields - Multiparty fields data or null.files - Multiparty fields data or null.i18n - i18n translation library.cb - function callback to run after validation. Arguments:
error - true value with an error or false value.Method [caches results]
Expands form for i18n locale and caches results.
Arguments:
i18n - i18n translation library.skipCache optional - Ignore the current cache and re-expand content.Returns:
object for Jade form render.Method
Renders HTML form.
Arguments:
jade - jade library (also pug 1.x may be used).options - jade and render options or null. Render options:
attrsExtender - function that extends HTML tags attributes.skipCache - Ignore the current cache and re-expand content.i18n - i18n translation library.insertions optional - object with HTML insertions or
null....includeJadeFiles optional - The rest arguments are treated as
jade files pathnames to include.Returns:
string HTML form.Constructor
Same as multiparty.Form. External form parser with the same results
format could be used.
Function
Wrapper for strings translation via __ function.
Arguments:
str - string to translate.Returns:
object that will be translated with a form.
Function
Wrapper for strings translation via __n function.
Arguments:
str - string to translate.n - integer.Returns:
object that will be translated with a form.
Function
Forces usage of unprefixed IDs for translation.
Arguments:
id - string matching /^~?[a-zA-Z_][a-zA-Z0-9_]*$/ regular
expression.Returns:
object that could be used as ID in form definitions.
Function [module configuration]
Enables auto-adding form IDs to locale files when a form is defined (by default locale files are filled only when a form is expanded to a locale).
Arguments:
generator - i18n translation library or null to disable
generation.locales - array of locales or null to disable generation.Constant
Path to Jade mixins file. This file contains Form mixin which
performs HTML rendering.
Mixin
Renders form.
Arguments:
data - form data (a result of js From.getContent method).insertions optional - object with HTML insertions data or null.attrsExtender optional - function that extends HTML tags
attributes or null.FAQs
A library that helps with HTML forms
We found that forms-generator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.