Filling in fields, methods and events

Let the agent fill in fields, control the guide from your own code, and listen for its events.

Letting the agent fill in fields#

Add data-formguide="extract" to a field (or a button group). Its panel then works like this:

The agent explains the question, as usual.
The visitor describes their answer in their own words.
Once the agent has replied, the Done button becomes active.
The visitor presses Done. The agent works out the value and writes it into the field. The panel says Response saved to form.

html

<label for="occupation">Your job</label>
<input id="occupation" name="occupation" data-formguide="extract">

How the value is written depends on the field:

Field	How it's filled in
text, email, phone, web address, search, textarea	The text as the agent gave it.
`<select>`	The option whose value, or visible text, matches (capital letters don't matter).
radio group	Ticks the radio button whose value or label matches.
checkbox	Ticked for yes, true, y, 1, checked or on. Cleared for no, false, n, 0, unchecked or off.
date	Written as `yyyy-mm-dd`. The agent can give a date in that form, as `dd/mm/yyyy`, or written out ("3rd of May 1988").
number, slider	The first number in the answer.
button group	Clicks the matching button: exact text first, then ignoring capitals, then text that contains the answer. An answer naming several choices ("Mortgage and Family") clicks each one, but only if every part matches.

When a value is written, the field also gets normal input and change events, so React, Vue and other frameworks see the change as if the visitor had typed it.

If the answer doesn't fit the field (no matching option, a date it can't read, no number), nothing is written. The panel shows We couldn't fill this in automatically: the suggested answer was: ... so the visitor can fill it in themselves.

JavaScript methods#

The script creates window.SubcontextFormGuide.

For the paste-in snippet#

Method or value	What it does
`version`	The script's version, e.g. `"1.2.0"`.
`attach(options)`	Installs the guide on one element. See Option 2.
`enable()`	Starts a guide that began switched off (`data-enabled="false"`), or brings it back after `disable()`. Returns a promise.
`disable()`	Removes the icons and panels and stops looking for new fields. Keeps its settings, so `enable()` brings it all back.
`rescan()`	Looks for new fields now. (New fields are normally picked up automatically.)
`trigger(element)`	Opens the help panel for a field, as if its icon were clicked. Pass the field (or a button group). Calling it again closes the panel. Works even for a field without an icon, such as a skipped one, as long as the guide can find its label and has started.
`hide(element)`	Closes the panel for that field. With no argument, closes every open panel on the page.
`destroy()`	Removes everything and forgets its settings.
`init()`	Starts the guide from the snippet. This happens by itself when the page loads, so you rarely need it. Calling it again after it has started looks for new fields. It takes no options.

enable, disable, rescan, trigger, destroy and init only affect the paste-in snippet install, not guides you added with attach(). hide() with no argument closes every panel, including ones from attach().

Your own "Explain this" button:

html

<button type="button" onclick="SubcontextFormGuide.trigger(document.getElementById('income'))">
  Explain this
</button>

For `attach()`#

attach() gives you a guide object with these methods. They only affect that one container.

Method	What it does
`rescan()`	Looks for new fields in the container now.
`disable()`	Removes this container's icons, closes open panels and stops looking for new fields.
`enable()`	Shows the icons and starts looking for fields again. Also starts a guide attached with `enabled: false`.
`destroy()`	Removes this container's icons and panels for good. After this, `enable()` and `rescan()` do nothing. Call `attach()` again to start afresh.
`setApplicationContext(ctx)`	Changes `applicationContext` (or clears it with `null`). Panels opened after this use the new value.

Events#

The form guide doesn't call your code directly. It sends events from the field (or button group). They bubble up, so you can listen on the field, the form or the whole document.

Event	When it happens	`event.detail`
`formguide:done`	The visitor pressed Done. The value is on its way but not written yet.	`{ field, fieldKey, fieldName, label }`
`formguide:generated`	The agent's value has been written into the field. Not sent if the value didn't fit the field.	`{ field, fieldKey, fieldName, label, content }`

What's in event.detail:

Key	What it is
`field`	The field element (or the button group element).
`label`	The question text.
`content`	The value as the agent gave it.
`fieldName`	The field's `name`, or a button group's `data-formguide-field` key. Use this to match the event to your own data.
`fieldKey`	The guide's own id for the field, made from the form and field names.

document.addEventListener('formguide:done', function (event) {
  console.log('Working out an answer for', event.detail.label)
})
document.addEventListener('formguide:generated', function (event) {
  console.log(event.detail.fieldName, 'is now', event.detail.content)
})

Stuck, or something missing?

Get in touch and a person on the team will help.

Letting the agent fill in fields#

JavaScript methods#

For the paste-in snippet#

For attach()#

Events#

For `attach()`#