1 | # Webform Toolkit
|
2 |
|
3 | [![npm version](https://badge.fury.io/js/webform-toolkit.svg)](https://badge.fury.io/js/webform-toolkit) [![](https://img.shields.io/npm/dm/webform-toolkit)](https://www.npmjs.com/package/webform-toolkit) [![Build Status](https://img.shields.io/github/actions/workflow/status/nuxy/webform-toolkit/.github%2Fworkflows%2Fci.yml)](https://github.com/nuxy/webform-toolkit/actions) [![Install size](https://packagephobia.com/badge?p=webform-toolkit)](https://packagephobia.com/result?p=webform-toolkit) [![](https://img.shields.io/github/v/release/nuxy/webform-toolkit)](https://github.com/nuxy/webform-toolkit/releases)
|
4 |
|
5 | Create a HTML form with field validation and custom errors.
|
6 |
|
7 | ![Preview](https://raw.githubusercontent.com/nuxy/webform-toolkit/master/package.gif)
|
8 |
|
9 | ## Features
|
10 |
|
11 | - Extensible HTML/CSS interface.
|
12 | - Compatible with all modern desktop and mobile web browsers.
|
13 | - Easy to set-up and customize. **No dependencies**.
|
14 | - Provides form input validation using REGEX ([regular expressions](http://www.regular-expressions.info/reference.html))
|
15 | - Supports synchronous form-data POST
|
16 | - Supports FORM submit callback for custom AJAX handling.
|
17 | - Supports dynamic ([on the fly](#adding-fields)) field creation.
|
18 |
|
19 | Checkout the [demo](https://nuxy.github.io/webform-toolkit) for examples of use.
|
20 |
|
21 | ## Dependencies
|
22 |
|
23 | - [Node.js](https://nodejs.org)
|
24 |
|
25 | ## Installation
|
26 |
|
27 | Install the package into your project using [NPM](https://npmjs.com), or download the [sources](https://github.com/nuxy/webform-toolkit/archive/master.zip).
|
28 |
|
29 | $ npm install webform-toolkit
|
30 |
|
31 | ## Usage
|
32 |
|
33 | There are two ways you can use this package. One is by including the JavaScript/CSS sources directly. The other is by importing the module into your component.
|
34 |
|
35 | ### Script include
|
36 |
|
37 | After you [build the distribution sources](#cli-options) the set-up is fairly simple..
|
38 |
|
39 | ```html
|
40 | <script type="text/javascript" src="path/to/webform-toolkit.min.js"></script>
|
41 | <link rel="stylesheet" href="path/to/webform-toolkit.min.css" media="all" />
|
42 |
|
43 | <script type="text/javascript">
|
44 | webformToolkit(container, settings, callback);
|
45 | </script>
|
46 | ```
|
47 |
|
48 | ### Module import
|
49 |
|
50 | If your using a modern framework like [Aurelia](https://aurelia.io), [Angular](https://angular.io), [React](https://reactjs.org), or [Vue](https://vuejs.org)
|
51 |
|
52 | ```javascript
|
53 | import WebFormToolkit from 'webform-toolkit';
|
54 | import 'webform-toolkit/dist/webform-toolkit.css';
|
55 |
|
56 | const webformToolkit = new WebformToolkit(container, settings, callback);
|
57 | ```
|
58 |
|
59 | ### HTML markup
|
60 |
|
61 | ```html
|
62 | <div id="webform-toolkit"></div>
|
63 | ```
|
64 |
|
65 | ### Example
|
66 |
|
67 | ```javascript
|
68 | const settings = {
|
69 | action: 'https://www.domain.com/handler',
|
70 | params: 'name1=value1&name2=value2',
|
71 | submit: false, // Override submit button creation.
|
72 | groups: [
|
73 | {
|
74 | legend: 'Login Form',
|
75 | fields: [
|
76 | {
|
77 | id: 'username',
|
78 | label: 'User Name',
|
79 | type: 'text',
|
80 | name: 'username',
|
81 | value: null,
|
82 | maxlength: 15,
|
83 | filter: '^\\w{0,15}$',
|
84 | description: null,
|
85 | placeholder: null,
|
86 | error: 'Supported characters: A-Z, 0-9 and underscore',
|
87 | required: true
|
88 | },
|
89 | {
|
90 | id: 'password',
|
91 | label: 'Password',
|
92 | type: 'password',
|
93 | name: 'password',
|
94 | value: null,
|
95 | maxlength: 15,
|
96 | filter: '^(?!password)(.{0,15})$',
|
97 | description: null,
|
98 | placeholder: null,
|
99 | error: 'The password entered is not valid',
|
100 | required: true
|
101 | }
|
102 | ]
|
103 | }
|
104 | ]
|
105 | };
|
106 |
|
107 | const container = document.getElementById('webform-toolkit');
|
108 |
|
109 | const webformToolkit = new WebformToolkit(container, settings, callback);
|
110 | ```
|
111 |
|
112 | ## Supported types
|
113 |
|
114 | [checkbox](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox), [color](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color), [date](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date), [email](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email), [file](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file), [hidden](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/hidden), [number](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number), [password](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password), [quantity](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/quantity), [radio](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio), [range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range), [select](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select), [submit](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit), [text](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text), [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea), [time](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time)
|
115 |
|
116 | ## Field definitions
|
117 |
|
118 | | Attribute | Description | Required |
|
119 | |-------------|---------------------------------------------------------|----------|
|
120 | | id | Field ID value. | true |
|
121 | | label | Field label value. | true |
|
122 | | type | [Supported types](#supported-types) | true |
|
123 | | name | Form element name. | true |
|
124 | | value | Default value. | false |
|
125 | | maxlength | Input maximum length ([password](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password), [text](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text)) | false |
|
126 | | max | Input number max ([number](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number), [quantity](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/quantity)) | false |
|
127 | | min | Input number min ([number](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number), [quantity](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/quantity)) | false |
|
128 | | step | Input number step ([range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range)) | false |
|
129 | | filter | Validate form input using REGEX | false |
|
130 | | description | Custom field description. | false |
|
131 | | placeholder | Input field type placeholder text. | false |
|
132 | | error | Custom error message (Required, if `filter` is defined) | false |
|
133 | | required | Required field. | false |
|
134 |
|
135 | ## Callback processing
|
136 |
|
137 | When a callback function is defined a form object is returned. This allows you to define a custom AJAX handler based on the requirements of your application. The following function corresponds to the [example](#usage) provided above.
|
138 |
|
139 | ```javasctipt
|
140 | function callback(form) {
|
141 | const xhr = new XMLHttpRequest();
|
142 |
|
143 | xhr.addEventListener('load', function() {
|
144 | if (this.status == 200) {
|
145 | alert(response);
|
146 | }
|
147 | });
|
148 |
|
149 | xhr.open('POST', form.getAttribute('action'));
|
150 | xhr.send(new FormData(form));
|
151 | }
|
152 | ```
|
153 |
|
154 | ## Adding fields
|
155 |
|
156 | I have added a method to dynamically create form fields that can be added to an existing webform. An optional callback has also been provided to for post-processing FORM and field elements. This makes it easy to show/hide fields using conditions and expressions.
|
157 |
|
158 | ```javascript
|
159 | webformToolkit.create({
|
160 | id: 'new_field_id',
|
161 | label: 'New Field',
|
162 | type: 'text',
|
163 | name: 'new_field',
|
164 | value: null,
|
165 | maxlength: null,
|
166 | filter: '^[a-zA-Z0-9_]{0,255}$',
|
167 | description: 'This is my new field',
|
168 | placeholder: null,
|
169 | error: 'Supported characters: A-Z, 0-9 and underscore',
|
170 | required: true
|
171 | },
|
172 | function(form, elm) {
|
173 | form.appendChild(elm); // default: last in fieldset
|
174 | });
|
175 | ```
|
176 |
|
177 | ## Best practices
|
178 |
|
179 | Just because you are filtering form input on the client-side is NO EXCUSE to not do the same on the server-side. Security is a two-way street, and BOTH ends should be protected.
|
180 |
|
181 | ## Developers
|
182 |
|
183 | ### CLI options
|
184 |
|
185 | Run [ESLint](https://eslint.org) on project sources:
|
186 |
|
187 | $ npm run lint
|
188 |
|
189 | Transpile ES6 sources (using [Babel](https://babeljs.io)) and minify to a distribution:
|
190 |
|
191 | $ npm run build
|
192 |
|
193 | Run [WebdriverIO](https://webdriver.io) E2E tests:
|
194 |
|
195 | $ npm run test
|
196 |
|
197 | ## Contributions
|
198 |
|
199 | If you fix a bug, or have a code you want to contribute, please send a pull-request with your changes. (Note: Before committing your code please ensure that you are following the [Node.js style guide](https://github.com/felixge/node-style-guide))
|
200 |
|
201 | ## Versioning
|
202 |
|
203 | This package is maintained under the [Semantic Versioning](https://semver.org) guidelines.
|
204 |
|
205 | ## License and Warranty
|
206 |
|
207 | This package is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
|
208 |
|
209 | _webform-toolkit_ is provided under the terms of the [MIT license](http://www.opensource.org/licenses/mit-license.php)
|
210 |
|
211 | ## Author
|
212 |
|
213 | [Marc S. Brooks](https://github.com/nuxy)
|