Configuration

info

This content is intended for advanced Studio users.

This section covers the three main configuration mechanisms for Form renderer: the EhrFormContext object, the events Form renderer emits, and external variables passed from your application into forms at runtime.

Form renderer context

EhrFormContext is a configuration object that controls Form renderer behaviour. Pass it to the renderer to set language, theme, date formats, validation options, presentation mode, auto-prefill, and more.

For instructions on how to pass the context object to the renderer in your framework, see the relevant framework guides.

Configuration attributes

Key	Type	Required	Default	Description
language	string	No	—	Language for Form renderer. If not provided, the default language from the form description is used.
territory	string	No	SI	Territory code, typically in ISO 3166 format.
readonly	boolean	No	—	Renders the form and all fields in read-only mode.
dateFormat	string	No	dd/MM/yyyy	Date format for DV_DATE and DV_DATE_TIME fields. Accepts date-fns format tokens.
validationDisabled	boolean	No	false	Completely disables validation on the renderer.
timePlaceholder	MrdTimePlaceholderFormat	No	—	Placeholders for hours and minutes on DV_TIME and DV_DATE_TIME fields.
datePlaceholder	string	No	—	Date placeholder. Priority: (1) field annotation, (2) this value, (3) date format string. Applies to DV_DATE and DV_DATE_TIME.
showNumericRangePlaceholder	boolean	No	false	Shows a placeholder with the allowed range for numeric fields (DV_COUNT, DV_PROPORTION, DV_QUANTITY) when no other placeholder is set.
displayValidationMessagesOnTouched	boolean	No	false	Shows validation errors when a field is touched and then blurred, rather than only on submit.
terminologyUrl	string	No	—	Overrides or provides a terminology URL for fields using terminology.
dropdownPresentationMinItems	number	No	—	When set, presentation dropdowns with fewer items than this threshold switch from dropdown to checkboxes or radio buttons.
displayDateInputMask	boolean	No	false	Shows the date format mask inline in the date input field.
disableFormScript	boolean	No	false	Disables all form scripts and dependencies. Primarily useful for Form builder.
textareaAutosize	boolean	No	false	Enables automatic height adjustment on text area fields.
disableScriptRunOnInitialization	boolean	No	false	Prevents scripts from running when the form is first rendered.
presentationMode	boolean	No	false	Renders the form in compact, read-only presentation mode.
showAllPages	boolean	No	false	Shows all pages at once. Applies to presentation mode.
theme	string	No	DEFAULT	Predefined theme. Options: DEFAULT, WHITE (white background).
showFieldsRequiredIndicator	boolean	No	false	Displays required field indicators on the form.
autoPrefill	object	No	{ enabled: false, mode: 'LATEST_COMPOSITION' }	Configures automatic prefill from previously saved data. See Auto-prefill.
cspSettings	{ enabled: boolean, nonce?: string }	No	—	Content Security Policy configuration. See CSP configuration.
uploadUrl	string	No	—	URL used for uploading files through multimedia form inputs.
disableDefaultAttachmentDownload	boolean	No	false	Disables the default download behaviour for attachments. When true, handle the ATTACHMENT_DOWNLOAD_INITIATED event to implement custom download logic.
attachmentUrlFormat	'absolute' | 'relative'	No	'absolute'	When set to 'relative', attachment URLs are resolved relative to the application base URL. Applies to attachments stored on Better Store or following the same URL pattern.
decimalSeparator	'.' | ','	No	'.'	Character used as the decimal separator in number display. The stored model value always uses a decimal dot regardless of this setting.
openEhr	'better' | 'openEHR'	No	'better'	Defines the EHR API type used when saving compositions and contributions.
formStyle	'BDS' | 'CLINICAL_LEGACY'	No	'BDS'	Sets the preferred form style. Versions 3.15 and later use BDS by default; override with CLINICAL_LEGACY if required.
mode	'online' | 'offline'	No	'online'	Sets the Form renderer operating mode. In 'offline' mode, all resource requests are delegated to the host application via a request handler function rather than making direct calls to the EHR server. See Offline mode.
offline	object	No	—	Offline mode configuration. Required when mode is 'offline'. Accepts two properties: requestHandler (async function, required) — the function Form renderer calls for every resource request; and timeoutMs (number, optional, defaults to 5,000) — the maximum time in milliseconds the renderer waits for a handler response before treating the request as failed. See Offline mode for the full request handler contract.

Auto-prefill

Auto-prefill loads a previously saved composition into the form on render. Enable it by setting autoPrefill.enabled to true and choosing a mode:

• LATEST_COMPOSITION — loads the latest saved composition for the given template.
• LATEST_COMPLETED_COMPOSITION — loads the latest composition with a completed lifecycle state.
• CUSTOM_AQL_VIEW — loads a composition identified by a custom AQL view you define.

info

If a custom AQL view is provided, it takes priority over the mode setting.

Custom AQL view

You can provide a custom AQL view in two ways.

Option 1 — webTemplate AQL view. A Freemarker AQL view in WEB_TEMPLATE_FLAT or STRUCTURED format. The composition is loaded directly from the view result.

Metadata:

{
  "properties": {
    "meta": "false",
    "format": "STRUCTURED"
  },
  "parameters": [
    { "name": "ehrId", "description": "", "type": "string" },
    { "name": "templateId", "description": "", "type": "string" }
  ]
}

Query:

SELECT c FROM EHR e[ehr_id/value=:ehrId]
CONTAINS VERSION v
CONTAINS COMPOSITION c
WHERE c/archetype_details/template_id/value = :templateId
AND v/lifecycle_state matches {'complete', 'incomplete'}
ORDER BY v/commit_audit/time_committed DESC
FETCH 1

Option 2 — custom AQL view returning a UID. Any AQL view type that returns a single uid value. Form renderer uses this UID to fetch the composition.

Query:

SELECT c/uid/value as uid
FROM EHR e[ehr_id/value=:ehrId]
CONTAINS VERSION v
CONTAINS COMPOSITION c
WHERE c/archetype_details/template_id/value = :templateId
AND v/lifecycle_state matches {'complete', 'incomplete'}
ORDER BY v/commit_audit/time_committed DESC
FETCH 1

Expected result:

[
  { "uid": "ac3981b6-64eb-4cfc-bd91-2b33fde0897b::studio-user::1" }
]

Handling events

Form renderer emits events you can listen for to respond to user interactions, form lifecycle changes, and errors. For framework-specific binding syntax, see the relevant Framework guide.

Available events

onValueChange

Fired when any field value in the form changes, including on initial render. Use it to respond to user input or to access the updated composition after each change.

onFormRendered

Fired when the form has been successfully rendered and is ready for interaction. This is the earliest point at which it is safe to call Script API methods on the form.

onCompositionSaved

Fired when a composition is saved via a save or save incomplete dependency on the form. The event detail includes a SaveCompositionResponse object.

onRequestUpdatedToken

Fired when the current OAuth 2.0 token has expired and the renderer needs a replacement to complete a pending request — for example, saving a composition or uploading a file. Implement a token refresh handler in response to this event.

The renderer expects a valid updated token within 5000ms. If no valid token is received, the renderer throws an error.

onPageChanged

Fired when the user navigates between pages in a multi-page form. The event detail includes page information:

id: string;
name: string;
firstPage?: boolean;
hideInPresentationMode?: boolean;
valid?: boolean;

onFormError

Fired when an error occurs while retrieving the form or handling form data. The event detail includes two properties:

• description — a human-readable error description.
• errorType — one of the following values:

Value	Description
PLATFORM_ERROR	An error raised by the platform, such as a 404 or a form error code.
SESSION_TIMEOUT	The OAuth session expired.
UNAUTHORIZED	Basic auth credentials were rejected.
UNKNOWN	An unclassified error occurred.

info

onFormError is not raised when the form contains invalid data. Use form validation methods via the Script API for that.

eventDispatched

A general-purpose event that fires when any custom event is dispatched from within the form. Use it to capture and respond to form-level events beyond the named events above.

External variables

External variables are part of the form environment. They allow your application to pass values into Form renderer at runtime — for example, the current patient's ehrId, a unit system preference, or any other application-level state a form needs to read.

good to know

Form renderer only uses a variable value if the variable is referenced on the form. Values passed for undefined or unused variables are silently ignored.

Setting initial values

Pass a formEnvironment object to Form renderer before or at render time. The object contains a variables array, where each entry specifies a variable name and value.

Framework-agnostic:

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

const fr = document.getElementById('fr');

fr.formEnvironment = {
  variables: [
    { name: 'ehrId', value: '000-92ac-4bf6-bfed-f0d4b9f6' },
    { name: 'unit-system', value: 'metric' }
  ]
};

Angular:

<form-renderer [formEnvironment]="environment"></form-renderer>

environment = {
  variables: [
    { name: 'ehrId', value: '000-92ac-4bf6-bfed-f0d4b9f6' },
    { name: 'unit-system', value: 'metric' }
  ]
};

Updating variable values at runtime

Replacing the entire formEnvironment object each time a single variable changes is cumbersome. Use ScriptApi.setVariableValue() instead to update individual variables after the form has rendered.

Framework-agnostic:

function updateVariable() {
  const scriptApi = fr.getScriptApi();
  scriptApi.setVariableValue('unit-system', 'imperial');
}

Angular:

export class MyComponent {
  @ViewChild('fr') private formRenderer: ElementRef;

  updateVariable() {
    const scriptApi = this.formRenderer.nativeElement.getScriptApi();
    scriptApi.setVariableValue('unit-system', 'imperial');
  }
}

Frequently asked questions (FAQs)

What is EhrFormContext?

EhrFormContext is a configuration object you pass to Form renderer that controls its behaviour — language, theme, date formats, validation, presentation mode, auto-prefill, CSP settings, and more.

How do I pass the context to Form renderer?

In framework-agnostic applications, set fr.context = context on the element reference. In Angular, pass it as [context]="context". In React, set it in componentDidMount. In Vue, set it in the mounted hook. See the framework guides for full examples.

What is auto-prefill?

Auto-prefill automatically loads a previously saved composition into the form on render. Configure it to load the latest composition, the latest completed composition, or a composition returned by a custom AQL view.

What does presentationMode do?

Setting presentationMode to true renders the form in a compact, read-only view. Use showAllPages: true alongside it to display all pages at once rather than one at a time.

Which event should I use to start interacting with the form programmatically?

Use onFormRendered. It marks the point at which Form renderer has finished rendering and it is safe to call Script API methods on the form.

How do I respond to a form save triggered by a dependency?

Listen for onCompositionSaved. It fires after a save or save incomplete dependency executes and provides a SaveCompositionResponse in its detail parameter.

What triggers onRequestUpdatedToken?

This event fires when the current authentication token has expired and the renderer needs a new one to complete a pending request, such as saving a composition or uploading a file. Respond by calling updateToken(token) on the renderer element within 5000ms.

What are external variables?

External variables are variables defined on a form in Form builder that are intended to receive values from the embedding application at runtime, rather than being computed internally by the form.

How do I pass external variables to the renderer?

Pass a formEnvironment object containing a variables array to the renderer. Each entry in the array is an object with a name and a value.

How do I update a variable value after the form has rendered?

Use ScriptApi.setVariableValue(variableName, value). This is more efficient than replacing the entire formEnvironment object when only one variable needs to change.

Does Form renderer use a variable if the form does not reference it?

No. Form renderer only uses a variable value if the variable is referenced on the form. Values passed for unused variables are ignored.