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

To call component methods, you need the element instance. To access it, use the @ViewChild or @ViewChildren decorator (depending on whether you are getting a single or multiple element instances).

The following code illustrates this approach by using template reference variable and calling validateForm and getScriptApi methods in custom functions.

<form-renderer #fr ...></form-renderer>

export class MyComponent {
  @ViewChild('fr', {static: false}) private formRenderer: ElementRef;

  onValidateForm(): void {
    const validationModel: object = this.formRenderer.nativeElement.validate(true);
  }

  onSetFieldValue(): void {
    const scriptApi = this.formRenderer.nativeElement.getScriptApi();
    scriptApi.setFieldValue('path/to/form/element', 'value');
  }
}

Handle Events

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

export class MyComponent {

  valueChange($event): void {
    console.log('onValueChange', $event.detail);
  }

  formRendered($event): void {
    console.log('onFormRendered', $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.

export class MyComponent {
  valueChange($event): void {
    console.error('composition', this.formRenderer.nativeElement.composition);
  }
}

<form-renderer #fr 
               (onValueChange)="valueChange($event)" 
               (onFormRendered)="formRendered($event)">
</form-renderer>

Viewing the current composition

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

@ViewChild('fr', {static: false}) private formRenderer: ElementRef;
// ...
console.log(this.formRenderer.nativeElement.composition);

Saving the Composition

There are two ways the form renderer can save the composition.

Using the save or save incomplete via dependency
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.

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

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

saveComposition Method

the saveComposition(validate?: boolean) method can be accessed via the renderer api member. The method returns a promise of a SaveCompositionResponse object.

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

<form-renderer #fr [formEnvironment]="environment"></form-renderer>
<button (click)="customSaveFunction()">Save</button>

export class MyComponent {
  @ViewChild('fr', {static: false}) fr: ElementRef;

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

  async customSaveFunction() {
    const response = await this.fr.nativeElement.getScriptApi().saveComposition();
    if (!response.success) {
      throw response.error;
    }
    console.log('Composition saved successfully under composition id(s): ');
    if (response.commitData) {
      response.commitData.forEach((commit => {
        console.log(commit.id);
      }));
    } else {
      console.log(response.uid);
    }
  }
}

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.

<form-renderer [formEnvironment]="environment"
               (onCompositionSaved)="handleSavedComposition($event)">
</form-renderer>

export class MyComponent {

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

  handleSavedComposition($event) {
    if (!$event.detail.success) {
      throw $event.detail.error;
    }
    console.log('Composition saved successfully under composition id(s): ');
    if($event.detail.commitData) {
      $event.detail.commitData.forEach((commit => {
        console.log(commit.id);
      }));
    } else {
      console.log($event.detail.uid);
    }
  }
}

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.

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

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

the updateComposition(validate?: boolean) method can be accessed via the renderer api member. The method returns a promise of a SaveCompositionResponse object.

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

<form-renderer [formEnvironment]="environment" [compositionId]="compositionId" #fr></form-renderer>
<button (click)="updateFunction()">Update</button>

export class MyComponent {
  @ViewChild('fr', {static: false}) fr: ElementRef;

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

  async updateFunction() {
    const response = await this.fr.nativeElement.getScriptApi().updateComposition();
    if (!response.success) {
      throw response.error;
    }
    console.log('Composition updated successfully under updated composition id(s): ');
    if (response.commitData) {
      response.commitData.forEach((commit => {
        console.log(commit.id);
      }));
    } else {
      console.log(response.uid);
    }
  }
}

SaveCompositionResponse Object

The SaveCompositionResponse can have a successful or unsuccessful response:

interface SaveCompositionResponse {
  success: boolean;
  type: SaveCompositionType;
  uid? : string;
  recordKey? : string;
  error? : FormRendererError;
}

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.

export class MyComponent {
  // ...
  pageChange(event) {
    console.error(event);
  }
}

<form-renderer #fr (onPageChanged)="pageChange($event)"></form-renderer>

The event will return information about the page in this form:

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

Interact with Form Renderer

Call Methods​

Handle Events​

Viewing the current composition​

Saving the Composition​

saveComposition Method​

Saving the composition with a dependency on the form​

Updating the Composition​

SaveCompositionResponse Object​

onPageChanged event​