Embedding Forms
Every form can be filled in on its landing page, https://<your Full Fabric domain>/f/<form id>. To collect submissions on your own website instead, use the form's Integration tab: embed the form with the Full Fabric forms library, or post submissions to the form's endpoint from your own code.
Note: An embedded form or an endpoint is the live form: what is sent through it is stored, creates or updates profiles, and starts the form's workflows.
External Integration
The External integration section decides whether the form can be used from another website.
| Setting | Description |
|---|---|
| Enable external integration | Off (the default), Endpoint, or Embed code. |
| Allowed external domain | The website the form is used from, for example https://example.com. Shown when the integration is not off. |
Save with Save changes. The instructions for the saved option appear below.
What the Checks Do
| Request | Checked |
|---|---|
| From Full Fabric itself (the landing page) | Nothing extra. |
| From anywhere else, integration Off | Refused: "This entity does not allow requests from external domains." |
| From anywhere else, integration on | The request must carry the form's token, or it is refused: "A valid token is required". |
| From a browser on another website | The browser only lets the page read Full Fabric's answers when it runs on the Allowed external domain. |
Set the allowed domain whenever the form runs in a visitor's browser on your site, as the embed code does. A server posting to the endpoint does not need it.
Deprecated Options
Two older options, Embed iframe and Embed code, first version, are no longer offered. A form still set to one shows it as "(deprecated)" with a warning, and keeps working until you pick another option. Once you leave it, you cannot select it again.
Embed Code
With Embed code saved, the tab shows three snippets to paste into your page:
- In the page's head: loads the forms library and its styles from
https://assets.fbri.cloud/embeddable-forms/<version>/. - Where the form goes: an empty element with an ID of your choice, unique on the page.
- After that element: a script that calls
FF.renderFormwith your institution's handle, the form's ID, and the element. The end of the page's body is a good place.
<div id="id-of-your-choice"></div>
<script>
FF.renderForm(
"your-institution-handle",
"your-form-id",
document.getElementById("id-of-your-choice")
)
</script>
Each page load counts as a view of the form. For several forms on one page, give each its own element and its own FF.renderForm call.
Additional Options
A fourth argument to FF.renderForm takes an object with these options:
| Option | Description |
|---|---|
onBeforeFormStarts |
A function called before the form starts rendering. |
onFormSubmitted |
A function called once the form has been submitted, for example to open a thank-you page. |
preFillData |
An object with the data to prefill the form with, keyed by field name, such as { first_name: 'John' }. |
locale |
The language to show the form in: one of the institution's languages, such as en-GB. |
Endpoint
With Endpoint saved, the tab shows what your own code needs to post submissions:
| Item | Value |
|---|---|
| Public form | The landing page address. |
| Endpoint | https://<your Full Fabric domain>/api/forms/<form id>/submissions. Send an HTTP POST, as JSON or form data. |
| Token | Send it with every request, in the body or the query string, as external_domain_token. |
A table lists the fields the endpoint stores, in the form's order, with each one's parameter name and whether it is Required, Conditionally required, or Not required. Answers go under data, keyed by field name, such as data[first_name]. A file upload field takes a list, data[<name>][]. When the institution has a privacy policy, its acceptance goes in data[policies][<policy id>][accepted].
{
"external_domain_token": "<token>",
"data": {
"first_name": "Joe",
"last_name": "Mayo",
"email": "joe@party.com",
"policies": { "<policy id>": { "accepted": "true" } }
}
}
Responses
| Status | Meaning |
|---|---|
| 200 OK | The submission was stored. The body's message is the form's success message. |
| 406 Not Acceptable | Nothing was stored. Invalid data lists the errors per field (under forms/submission), a policy not accepted lists the errors per policy (under policies), and a form outside its submission window answers "Form submissions are closed". |
| 422 | A field name that the form does not have was sent. |
| 401 Unauthorized | The form does not take requests from other websites, the token is missing or wrong, or the captcha check failed. The message says which. |
Warning: With Enable captcha for spam protection on, every submission must carry a solved captcha. A server posting to the endpoint cannot solve one, so its submissions are refused. Keep the captcha off for forms used through the endpoint. See Spam Protection.
Related
- Submissions for what happens once a submission is accepted
- Form Builder for field names and required rules