Skip to main content

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 access properties, you need to get the reference to formRenderer object via reference handler HandleRef.

class App extends Component {
  // methods
  onValidateForm = () => {
    const validationModel: object = this.component.validate(true);
  }

  onSetFieldValue = () => {
    const scriptApi = this.component.getScriptApi();
    scriptApi.setFieldValue('path/to/form/element', 'value');
  }
}
    
// reference handler
handleRef = component => {
  this.component = component;
};

// ref={this.handleRef} is crucial
render() {
  return (
    <div className="App">
      <form-renderer ref={this.handleRef}></form-renderer>
   </div>
  );
}

Handle Events​

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

export class MyComponent {
  valueChange = (event) => {
    console.log('onValueChange', event.detail);
  };

  formRendered = (event) => {
    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.

Pass events as arrow function!

class App extends Component {
  valueChange = (event) => {
    console.error('composition', this.component.composition);
  };

  componentDidMount() {
    // ...
    this.component.addEventListener('onValueChange', (event) => valueChange(event));
    this.component.addEventListener('onFormRendered', (event) => formRendered(event));
  }

  // reference handler
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
     </div>
    );
  }
}

Viewing the current composition and other formRenderer properties​

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

// define a logger method
logger = () => {
  console.log(this.component.composition)
  // get other properties by replacing 'composition'
}

// reference handler
handleRef = component => {
  this.component = component;
};

// ref={this.handleRef} is crucial
render() {
  return (
    <div className="App">
      <form-renderer ref={this.handleRef}></form-renderer>
      <button onClick={this.logger}> Log </button>
   </div>
  );
}

Saving the Composition​

You can save the composition by 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.

class App extends Component {
  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.

class App extends Component {
  // ... all necessary data
  environment = {
    variables: [
      {
        name: 'ehrId',
        value: '000-92ac-4bf6-bfed-f0d4b9f6'
      }
    ]
  };
  
  // define customSaveFunction() here
  customSaveFunction = async () => {
    const response = await this.component.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);
    }
  };
  
  // define component properties and methods inside componentDidMount()
  componentDidMount() {
    // ...
    this.component.compositionId = this.compositionId;
    this.component.formEnvironment = this.environment;
  }
  
  // reference handler
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  // create an onClick event for the custom button
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
        <button onClick={this.customSaveFunction}> Save </button>
     </div>
    );
  }
}

Saving the composition with a dependency on the form​

If the form uses a dependency to save the composition, this will emit an onCompositionSaved event which also outputs a save composition response object within the detail parameter of the response.

class App extends Component {
  // define environment and other data
  environment = {
    variables: [
      {
        name: 'ehrId',
        value: '000-92ac-4bf6-bfed-f0d4b9f6'
      }
    ]
  };

  // define handleSavedComposition method
  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);
    }
  };
  
  // define component method inside componentDidMount() method and make sure to pass the event as an arrow function
  componentDidMount() {
    // ...
    this.component.formEnvironment = this.environment;
    this.component.addEventListener('onCompositionSaved', (event) => this.handleSavedComposition(event))
  }
  
  // reference handler
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
     </div>
    );
  }
}

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.

class App extends Component {
  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.

class App extends Component {
  environment = {
    variables: [
      {
        name: 'ehrId',
        value: '000-92ac-4bf6-bfed-f0d4b9f6'
      }
    ]
  };
  compositionId = 'f8805e7e-0000-1111-222c-74ca6b0a53e9::test::1';
  
  // define updateFunction() method as an arrow function
  updateFunction = async () => {
    const response = await this.component.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);
    }
  };
  
  // define component properties and methods inside componentDidMount()
  componentDidMount() {
    // ...
    this.component.compositionId = this.compositionId;
    this.component.formEnvironment = this.environment;
  }
  
  // reference handler
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
        <button onClick={this.updateFunction}> Update </button>
     </div>
    );
  }
}

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.

class App extends Component {
  // define method
  pageChange = (event) => {
    console.error(event);
  };
  
  componentDidMount() {
    // add an event listener on component ref
    this.component.addEventListener('onPageChanged', (event) => this.pageChange(event));
  }
  
  // reference handler
  handleRef = component => {
    this.component = component;
  };
  
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
     </div>
    );
  }
}

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

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