Interact with Form Renderer

We know that each application has its own use case and with that many options it is impossible to satisfy all the needs without providing rich configuration options, event listeners and inputs.

Call Methods

The following code illustrates calling validateForm and getScriptApi methods in custom functions.

function onValidateForm() {
  let validationModel = fr.validate(true);
  console.log(validationModel);
}

function onSetFieldValue() {
  let scriptApi = fr.getScriptApi();
  scriptApi.setFieldValue('path/to/form/element', 'value');
}

Handle Events

The following code illustrates handling events and logging the received data to the console.

fr.addEventListener('onValueChange', function(event) {
  console.error('onValueChange', event.detail);
});

fr.addEventListener('onValidationChange', function(event) {
  console.error('onValidationChange', event.detail);
});

fr.addEventListener('onFormRendered', function(event) {
  console.error('onFormRendered', event.detail);
});

fr.addEventListener('eventDispatched', function(event) {
  console.error('eventDispatched', event.detail);
});

When the onValueChange event happens the composition is also updated, so we recommend taking advantage of that. The following code illustrates handling onValueChange event and logging the updated composition to the console. Note that onValueChange happens also when the form is rendered.

fr.addEventListener('onValueChange', function(event) {
  console.error('composition', fr.composition);
});

Viewing the current composition

To get the current composition, you can access it like this:

// ...
let fr = document.getElementById("fr");
console.log(fr.composition);
// ...

Saving the Composition

Saving the composition can be accomplished in one of two ways:

1. Using the save/save incomplete dependency
2. Using the saveComposition api call method

Saving the composition also saves all the Generic Canvas images to the multimedia server, before finally saving the composition which can take some time if the images are large. We strongly recommend that you implement a spinner or some other means of notifying the user that the saving is in progress.

Both ways also require an ehrId which can be passed to the renderer through the formEnvironment property.

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

fr.formEnvironment = environment;

saveComposition Method

The saveComposition(validate) method can be accessed via the getScriptApi. The method returns a promise of a SaveCompositionResponse object.

The method takes an optional boolean argument validate if you wish to validate the form before saving the composition. The argument defaults to true if not provided.

const api = fr.getScriptApi();

async function save() {
  const response = await api.saveComposition();
  if (!response.success) {
    throw response.error;
  }
  console.log('Composition id(s): ');
  if(response.commitData) {
    response.commitData.forEach((commit => {
      console.log(commit.id);
    }));
  } else {
    console.log(response.uid);
  }
}

// will save the composition even if the form is invalid
fr.getScriptApi().saveComposition(false);

// will return an error in case the form is invalid
fr.getScriptApi().saveComposition(true);

Saving the composition with a dependency on the form

Saving the composition by using the save/save incomplete dependency emits an onCompositionSaved event which outputs the SaveCompositionResponse in the detail parameter of the response.

fr.addEventListener('onCompositionSaved', (response) => {
  // implement response handler
});

Updating the Composition

Updating the composition will require an ehrId which can be passed to the renderer through the formEnvironment property and a compositionId which you want to update, which can be passed as compositionId.

const environment = {
  variables: [
    {
      name: 'ehrId',
      value: '000-92ac-4bf6-bfed-f0d4b9f6'
    }
  ]
};
const compositionId = 'f8805e7e-0000-1111-222c-74ca6b0a53e9::test::1';

fr.formEnvironment = environment;
fr.compositionId = compositionId;

The updateComposition(validate) method can be accessed via the getScriptApi. The method returns a promise of a SaveCompositionResponse object.

The method takes an optional boolean argument validate if you wish to validate the form before saving the composition. The argument defaults to true if not provided.

const api = fr.getScriptApi();

async function save() {
  const response = await api.updateComposition();

  if (!response.success) {
    throw response.error;
  }
  console.log('Composition id(s): ');
  if(response.commitData) {
    response.commitData.forEach((commit => {
      console.log(commit.id);
    }));
  } else {
    console.log(response.uid);
  }
}

// will update the composition even if the form is invalid
fr.getScriptApi().updateComposition(false);

// will return an error in case the form is invalid
fr.getScriptApi().updateComposition(true);

SaveCompositionResponse Object

The SaveCompositionResponse can have a successful or unsuccessful response:

// success
response = {
  success: true,
  uid: '000-92ac-4bf6-bfed-f0d4b9f6'
};

// error
response = {
  success: false,
  error: FormRendererError
};

Where FormRendererError is an object comprised of

elementId: string;
message:string;
code? : string;
status? : string;

onPageChanged event

onPageChanged($event) is an event fired when user changes the page. The response is active page information, such as id, name, templateId and information if this is the first page.

fr.addEventListener('onPageChanged', function(event) {
  console.error('onPageChanged', event);
});

And the returned event will be composed of:

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