HOME DOCUMENTATION DOWNLOADS

Html Client Plugins

Html client plugins can be used to implement features not supported by origam and to supplement origam modeling where necessary using a piece of custom react code.
There are two kinds of plugins so far, both of which can use javascript/react to create a custom user interface. The section level plugin has access to screen section data and can be used to display them. The screen level plugin can change data fed into section level plugins by modifying the screen parameters.
We will demonstrate how to get started with the plugins on Audit screen from the Audit package which you can find it in the standard Origam distribution. The hello world style plugins we will create here won’t do much but you can find a more complex implementation of the Audit view using plugins in the demo project https://github.com/origam/origam-demo.
Before you start creating a plugin make sure you have origam Root package version 5.1.8 or higher.

Plugin Placement

The plugins can be placed on any lazy loaded screen. To make a screen lazy loaded you have to specify a ListMethod, Method and ListSortSet in MenuItem.

Next you have to place the plugin (or a placeholder rather) on a screen. This is done in screen editor in Architect.

In the widget properties you have to specify the plugin’s SchemaItemName. Name the screen level plugin TestScreenPlugin and the section level plugin TestSectionPlugin. The section level plugin needs a DataMember so be sure to select one here. Also note that exactly one SectionLevelPlugin in the section must have the property AllowNavigation set to true. This is an equivalent of one screen section being a master and others details. So the AllowNavigation property would not be set to true if there were a master screen section here.

image

The widgets can be used to configure the plugins by passing custom parameters. To define the parameters open the plugin widget in Architect (root package → User Interface → Widgets → Basic Controls) and add a new property by right clicking on the Properties folder.

image

The widgets already placed in screens will not be updated after you add a new property. To see the new property in the screen editor remove the widget you just added the property to and add it again.

Running the Client

To create a plugin you have to compile the html client application. First clone repository GitHub - origam/origam-html: ORIGAM HTML Client application. somewhere on your machine and install latest version of Node.js.

Then open command line in the repo’s root directory and run:

npm install -g yarn

this will install the yarn package manager. Next run

yarn install

this will download and install all dependencies.

We will run the client application on a nodejs development server to make debugging simple. Before we do that we will also need an origam server to connect to and get the data from. You can use any running origam server you have access to: installed in IIS or in docker, local or remote. Just note the address and port the server is running on and write it to an environment variable WDS_PROXY_TARGET.

Now you can run the project with this command

yarn start

a development server should be started at https://localhost:3000/ when you go to that address you should see the client application.

Creating the Plugin

The client is written in typescript and react. You can use any javascript editor to edit the project like Visual Studio Code for example.

All plugin files should be located in origam-html5\src\plugins\implementations and registered in origam-html5\src\plugins\tools\PluginRegistration.ts file. The exported classes defined here will be recognized as plugins by the application. It is therefore important to prefix the plugin’s class definition with export defaut keywords and give the classes the same names the widgets in the Architect have.
Create a new file there and call it TestScreenPlugin.tsx. After that you can copy the following code into it:

import {IScreenPlugin} from "../types/IScreenPlugin";
import {IPluginData} from "../types/IPluginData";

export default class TestScreenPlugin implements IScreenPlugin {
  $type_IScreenPlugin: 1 = 1;
  requestSessionRefresh: (() => Promise<any>) | undefined;
  setScreenParameters: ((parameters: { [p: string]: string }) => void) | undefined;

  getComponent(data: IPluginData): JSX.Element {
    return <div>TestPlugin!</div>;
  }

  initialize(xmlAttributes: { [p: string]: string }): void {
  }
}

As you can see the plugin implements interface IScreenPlugin and all its fields and methods.

The field $type_IScreenPlugin is not explicitly defined in the interface but it is needed to clearly show that the objects created from this class implement the interface.

requestSessionRefresh is a method you can call to refresh the screen (data)

setScreenParameters is a method you can use to set screen parameters

getComponent will be called when rendering the component and what you return here will be used to replace the placeholder widget you added to the screen in the Architect. The input to the method contains model and database data you can use in your component.

initialize is called after the application starts and the xmlAttributes parameter contains among other things the properties that you can model in architect and use them to configure the plugin.

Now we can create another file called TestSectionPlugin.tsx and put this into it:

import {ISectionPlugin} from "../types/ISectionPlugin";
import {IPluginData} from "../types/IPluginData";

export default class TestSectionPlugin implements ISectionPlugin {
  $type_ISectionPlugin: 1 = 1;
  getScreenParameters: (() => { [p: string]: string }) | undefined;

  getComponent(data: IPluginData): JSX.Element {
    return <div>{data.dataView.properties.map(prop => prop.id+", ")}</div>;
  }

  initialize(xmlAttributes: { [p: string]: string }): void {
  }
}

The TestSectionPlugin implements IsectionPlugin interface. As you can see this plugin cannot refresh the screen or set screen parameters but it can get the parameters and their values.

Finaly we have to register the plugins in the origam-html5\src\plugins\tools\PluginRegistration.ts file so that the plugin classes can be recognized as plugins and found by the application:

export function registerPlugins(){
  registerPlugin("TestScreenPlugin", () => new TestScreenPlugin());
  registerPlugin("TestSectionPlugin", () => new TestSectionPlugin());
}

Now when we open audit view on any page:

image

We should see this:

Localization

to use localization features you have to create an instance of Localizer class and suply localization data to it’s constructor. The data should be placed in a separate file next to the plugin file. The localization file for the TestScreenPlugin would be named TestScreenPluginLocalization.ts. The file should contain a constant named localizations in the following format:

export const localizations = [
  {
    locale: "de",
    translations: {
      day: "Tag",
    }
  },
  {
    locale: "cs-CZ",
    translations: {
      day: "Den",
    }
  },
  {
    locale: "en-US",
    translations: {
      day: "Day",
    }
  },
]

To localize a string inside you plugin call translate(key: string, parameters?: {[key: string]: any})
method of the localizer where the key is the key from the localization file and parameters is an object with named parameters. The localization strings are interpreted using library called messageformat. Look here to learn how you can parametrize your strings: Format Guide - messageformat a nice debug tool is also available here: Online ICU Message Editor

What can the plugins depend on

The plugins get model and database data when the getComponent(data: IpluginData) method is called. You can explore the IpluginData interface and everything in it in the origam-html5\src\plugins\types folder.

If you want to make your plugins look similar to the rest of the application, you can use components from this folder: origam-html5\src\gui\Components\PublicComponents. You can also reference colors from this file: origam-html5\src\styles\colors.scss

1 Like