Framework v1.5 now available!

Appearance

On this page

Plugins ​

Plugins enhance the Visiontree framework's core functionality. This guide explains how to use plugins to extend the Auto Renderer's base capabilities.

1. What are Plugins? ​

Plugins in the Visiontree framework are modular extensions that add or modify functionality, allowing developers to tailor the Auto Renderer to their specific requirements. This can include extending the rendering capabilities, adding new UI components, integrating with third-party services, or even changing the behavior of existing features.

2. How Plugins Work ​

Plugins are essentially JavaScript modules that expose a specific interface that the Visiontree framework can interact with. They can be developed and distributed independently, making it easy to share and reuse plugins across different projects.

When a plugin is registered with the Visiontree Auto Renderer, it gains access to the internal Vue instance and other core components of the framework. This allows the plugin to hook into the rendering process, modify the configuration, or even add custom functionality to the application.

3. Creating Your Own Plugin ​

To create a new plugin for the Visiontree framework, follow these steps:

  1. Create a new JavaScript module: Start by creating a new JavaScript file that will contain your plugin code.

  2. Define the plugin interface: The plugin interface is an object that exposes specific methods and properties that the Visiontree framework can interact with. The most important method is the install function, which is called when the plugin is registered with the Visiontree Auto Renderer. This function receives the Vue instance and any plugin options as arguments.

typescript
/**
 * Engine plugin definition.
 * Provides a way to intercept events from the fhir-engine.
 */
export interface EnginePlugin {
  /**
   * The name of the plugin.
   */
  name: string

  /**
   * Called when the plugin has been loaded.
   * @this {EngineAPI} - The Engine API
   */
  onLoad?(this: EngineAPI): unknown

  /**
   * Called when the Engine is initialized.
   * @this {EngineAPI} - The Engine API
   */
  onInit?(this: EngineAPI): void | Promise<unknown>

  /**
   * Called when a Questionnaire resource is loaded by the Engine.
   * This function allows for direct modification of the final Form object before it is used by the application.
   * @this {EngineAPI} - The Engine API
   * @param {Form} form - The form object that is ready.
   */
  onFormLoad?(this: EngineAPI, form: Form): unknown

  /**
   * Handles the save event triggered by the form.
   * This function is called when the form's save event is triggered by the host application.
   * @this {EngineAPI} - The Engine API
   * @param questionnaireResponse - The FHIR QuestionnaireResponse object generated by the form.
   * @returns A Promise that resolves when the save event handling is complete.
   */
  onFormSave?(
    this: EngineAPI,
    questionnaireResponse: r4.QuestionnaireResponse
  ): Promise<unknown>
}
const MyPlugin = {
  layout: 'clinical'
  forms: {
    sources: [questionnaire],
  },
  plugins: [
    {
      id: 'react-plugin',
      async init(payload) {
        console.log('react-plugin init', payload)

        // Add your own form
        //
        // payload.forms.push(questionnaire)

        // Add your own response
        //
        // payload.responses.push(questionnaireResponse)
      },
      async setup(form) {
        console.log('react-plugin setup', form)

        // Access a form before it is rendered.
        //
        // form.items
        // form.itemMap
      },
      async save(questionnaireResponse) {
        console.log('react-plugin save', questionnaireResponse)

        // Intercept the save event from the Core engine
      }
    }
  ]
}

  1. Implement the plugin logic: Inside the init, setup, and save functions, you can implement the plugin's functionality. This can include adding new forms or responses, modifying the configuration, or even intercepting the save event.

  2. Export the plugin: Finally, export the plugin object from your JavaScript module so it can be imported and used in other projects.

typescript
export default MyPlugin

4. Registering and Using Plugins ​

To use a plugin with the Auto Renderer, you first need to import it into your project and then provide it in the configuration object.

javascript
import MyPlugin from './my-plugin'

// Register the plugin with the MFX Auto Renderer
Core.loadConfig({
  // ...
  plugins: [MyPlugin],
})

Once the plugin is registered, its functionality will be available in the Visiontree Auto Renderer instance.

5. Plugin Interface ​

For reference and ease of use the EnginePlugin interface has been provided as a template below.

typescript
/**
 * Engine plugin definition.
 * Provides a way to intercept events from the fhir-engine.
 */
export interface EnginePlugin {
  /**
   * The name of the plugin.
   */
  name: string

  /**
   * Called when the plugin has been loaded.
   * @this {EngineAPI} - The Engine API
   */
  onLoad?(this: EngineAPI): unknown

  /**
   * Called when the Engine is initialized.
   * @this {EngineAPI} - The Engine API
   */
  onInit?(this: EngineAPI): void | Promise<unknown>

  /**
   * Called when a Questionnaire resource is loaded by the Engine.
   * This function allows for direct modification of the final Form object before it is used by the application.
   * @this {EngineAPI} - The Engine API
   * @param {Form} form - The form object that is ready.
   */
  onFormLoad?(this: EngineAPI, form: Form): unknown

  /**
   * Handles the save event triggered by the form.
   * This function is called when the form's save event is triggered by the host application.
   * @this {EngineAPI} - The Engine API
   * @param questionnaireResponse - The FHIR QuestionnaireResponse object generated by the form.
   * @returns A Promise that resolves when the save event handling is complete.
   */
  onFormSave?(
    this: EngineAPI,
    questionnaireResponse: r4.QuestionnaireResponse
  ): Promise<unknown>
}