HTML forms on performance-enhancing drugs.
Note: Ajax-form is not tied to Polymer. In fact, it has no dependencies at all, but should work just fine with Polymer or any other custom elements library. If you prefer to use a simple custom elements polyfill, ajax-form is also your best choice.
What's wrong with a traditional
- Form submission changes/reloads the page, and it's not trivial to properly prevent this.
- You can't send custom headers with a submitted form.
- You can't (easily) parse the server response after a form is submitted.
- Programmatically tracking invalid forms/fields is frustrating.
- You can't send form data as JSON.
- You have no opportunity to programmatically augment user-entered data before it is sent to the server.
- Custom form elements (such as those created using the web components spec) cannot be submitted using a traditional unadulterated
ajax-form custom element augments a traditional
<form> to provide additional features and solve the problems listed above. See the API documentation page for complete documentation and demos.
npm install ajax-form
Use ajax-form just like you would use a traditional form, with the exception of the required
is="ajax-form" attribute that you must include in your
<form> element markup. Since ajax-form is a web component, you may need to include a web component polyfill, such as webcomponents.js to ensure browsers
that do not implement the WC spec are able to make use of ajax-form. Ajax-form has no hard
A very simple use of
ajax-form looks just like a normal
<form>, with the addition of an
Enter your name:...
See the API documentation page for complete documentation and demos.
Are you developing a form field web component? Read the instructions below to ensure your field integrates properly with ajax-form.
Your component will integrate nicely into ajax form provided your custom element
value property that contains the current value of the field. If this
is not true, then your custom field must ensure a native HTML form field is part of
the light DOM. In either case, the element with the
value property must also
name attribute. Your user/integrator will need to include an
appropriate value for this field.
If your custom field exposes a native HTML form field in the light DOM, then there is nothing more to do - ajax-form will respect any validation that your user/integrator adds to the field. The constrain attribute(s) MUST be placed on the native HTML form field.
If your custom field does NOT expose a native HTML form field in the light DOM by default, and you want ajax-form to respect validation constraints, then you will need to include a little code to account for this. Here are the steps to follow:
- Add an opaque, 0x0
<input type="text">field to the light DOM, just before your field.
- Add a
customElementRefproperty to the input, with a value equal to your field.
- Ensure the validity of the input always matches the validity of your field. You can
do this via the
setCustomValiditymethod present on an
setValidationTarget method in the
<file-input> custom element source code
for an example.
npm install npm install -g grunt-cli grunt
gruntwithout any parameters will test against a few locally installed browsers (see the codebase for details).
grunt shell:wctSaucewill run tests against a number of browsers in SauceLabs. Ensure you have your SauceLabs username and key attached to the proper environment variables first.