Skip to main content

Quick start

Below you can find guidance how to render a form in Vue.js framework with Form Renderer. For more details on web components in Vue.js check out the official documentation: https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue

Configure​

The following code illustrates a basic component configuration.

Inside script tag export following data: 

<script>
  export default {
    data() {
      return {
        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'
      }
    }
  }
</script>

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

Template/HTML: The dot before each parameter is crucial.

<template>

  <form-renderer 
    .formMetadata="formMetadata" 
    .resourceUrl="resourceUrl" 
    .credentials="credentials"
    .context="context"
    .compositionId="compositionId">
  </form-renderer>
  
</template>

The form should now be rendered, if you followed the steps correctly.​

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>
<script>  
  export default {
    data() {
      return {
        // ...
        context: {
          language: 'en',
          readonly: false,
          territory: 'SI',
          presentationMode: true,
          showAllPages: false,
          dateFormat: 'dd/MM/yyyy',
          autoPrefill: {
            enabled: true,
            mode: 'LATEST_COMPOSITION'
          }
        }
      }
    }
  }
</script>

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 default {
   data() {
     return {
       //...     
     }
   },
   methods: {
     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.

Add a reference

<form-renderer  
                ref="fr"
               .credentials="credentials"
               .(onRequestUpdatedToken)="provideNewToken()">
</form-renderer>
// declare form-renderer custom element variable
let form;

export default {
   // when element is mounted get its reference and save it in the variable
   mounted(){
     form = this.$refs.fr
   },
   data() {
     return {
       credentials: {
         authType: 'oauth2',
         token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
       },
       //... 
     }
   },
   methods: {
     async provideNewToken() {
       // fetch refresh token

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

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

<form-renderer 
                ref="fr" 
               .credentials="credentials" 
               .(onRequestUpdatedToken)="provideNewToken()">
</form-renderer>
// declare form-renderer custom element variable
let form;

export default {
     // when element is mounted get its reference and save it in the variable
     mounted(){
       form = this.$refs.fr
     },
     data() {
       return {
         //...
         credentials: {
           authType: 'oauth2',
           token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
         }     
       }
     },
     methods: {
       async provideNewToken() {
          //implement refresh token
          const refreshedToken = await ... // <--- retrieved new access token
          form.credentials = {authType: 'oauth2', token: refreshedToken}    
       }
     }
  }

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