Aidbox Forms Renderer Integration Guide
This section details the technical implementation of the Aidbox Forms Renderer as a Web Component within our application architecture.
1. Script Loading Strategy
The Aidbox Forms Renderer is integrated as a Web Component. To manage this efficiently, we use a dedicated AidboxRendererService.
- On-Demand Injection: The service ensures the renderer script is injected into the HTML
<head>only when a Renderer Component is actually initialized. - Singleton Pattern: The service tracks the loading state to ensure the script is included exactly once, preventing redundant network requests and potential JS execution conflicts.
2. The Renderer Component (AidboxRendererComponent)
The AidboxRendererComponent handles the lifecycle and data binding for the Web Component.
Dynamic Element Construction
Due to lifecycle timing issues with standard Angular/Framework template bindings, the HTML element for the renderer is constructed dynamically.
Technical Note: Standard template binding was found to be unreliable. For instance, passing the
tokenvia a fixed template variable often resulted in the token being missing during the Web Component'sconstructorexecution, leading to initialization errors. Dynamic construction ensures all attributes are present at the moment the element is attached to the DOM.
Component Inputs
The component supports the following inputs, mirroring the native Aidbox Renderer capabilities:
| Input | Type | Default / Description |
|---|---|---|
questionnaire | Questionnaire | The FHIR Questionnaire object. |
questionnaireResponse | QuestionnaireResponse | null | The FHIR Response object (optional). |
hideFooter | boolean | false |
hideLanguageSelector | boolean | false |
baseUrl | string | environment.aidboxUrl |
style | string | Default: Flex-stretched, borderless container. |
config | SDCConfig | undefined | Structured Data Capture configuration. |
theme | string | undefined | Custom UI theme name. |
disableLoadSdcConfig | boolean | false |
token | string | undefined | Authentication token for Aidbox API calls. |
3. Data Handling & Interception
While the native Aidbox Renderer typically expects Resource IDs, our implementation passes full Objects (Questionnaire, QuestionnaireResponse).
Why we use Objects instead of IDs:
- Intercepting Core Features: We intercept internal methods such as
getQuestionnaire,loadQuestionnaireResponse,save, andsubmit. Passing the full objects allows us to maintain the payloads within the global application context immediately. - Compatibility Pre-checks: By having access to both objects before the renderer starts, we perform a validation check to ensure the
Questionnaireand theQuestionnaireResponseare compatible (checking versions and canonical URLs). - Enhanced Error Handling: This "Pre-check" allows us to display user-friendly UI error states if a mismatch is detected, rather than allowing the renderer to fail silently or display an empty state.
For further details on the specific input parameters, please refer to the Official Aidbox Documentation.