<commit_before># Forme

Forme has been designed to offer a sane way for handling forms in nodejs using **promises**. A form can be built to handle a user input or even manage data from api requests. Forme does not dictate to you how a form should build, process or render. With forme you can handle forms in the way that suites you.

Your form object is created in such a way that it can be reused for multiple instances of that form. The request object will be used to store any live data when processing a particular instance of the form. You can also create a form per request if you need to add a dynamic set of fields.

Forme has no concept of rendering but does provide a simple way to build your template vars. The object containing all the variables can then be passed to the appropriate templating engine of choice.

- Create static or dynamic form objects to handle input in a generic fashion.
- Easily apply built in input handlers to process and validate your data.
- Integrate into the templating system of your choice.
- Not limited to any specific frameworks.
- Semi-Automatic session data handling using extendable session handler. 

The project is still in development so use with caution, however the functionality is there so feel free to have a play!


## Index

**Topics**
- [Custom Errors](#customErrors)
- [Input Type](#inputType)
- [Form Require Validation (and/or)](#formRequireValidation)
- [Grouping and Referencing Inputs](#groupingAndReferencingInputs)
- [Custom Form Validation](#customFormValidation)
- [Custom Input Validation](#customInputValidation)
- [Custom Submit Handling](#customSubmitHandling)
- [Order of Validation](#orderOfValidation)
- [Validation in final .then()](#validationInFinalThen)

**API/Reference**
- [Form](#apiForm)
- [Fnput](#apiInput)

**Examples**
- [Static Form](#staticFormExample)
- [Dynamic Form](#dynamicFormExample)
- [API Form](#apiFormExample)
- [Validate The Form](#validateExample)


## <a name="customErrors"></a> Custom Errors 

Many input methods allow you to provide a custom error string. For example:
```javascript
const forme = require('forme');

const form = forme('login').post('form/process.html');
form.add('username').label('Username').require().is('username','{label} is invalid');
```

You can see see in this example we have added a second argument *'{label} is invalid'* to the **.is()** method. This is our custom error that will be returned should the input fail the **.is()** test. Custom error messages can contain placeholder tokens, which will be automatically converted to useful information.
 
You can also use placeholder tokens with a small selection of form methods. For example when you call `form.validate(callback, error)`.
 
**Form Placeholder tokens:**<commit_msg>one of those days where you keep making tpyos!<commit_after># Forme

Forme has been designed to offer a sane way for handling forms in nodejs using **promises**. A form can be built to handle a user input or even manage data from api requests. Forme does not dictate to you how a form should build, process or render. With forme you can handle forms in the way that suites you.

Your form object is created in such a way that it can be reused for multiple instances of that form. The request object will be used to store any live data when processing a particular instance of the form. You can also create a form per request if you need to add a dynamic set of fields.

Forme has no concept of rendering but does provide a simple way to build your template vars. The object containing all the variables can then be passed to the appropriate templating engine of choice.

- Create static or dynamic form objects to handle input in a generic fashion.
- Easily apply built in input handlers to process and validate your data.
- Integrate into the templating system of your choice.
- Not limited to any specific frameworks.
- Semi-Automatic session data handling using extendable session handler. 

The project is still in development so use with caution, however the functionality is there so feel free to have a play!


## Index

**Topics**
- [Custom Errors](#customErrors)
- [Input Type](#inputType)
- [Form Require Validation (and/or)](#formRequireValidation)
- [Grouping and Referencing Inputs](#groupingAndReferencingInputs)
- [Custom Form Validation](#customFormValidation)
- [Custom Input Validation](#customInputValidation)
- [Custom Submit Handling](#customSubmitHandling)
- [Order of Validation](#orderOfValidation)
- [Validation in final .then()](#validationInFinalThen)

**API/Reference**
- [Form](#apiForm)
- [Input](#apiInput)

**Examples**
- [Static Form](#staticFormExample)
- [Dynamic Form](#dynamicFormExample)
- [API Form](#apiFormExample)
- [Validate The Form](#validateExample)


## <a name="customErrors"></a> Custom Errors 

Many input methods allow you to provide a custom error string. For example:
```javascript
const forme = require('forme');

const form = forme('login').post('form/process.html');
form.add('username').label('Username').require().is('username','{label} is invalid');
```

You can see see in this example we have added a second argument *'{label} is invalid'* to the **.is()** method. This is our custom error that will be returned should the input fail the **.is()** test. Custom error messages can contain placeholder tokens, which will be automatically converted to useful information.
 
You can also use placeholder tokens with a small selection of form methods. For example when you call `form.validate(callback, error)`.
 
**Form Placeholder tokens:**
{'fraction_non_alphanumeric': 0.08646413805500629, 'fraction_numerical': 0.0, 'mean_word_length': 4.92545260915868, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4451696', 'n_tokens_mistral': 1425, 'n_tokens_neox': 1366, 'n_words': 737}