Quick start

Below you can find guidance how to render a form with Form Renderer.

Configure

The following code illustrates a basic component configuration.

export class MyComponent {
  formMetadata = {
    name: 'my-form',
    version: '1.0.0'
  };
  resourceUrl = 'https://better-ehr-server.com/rest/v1';
  credentials = {
    username: 'user',
    password: 'pswd'
  };
  context = {
    language: 'en',
    readonly: false
  };
  compositionId = '28e813d9-5caf-4302-8274-3966a5b1f819::user::1';
}

NOTE version in formMetadata is an optional parameter, if omitted the latest version of that form is used

<form-renderer
        [formMetadata]="formMetadata"
        [resourceUrl]="resourceUrl"
        [credentials]="credentials"
        [context]="context"
        [compositionId]="compositionId">
</form-renderer>

Compositions and CompositionIds

Passing composition or compositionId to the form will fill the form with data from the composition.

• When you pass a composition to the form renderer, the form renderer will fill the form with the composition provided.
• When you pass a compositionId to the form renderer, the form renderer will fetch the composition from the server and fill the form with it.
• When you pass both compositionId and composition, the form renderer will ignore the provided composition and fetch the composition from the server using the compositionId.
• When you do not pass either compositionId or composition, the form renderer will render an empty form.
• When you pass a null value as compositionId, the form renderer will render an empty form.

Configurable EHR form context parameters

We understand that each application has its own use cases and requirements, and we understand we can't cover all those needs without an extensive set of configuration options which you can configure for your needs. Below are instructions how to pass configuration (EhrFormContext object) to Form Renderer. For more details about options head to EhrFormContext.

<form-renderer
        [formMetadata]="formMetadata"
        [resourceUrl]="resourceUrl"
        [credentials]="credentials"
        [context]="context"
        [compositionId]="compositionId">
</form-renderer>

export class MyComponent {

  // ...
  context = {
    language: 'en',
    readonly: false,
    territory: 'SI',
    presentationMode: true,
    showAllPages: false,
    dateFormat: 'dd/MM/yyyy',
    autoPrefill: {
      enabled: true,
      mode: 'LATEST_COMPOSITION'
    }
  };
}

Credentials

There are two ways of providing credentials to the renderer directly:

• Basic Auth
• OAuth 2.0

Basic Auth

With basic auth you only provide a resource url and a username and password for the url. authType can be set to basic or it can be left out entirely.

<form-renderer [credentials]="credentials"></form-renderer>

credentials = {
  username: 'my_user',
  password: 'my_password'
};

OAuth 2.0

Form renderer also supports OAuth2.0, where you can provide the form renderer with an access token.

Instead of username and password you provide a credentials object with authType and token. authType value for OAuth2.0 is oauth2 while you should get the token from your auth server.

<form-renderer [credentials]="credentials"></form-renderer>

credentials = {
  authType: 'oauth2',
  token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
};

This example, however, is only the first step in configuring the renderer, because the token will eventually expire. If you do not provide a new token until then the renderer has a built-in fallback and will trigger an onRequestUpdatedToken output event you can use to pass a function that updates the token.

<form-renderer [credentials]="credentials"
               (onRequestUpdatedToken)="provideNewToken()">
</form-renderer>

export class MyComponent {
  provideNewToken() {
    // implement refresh token
  }
}

To update the token you can use the updateToken(token) method call. The token can be updated at any time, however the renderer does expect an updated token within 5000ms after emitting the onRequestUpdatedToken event. If a new token is not provided or an invalid token is passed the renderer will throw an error.

To access the method on the element you can use @ViewChild like in the example below

<form-renderer #fr
               [credentials]="credentials"
               (onRequestUpdatedToken)="provideNewToken()">
</form-renderer>

import {ElementRef} from 'angular/core';

export class MyComponent {

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

  credentials = {
    authType: 'oauth2',
    token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
  };

  async provideNewToken() {
    // fetch refresh token

    const refreshedToken = await ... // <--- retrieved new access token
    this.fr.nativeElement.updateToken(refreshedToken);
  }
}

Alternatively you can provide form-renderer with a new credentials object, which will also trigger the updateToken input:

<form-renderer #fr 
               [credentials]="credentials" 
               (onRequestUpdatedToken)="provideNewToken()">
</form-renderer>

export class MyComponent {

  credentials = {
    authType: 'oauth2',
    token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
  }

  async provideNewToken() {
    // fetch refresh token
    const refreshedToken = await ... // retrieved new access token
    this.fr.nativeElement.credentials = {authType: 'oauth2', token: refreshedToken};
  }
}

If a new token is not received in 5000ms the form renderer will throw an error.