Embedding

Embedding Formbox Builder and Renderer

You can embed the Builder and Renderer into your application or website using web components. The Renderer can also be embedded directly as an iframe using SDC SMART Web Messaging (SWM).

Renderer in an iframe (SDC SWM)

The Formbox renderer also supports SDC SMART Web Messaging. You can embed it directly in an iframe and communicate via postMessage, without the web component wrapper.

• 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

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

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

Step 2: Add the Component Tag

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

<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.

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

Below are examples of how to set properties programmatically:

onFetch: Intercept Network Requests

<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>

<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

<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>

<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>

onPreviewAttachment: show attachments with external editor

Allows to preview attachments in an external editor or viewer.

Return false to use default Formbox attachment preview, or true to prevent default behavior and show your previewer.

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

<script>
  const renderer = document.getElementById('aidbox-form-renderer');
  
  renderer.onPreviewAttachment = (attachment) => {
    // attachment is an FHIR attachment object
    // e.g., open attachment in external editor
    if(attachment.contentType === "application/dicom") {
      window.open(attachment.data, '_blank'); // if it's a data URL
      window.open(attachment.url, '_blank'); // if it's stored in S3
      return true;
    }
  
    return false;
    
  };
</script>

onChange: React to Form Updates

<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>

<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

<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>

contentHeight: Adjust Component Height

To ensure the component fits well within your layout, you can get the current content height of the component and adjust its height accordingly. This is particularly useful when embedding the component in a responsive design.

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

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

  console.log("Current content height:", renderer.contentHeight);
</script>

Additionally, you can set the height of the component dynamically based on the content height by settings the style attribute to auto:

<aidbox-form-renderer id="aidbox-form-renderer" style="height: auto" /> 

Step 4: Optional Custom Loading Content

Both web components support a loading slot. You can place any HTML in this slot, from a simple text message to a complex, fully styled loader (for example: spinners, SVG animations, skeleton screens, or branded layouts). The element you place in slot="loading" is fully styleable with your own CSS. The component style attribute is applied to both iframe and loader container.

<aidbox-form-builder
  id="aidbox-form-builder"
  style="width: 100%; height: 640px; border: none; display: flex"
  form-id="{{ FORM_ID }}"
>
  <div slot="loading">Loading builder...</div>
</aidbox-form-builder>

<aidbox-form-renderer
  id="aidbox-form-renderer"
  style="width: 100%; height: 640px; border: none; display: flex"
  questionnaire-id="{{ ID }}"
>
  <div slot="loading">Loading form...</div>
</aidbox-form-renderer>

If needed, you can also observe loading state with events:

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

  builder.addEventListener('loading', (event) => {
    console.log('Loading state:', event.detail.loading); // true | false
  });

  builder.addEventListener('ready', () => {
    console.log('Builder is ready');
  });
</script>

Step 5: Optional Custom Submit Button

If you use your own submit button outside the renderer component, call submit() on the web component instance. The method uses the same validation and disabled-state rules as the built-in footer submit action. It returns a Promise with the submission result.

<button id="custom-submit">Submit</button>
<aidbox-form-renderer
  id="aidbox-form-renderer"
  questionnaire-id="{{ ID }}"
  hide-footer
/>

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

  customSubmit.addEventListener('click', async () => {
    try {
      const result = await renderer.submit();
      console.log('Form submitted:', result);
    } catch (error) {
      console.error('Submission failed:', error.payload || error);
    }
  });
</script>

For message-based integrations, sdc.aidbox.submit is also supported as an inbound message type.

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.

Step 6: Enable Controlled Mode

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

<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:

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:

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

<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>

<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>