Forms Extension¶
The forms
extension enables events that track form changes and submits
on the site. This extension provides ways to see what forms it has detected,
parse form elements for their inputs and content, and more.
Note
This plugin only tracks standard web form elements. If you are using non-standard frameworks like Bootstrap that don't follow the standard web form implementation, then you'll have to provide custom tracking.1
Warning
Forms can contain sensitive values, like passwords! We do some rudimentary
checks for inputs like this, and choose not to track those inputs. Generally
speaking, sensitive information should be flagged as type=password
on the
input element.
Installation¶
This extension can be enabled through Orbee's Platform. If you are manually controlling installation and setup, you can also fetch the plugin here:
<script async src="https://scripts.orb.ee/js-sdk/latest/forms.js" />
This standalone installation sets up the extension's class on the window object,
under window.OaFormsExtension
. You can then extend your scope like this:
oa.getScope(YOUR_SCOPE).extend('forms', OaFormsExtension);
Configuration¶
This extension requires no additional configuration at this time.
Methods¶
This extension has a variety of available attributes and functions to call.
forms.forms
¶
This is an object of forms the extension is currently tracking; the key is the generated ID for that form instance, and the value is the form element on the web page.
forms.forms = {
"b92258ec-1b11-4b80-8111-729187e3c9f4": <form element-on-page>,
...
}
forms.domWatcher
¶
This is an object that uses a
MutationObserver
to track changes to your website, and continuously add tracking to new forms. It
is on by default; you can disable it with forms.domWatcher.stop();
.
If stopped, you can also restart it with forms.domWatcher.watch();
.
forms.trackForm(formEl)
¶
This function lets you manually enable tracking of a form on the web page. The DOM watcher automatically calls this method for all forms it detects on your website.
forms.parseForm(formEl)
¶
This function lets you parse a form in the format our extension resolves things like form name, input labels and value, etc. This function returns a proper form class that includes methods like getting all input properties or just their values.
Available methods/properties:
form.element
: returns the element of the form.form.inputs
: returns a map of inputs and their properties (label, element, value, validity).form.name
: returns the name of the form.form.valid
: returns whether we've detected if the form is valid or not. This returnstrue
if validity is unknown.form.getInputValues()
: returns the key/val pairs of the forms' inputs, ignoring all other properties of those inputs.
Advanced¶
If you want to control when data is sent to Orbee, or if you use atypical web practices that cause our form tracking to not be adequate, you can use the following methods to manually send form changes and submits to Orbee:
trackChange(formEl)
¶
This function will track the change of an input in a form. This does parse and send all inputs of the form in the event.
trackSubmit(formEl)
¶
This will track the submit of a form. This does parse and send all inputs of the form in the event.
Events¶
The extension generates the following events:
Form Changed¶
oa.track('form changed', {
_id: "<form instance id>",
_name: "formName",
...inputKeyValues,
});
Form Submitted¶
oa.track('form submitted', {
_id: "<form instance id>",
_name: "formName",
...inputKeyValues,
});
Listening¶
This extension does not listen for any events in the SDK.
Dependencies¶
This extension does not depend on any other extensions.
-
We are currently in the process of providing configuration and adapters to track other form frameworks. Check back here for updates on these developments! ↩