Skip to content
This repository has been archived by the owner on Sep 10, 2020. It is now read-only.

A javascript module for setting up and configuring your SPA

Notifications You must be signed in to change notification settings

openmrs/openmrs-esm-root-config

Repository files navigation

openmrs-esm-root-config

Build Status

What is this?

openmrs-esm-root-config is an in-browser javascript module that serves as the single-spa root config for OpenMRS. It is the very first javascript module that is loaded, and controls which other modules are loaded and active for any particular URL.

How do I use it?

openmrs-esm-root-config is available on npm to be downloaded.

Usage (no customization)

To accept all OpenMRS defaults for modules, do the following:

  1. npm install --save @openmrs/esm-root-config. Alternatively, go to get the files from jsdelivr.
  2. Make the file node_modules/@openmrs/esm-root-config/dist/openmrs-esm-root-config.defaults.js available in your import map with the name @openmrs/esm-root-config.

Usage (with customization)

To customize which modules and single-spa applications are used, do the following:

  1. Create a new repo that will be your custom root config. For example, ampath-esm-root-config.
  2. npm install --save @openmrs/esm-root-config. Alternatively, go to get the files from jsdelivr.
  3. Make your repo's bundle available in your import map, with the name @openmrs/esm-root-config.
  4. In your repo's entry file, add the following code:
    import { registerApplication, start } from 'single-spa';
    import { registerAllCoreApplications } from '@openmrs/esm-root-config';
    
    // Get all the core applications
    registerAllCoreApplications();
    // or: registerAllCoreApplicationsExcept(['@openmrs/esm-login', '@openmrs/esm-devtools'])
    
    // Add your own application
    registerApplication(
      'my-custom-app',
      () => System.import('my-custom-app'),
      location => location.pathname.startsWith('/custom')
    )
    
    // start everything up
    start();

API

The following functions are exported from @openmrs/esm-root-config.

registerAllCoreApplications()

registerAllCoreApplications is a function that calls singleSpa.register() for each of the OpenMRS core applications.

Arguments

None

Return value

None (undefined)

Example

import { registerAllCoreApplications } from '@openmrs/esm-root-config';

registerAllCoreApplications();

registerAllCoreApplicationsExcept(applicationNames)

registerAllCoreApplicationsExcept allows you to specify an array of application names that you do not want to be registered from the set of all OpenMRS core applications.

Arguments

  1. applicationNames (required): an array of string names that must correspond with the OpenMRS core applications that you don't want registered.

Return value

None (undefined)

Example

import { registerAllCoreApplicationsExcept } from '@openmrs/esm-root-config';

registerAllCoreApplicationsExcept(['@openmrs/esm-login', '@openmrs/esm-primary-navigation']);

routePrefix(prefix, location)

routePrefix is a utility function that helps you implement single-spa activity functions. The word "route" refers to the browser's url and the word "prefix" refers to a prefix in the pathname.

Arguments

  1. prefix (required): A string that starts with a / character. Any time the browser's url's pathname starts with that url, your application will be active.
  2. location (required): A Location object. You can just pass in the location given to your activity function.

Return value

A boolean that is true when the location matches the prefix, and false otherwise.

Example

See code examples.

import { registerApplication } from 'single-spa';
import { routePrefix } from '@openmrs/esm-root-config';

registerApplication('my-custom-app', () => System.import('my-custom-app'), isCustomAppActive);

function isCustomAppActive(location) {
  return routePrefix('/custom', location);
}

routeRegex(regex, location)

routeRegex is a utility function that helps you implement single-spa activity functions. The word "route" refers to the browser's url and the word "prefix" refers to a prefix in the pathname.

Arguments

  1. regex (required). A regular expression that will be matched against the location's pathname.
  2. location (required). A Location object. You can just pass in the location given to your activity function.

Return value

A boolean that is true when the location matches the prefix, and false otherwise.

Example

import { registerApplication } from 'single-spa';
import { routeRegex } from '@openmrs-esm-root-config';

registerApplication('my-custom-app', () => System.import('my-custom-app'), isCustomAppActive);

function isCustomAppActive(location) {
  return routeRegex(/^patient\/.+\/dashboard/, location);
}