You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| autogenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true |
122
+
| autoMountForms | Whether the library should automatically mount forms collected or not | Boolean | true |
Copy file name to clipboardexpand all lines: docs/forms.md
+33-30
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,18 @@
1
1
## Forms
2
2
3
-
Create dynamic forms based on built-in subscriber attributes such as name, email, phone or other custom properties unique to your business.
4
-
Then let Hellotext handle building the form, collecting, validating and authenticating the data users submit.
3
+
Create dynamic forms based on built-in subscriber attributes such as name, email, phone or other custom properties unique to your business.
4
+
Then let Hellotext handle building the form, collecting, validating and authenticating the data users submit.
5
5
6
6
For more information on how to create a form from the dashboard, view this [guide](https://help.hellotext.com/forms).
7
7
8
8
### Collection Phase
9
9
10
-
After initializing the `Hellotext` class, it attaches a `load` event listener and once the page is loaded,
11
-
it looks for any HTML element that is on the page that has a `data-hello-form` attribute.
10
+
Hellotext uses the `MutationObserver` API to listen for changes in the DOM, specifically new form elements being added that have the `data-hello-form` attribute.
12
11
13
-
You can access the forms object to also trigger the form collection phase manually.
14
-
This is useful if you have a Single Page Application(SPA) and cannot hardcode the `data-hello-form` element on the rendered page.
12
+
You can access the forms object to also trigger the form collection phase manually.
13
+
This is useful if you have a Single Page Application(SPA) and cannot hardcode the `data-hello-form` element on the rendered page.
15
14
16
-
To manually collect forms, do the following.
15
+
To manually collect forms, do the following.
17
16
18
17
```javascript
19
18
Hellotext.initialize('HELLOTEXT_BUSINESS_ID')
@@ -22,18 +21,18 @@ Hellotext.forms.collect()
22
21
23
22
Once loaded, you can access the `FormCollection` object by calling `Hellotext.forms`.
24
23
25
-
Make sure you have initialized with `Hellotext.initialize` otherwise an error is reported.
24
+
Make sure you have initialized with `Hellotext.initialize` otherwise an error is reported.
26
25
27
26
Form collection finishes once Hellotext has fetched the data for the form elements present on the page from the Hellotext API.
28
-
Afterwards, it dispatches a `forms:collected` event that you can subscribe to.
27
+
Afterwards, it dispatches a `forms:collected` event that you can subscribe to.
29
28
30
29
```javascript
31
-
Hellotext.on('forms:collected', (forms)=> {
30
+
Hellotext.on('forms:collected', forms=> {
32
31
console.log(forms) // Instance of FormCollection
33
32
})
34
33
```
35
34
36
-
The `FormCollection` class is a wrapper around the forms, which providers other useful methods.
35
+
The `FormCollection` class is a wrapper around the forms, which providers other useful methods.
37
36
38
37
-`getById(id: string): Form` - Get a form by it's id
39
38
-`getByIndex(index: number): Form` - Get a form by it's index
@@ -44,38 +43,44 @@ The `FormCollection` class is a wrapper around the forms, which providers other
44
43
45
44
### Mounting forms
46
45
47
-
After the collection phase, form elements would be available to be mounted. Hellotext does not automatically mount form elements,
48
-
you have total control on when and where to mount the form elements. To mount a form object, you call the `mount` method on the form object.
46
+
Hellotext.js by default automatically mounts forms collected to the DOM. You can disable this behaviour by passing the `autoMountForms` option as `false` when initializing the library.
If form mounting is disabled, Hellotext does not automatically mount form elements,
53
+
you will have total control on when and where to mount the form elements. To mount a form object, you call the `mount` method on the form object.
54
+
55
+
```javascript
56
+
Hellotext.on('forms:collected', forms=> {
52
57
forms.getByIndex(0).mount()
53
58
})
54
59
```
55
60
56
-
Mounting a form creates the form and it's components that are associated to it, and attaches it to the DOM.
57
-
Hellotext looks for a `form` element with the `data-hello-form` attribute and mounts the form inside it.
61
+
Mounting a form creates the form and it's components that are associated to it, and attaches it to the DOM.
62
+
Hellotext looks for a `form` element with the `data-hello-form` attribute and mounts the form inside it.
58
63
If this condition is not met, Hellotext creates the form manually and appends it to the body of the document.
59
64
We recommend to make the criteria met to ensure the form is loaded into an expected place in your page.
60
65
61
66
### Validation
62
67
63
-
Hellotext automatically validates the form inputs based on how they were configured on the dashboard
64
-
using browser's native [checkValidity()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/checkValidity).
65
-
Once the user tries to submit the form and there are missing required fields,
68
+
Hellotext automatically validates the form inputs based on how they were configured on the dashboard
69
+
using browser's native [checkValidity()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/checkValidity).
70
+
Once the user tries to submit the form and there are missing required fields,
66
71
the submission is halted and we display default browser's error message using [HTMLObjectElement.validationMessage](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage) property.
67
72
68
73
### Authentication
69
74
70
-
Hellotext protects you from bot submissions and protects your customers from identity theft and impersonation.
75
+
Hellotext protects you from bot submissions and protects your customers from identity theft and impersonation.
71
76
When a subscriber fills the form, Hellotext sends a One Time Password (OTP) code to the subscriber. If they have an email,
72
-
an email is sent to them, otherwise an SMS is sent to their phone number.
77
+
an email is sent to them, otherwise an SMS is sent to their phone number.
73
78
Until a valid OTP has been entered, data will not show up on the dashboard and will not contribute to attribution marketing.
74
79
75
80
### Form Completion
76
81
77
-
Once the user enters the OTP they received. The form is considered to be complete and will be sent to the Hellotext API to create(or update) a profile from the submission information.
78
-
The library also dispatches a `form:completed` event that you can subscribe to. In addition, a Session object is set and stored on the browser's cookies.
82
+
Once the user enters the OTP they received. The form is considered to be complete and will be sent to the Hellotext API to create(or update) a profile from the submission information.
83
+
The library also dispatches a `form:completed` event that you can subscribe to. In addition, a Session object is set and stored on the browser's cookies.
79
84
Additionally, the `Hellotext.session` is also set if no session was present already, you can listen for the session events by subscribing to `session-set` event.
The data in the from will differ based on the inputs you have configured on the dashboard.
97
102
98
103
### Understanding form's layout
99
104
100
-
Hellotext assumes a fixed layout for forms, which are in order of Header, Inputs, Button and Notice.
105
+
Hellotext assumes a fixed layout for forms, which are in order of Header, Inputs, Button and Notice.
101
106
102
107
But you can override this layout if you want. Overriding a form's layout can be achieved
103
108
by moving the placement of the form's components. For example, if you want to display the Button component after the Footer, here's how you can do that
104
109
105
110
```html
106
111
<formdata-hello-form=":id">
107
-
<footerdata-form-notice>
108
-
</footer>
112
+
<footerdata-form-notice></footer>
109
113
110
-
<buttondata-form-button>
111
-
</button>
114
+
<buttondata-form-button></button>
112
115
</form>
113
116
```
114
117
115
-
Hellotext would simply load the contents inside the respective elements without creating the default layout.
118
+
Hellotext would simply load the contents inside the respective elements without creating the default layout.
116
119
If these elements were not defined, Hellotext would render the button then the notice component.
0 commit comments