Embedding

Embedding the Aidbox Form Builder and Renderer into your application using web components.

Embedding Aidbox Form Builder and Renderer

You can embed the Builder and Renderer into your application or website using web components.

• Builder allows users to create and manage forms directly within your application.

• Renderer enables users to fill out forms within your application without leaving your platform.

Step 1: Include the Script

Builder

<script src="{{ YOUR_AIDBOX_INSTANCE_BASE_URL }}/static/aidbox-forms-builder-webcomponent.js"></script>

Renderer

<script src="{{ YOUR_AIDBOX_INSTANCE_BASE_URL }}/static/aidbox-forms-renderer-webcomponent.js"></script>

Step 2: Add the Component Tag

Builder

<aidbox-form-builder
  style="width: 100%; border: none; align-self: stretch; display: flex"
  form-id="{{ FORM_ID }}"
  hide-back
/>

Renderer

<aidbox-form-renderer
  style="width: 100%; border: none; align-self: stretch; display: flex"
  questionnaire-id="{{ ID }}"
/>

Step 3: Configure Attributes and Properties

The following attributes are available for the Builder and Renderer components. These attributes control various aspects of the form’s behavior and appearance, including the form’s layout, customization options, and integration with external systems.

Builder

• form-id (optional): The ID of the form to load. If not provided, the builder opens with a blank form.

• hide-back, hide-save, hide-publish (optional): Hides respective buttons in the UI.

• disable-save, disable-publish (optional): Disables respective actions.

• hide-population, hide-extraction (optional): Hides respective functionalities.

• collapse-debugger (optional): Collapses the debugging panel.

• hide-add-theme, hide-edit-theme, hide-save-theme (optional): Controls theme-related UI elements.

• show-share (optional): Shows the share button.

• language (optional): Default language for the builder.

• translation-languages (optional): Comma-separated list of allowed languages.

• base-url (optional): The base URL of your Aidbox instance.

• style (optional): Custom styling for the iframe.

• config (optional): The configuration as a JSON string.

• theme (optional): Theme settings as a JSON string.

• token (optional): JWT token for authentication.

• disable-load-sdc-config (optional): Disables automatic loading of SDC configuration.

Renderer

• questionnaire-id: ID of the questionnaire to load.

• questionnaire-response-id (optional): ID of the questionnaire response to load.

• hide-footer (optional): Hides the form footer.

• hide-language-selector (optional): Hides language selector.

• base-url (optional): The base URL of your Aidbox instance.

• style (optional): Custom styling for the iframe.

• config (optional): The configuration as a JSON string.

• theme (optional): Theme settings as a JSON string.

• token (optional): JWT token for authentication.

• disable-load-sdc-config (optional): Disables automatic loading of SDC configuration.

Along with the above attributes, you can also set the following properties.

Unlike attributes, which can only store string values and are defined in the markup,properties can hold any JavaScript value (such as objects, arrays, functions, etc.) and must be set programmatically using JavaScript.

Builder

• onFetch (optional): A custom fetch handler that allows you to intercept and modify network requests. The function receives the URL and request options as arguments.

• onAlert (optional): A custom alert handler that allows you to intercept and handle alerts, overriding the visual alert display. The function receives the alert object as an argument.

• onChange (optional): A custom callback function invoked when the questionnaire is modified, without affecting the default behavior. The function receives the updated questionnaire as an argument.

• onBack (optional): A custom callback function that is invoked when the back button is clicked, allowing you to override the default back button behavior.

Renderer

• onFetch (optional): A custom fetch handler that allows you to intercept and modify network requests. The function receives the URL and request options as arguments.

• onAlert (optional): A custom alert handler that allows you to intercept and handle alerts, overriding the visual alert display. The function receives the alert object as an argument.

• onChange (optional): A custom callback function that is invoked when the questionnaire response is modified, without affecting the default behavior. The function receives the updated questionnaire response as an argument.

Below are examples of how to set properties programmatically:

onFetch: Intercept Network Requests

Builder

<aidbox-form-builder id="aidbox-form-builder" />

<script>
  const builder = document.getElementById('aidbox-form-builder');

  builder.onFetch = async (url, init) => {
    console.log('Intercepted request', url, init);
    init.headers = {
      ...init.headers,
      Authorization: 'Bearer YOUR_TOKEN'
    };
    return fetch(url, init);
  };
</script>

Renderer

<aidbox-form-renderer id="aidbox-form-renderer" />

<script>
  const renderer = document.getElementById('aidbox-form-renderer');

  renderer.onFetch = async (url, init) => {
    console.log('Intercepted request', url, init);
    return fetch(url, init);
  };
</script>

For more complex use cases, such as attaching authorization headers or storing questionnaires locally, refer to the detailed interception guide.

onAlert: Handle Alerts

Builder

<aidbox-form-builder id="aidbox-form-builder" />

<script>
  const builder = document.getElementById('aidbox-form-builder');

  builder.onAlert = (alert) => {
    console.log('Alert received:', alert);
    // e.g., display toast or log error
  };
</script>

Renderer

<aidbox-form-renderer id="aidbox-form-renderer" />

<script>
  const renderer = document.getElementById('aidbox-form-renderer');

  renderer.onAlert = (alert) => {
    console.log('Alert received:', alert);
    // e.g., display toast or log error
  };
</script>

onChange: React to Form Updates

Builder

<aidbox-form-builder id="aidbox-form-builder" />

<script>
  const builder = document.getElementById('aidbox-form-builder');

  builder.onChange = (questionnaire) => {
    console.log('Updated questionnaire:', questionnaire);
    // e.g., log or analyze the questionnaire
  };
</script>

Renderer

<aidbox-form-renderer id="aidbox-form-renderer" />

<script>
  const renderer = document.getElementById('aidbox-form-renderer');

  renderer.onChange = (response) => {
    console.log('Updated questionnaire response:', response);
    // e.g., log or analyze the response
  };
</script>

onBack: Customize Navigation

Builder

<aidbox-form-builder id="aidbox-form-builder" />

<script>
  const builder = document.getElementById('aidbox-form-builder');

  builder.onBack = () => {
    console.log('Back button clicked');
    // Perform custom navigation
  };
</script>

Controlled Mode (Deprecated)

Controlled mode gives full manual control over loading, updating, and persisting a Questionnaire and QuestionnaireResponse at the application level. The system does not automatically save changes, so the developer must handle data flow and storage. Depending on the use case, making requests to the intended endpoints, as normal mode does, may still be necessary.

This approach is useful when custom validation is required, such as enforcing business rules that go beyond standard validation mechanisms. It is also beneficial when integrating with external systems, where the Questionnaire and QuestionnaireResponse are stored outside Aidbox or when working with multiple data sources. Additionally, it allows fine-grained control over how and when data is fetched, updated, or persisted, making it suitable for applications that need to manage state independently.

Controlled mode is deprecated in favor of request interception, as the latter provides full control over the component’s interaction with Aidbox, extending beyond just Questionnaire and QuestionnaireResponse.

Step 4: Enable Controlled Mode

Builder

To enable controlled mode, remove the form-id attribute and specify the Questionnaire resource as a JSON string in the value attribute.

<aidbox-form-builder
  id="aidbox-form-builder"
  value="YOUR QUESTIONNAIRE AS JSON STRING"
/>

Renderer

Enable controlled mode by removing the questionnaire-id attribute and specifying the Questionnaire resource as a JSON string in the questionnaire attribute. Optionally, you can also specify the questionnaire-response if needed.

<aidbox-form-renderer
  questionnaire="YOUR QUESTIONNAIRE AS JSON STRING"
  questionnaire-response="YOUR QUESTIONNAIRE RESPONSE AS JSON STRING"
/>

The following attributes are available for controlled mode:

Builder

• value: The Questionnaire resource as a JSON string.

Renderer

• questionnaire: The Questionnaire resource as a JSON string.

• questionnaire-response (optional): The QuestionnaireResponse resource as a JSON string.

In controlled mode, handling events is essential, as the system no longer manages updates automatically. Developers are responsible for listening to events such as change, save, and submit to track user interactions and manually persist form data.

Below is a list of events you can listen for:

Builder

• change: Triggered when the form is modified.

• back: Emitted when the back button is clicked.

• save: Emitted when the form is saved.

• select: Emitted when an item is selected.

• ready: Emitted when the builder is loaded.

Renderer

• change: Triggered when the questionnaire response is updated.

• submit: Emitted when the Submit button is clicked.

• extracted: Emitted when data extraction occurs.

• ready: Emitted when the renderer is loaded.

Below is an example of how to listen for change event:

Builder

<script>
  const builder = document.getElementById('aidbox-form-builder');

  builder.addEventListener('change', (event) => {
    // event.detail contains update questionnaire as json string 
    console.log('Form changed', event.detail);
    // you might want to update update it and set it back as value
    builder.setAttribute('value', JSON.stringify(event.detail));
  });
</script>

Renderer

<script>
  const renderer = document.getElementById('aidbox-form-renderer');

  renderer.addEventListener('change', (event) => {
    console.log('Questionnaire Response changed', event.detail);
    renderer.setAttribute('questionnaire-response', JSON.stringify(event.detail));
  });
</script>