CustomizeJS and LoadAndRun

CustomizeJS and LoadAndRun are JavaScript files which can be loaded in the AMT Web Client in order to customize the application.

These script files can be configured in the appsettings.json file of the Blazor web client Server Web Application.

As this functionality is not part of the main AMT product suite, while unlikely, it is possible that specific functions are changed with newer AMT versions.
Due to the custom nature of this script customers are advised to test their CustomizeJS and LoadAndRun scripts thoroughly themselves when upgrading the AMT environment to a newer version.

CustomizeJS

This script is loaded in the application once when the web client has finished loading. It can be used to customize the web client, e.g. to add custom buttons, change the look and feel, or to add custom functionality.

LoadAndRun

The LoadAndRun JavaScript script is a customer specific customization which can modify the values to and from an AMT web client form by hooking into the form at certain loading stages on runtime.

These stages are:

LoadObjects: Executes when the form is initially loaded.
RunObjects: Executes before values are sent to the server by a transmit.
Using 'RunObjects', you can also block a transmit from happening by returning false. This is useful if a button click is handled in a custom JS script.
RefreshObjects: Executes when the form is refreshed with values.

The hooks must be created with the following syntax:

async function LoadObjects() {
    // your custom implementation
}

async function RunObjects() {
    // your custom implementation
    return true; // return false to block the transmit
}
async function RefreshObjects() {
    // your custom implementation
}

AMT CustomJS API

The WebClient API provides a collection of JavaScript methods and classes that allow you to interact with and customize the WebClient interface. These methods are designed to help developers set and retrieve values, modify component states, and manage UI updates effectively. However, the API is intentionally limited to operations that directly affect the WebClient and its components.

Key points:

Specific to WebClient Interaction: The API exposes only those methods that are relevant for interacting with the WebClient’s components, such as setting values, getting values, and managing lists. These operations are critical as they trigger re-renders to ensure the WebClient behaves as expected.
Does Not Include Common JavaScript Utilities: The WebClient API does not include common JavaScript functionality such as DOM manipulation methods (e.g., calculating the cumulative position of an element). These are considered standard JavaScript features and can be implemented by the developer themselves.

JS namespace: `Amt`

This namespace contains all classes and enums necessary to interact with the web client.

Abstract base class: `AmtControl`

This abstract base class is used to interact with the controls in the web client. It provides methods to get and set values. All specific AmtControl implementations (e.g. AmtButtonGroup, AmtLabel, etc.) inherit this base class.

Method: `getValue(): Promise<string>`

This method gets the formatted AMT value of the control. It returns a promise that resolves with the current value: Formatted value means the value that AMT is using on the backend. For example, when a control has the value type boolean getValue will return either 'T' or 'F'.

Since all control types are inheriting from AmtControl, this method is available on all control classes. However, it is only functional for the following types: AmtButtonGroup, AmtCalendar, AmtCheckbox AmtComboBox, AmtEdit, AmtLabel, AmtListBox, AmtMaskEditBox, AmtMemo and AmtRadioButton. If the method is used unsupported controls, an error will be thrown.

let myLabel = new Amt.AmtLabel('DISPLAY_0');
let myLabelValue = await myLabel.getValue();

Method: `setValue(value: string): Promise<void>`

This method sets the value of the control. It returns a promise that resolves when the value is set. The provided value must comply with the formatted AMT value. The same format as used in getValue is expected. For example, when setting a boolean value, you should use 'T' or 'F'. Using wrong formatted values may result in unexpected behavior or errors.

The value will only be set if the control isn’t readonly or disabled. If the control is readonly or disabled, an error will be thrown.

let myLabel = new Amt.AmtLabel('DISPLAY_0');
await myLabel.setValue('New Value');

Method: `getElement(): HTMLElement | null`

This method returns the HTML element associated with the control. It can be used to manipulate the DOM directly if needed. If the element could not be found, it returns null:

let myLabel = new Amt.AmtLabel('DISPLAY_0');
let myLabelElement = myLabel.getElement();

Abstract base class: `AmtListControl` extends `AmtControl`

This abstract base class is inherited by the list controls in the web client (AmtComboBox and AmtListBox). It provides the ability to set list items.

Method: `setListItems(items: [{ Text: string, Value: any }]): void`

This method sets the list items for the control. It takes an array of objects with Text and Value properties:

let myComboBox = new Amt.AmtComboBox('COMBOBOX_0');
myComboBox.setListItems([
    { Text: 'Item 1', Value: '1' },
    { Text: 'Item 2', Value: '2' }
]);

Class: `AmtButtonGroup` extends `AmtControl`

Constructor: new Amt.AmtButtonGroup(amtId: string, subsessionId: number = 1)

Class: `AmtCalendar` extends `AmtControl`

Constructor: new Amt.AmtCalendar(amtId: string, subsessionId: number = 1)

Class: `AmtChart` extends `AmtControl`

Constructor: new Amt.AmtChart(amtId: string, subsessionId: number = 1)

Class: `AmtCheckBox` extends `AmtControl`

Constructor: new Amt.AmtCheckBox(amtId: string, subsessionId: number = 1)

Class: `AmtComboBox` extends `AmtListControl`

Constructor: new Amt.AmtComboBox(amtId: string, subsessionId: number = 1)

Class: `AmtDatagrid` extends `AmtControl`

Constructor: new Amt.AmtDatagrid(amtId: string, subsessionId: number = 1)

Class: `AmtDynamicForm` extends `AmtControl`

Constructor: new Amt.AmtDynamicForm(amtId: string, subsessionId: number = 1)

Class: `AmtEditBox` extends `AmtControl`

Constructor: new Amt.AmtEditBox(amtId: string, subsessionId: number = 1)

Class: `AmtFileUploader` extends `AmtControl`

Constructor: new Amt.AmtFileUploader(amtId: string, subsessionId: number = 1)

Class: `AmtImage` extends `AmtControl`

Constructor: new Amt.AmtImage(amtId: string, subsessionId: number = 1)

Class: `AmtLabel` extends `AmtControl`

Constructor: new Amt.AmtLabel(amtId: string, subsessionId: number = 1)

Class: `AmtListBox` extends `AmtListControl`

Constructor: new Amt.AmtListBox(amtId: string, subsessionId: number = 1)

Class: `AmtListview` extends `AmtControl`

Constructor: new Amt.AmtListview(amtId: string, subsessionId: number = 1)

Class: `AmtMaskEditBox` extends `AmtControl`

Constructor: new Amt.AmtMaskEditBox(amtId: string, subsessionId: number = 1)

Class: `AmtMemo` extends `AmtControl`

Constructor: new Amt.AmtMemo(amtId: string, subsessionId: number = 1)

Class: `AmtMenu` extends `AmtControl`

Constructor: new Amt.AmtMenu(amtId: string, subsessionId: number = 1)

Class: `AmtPanel` extends `AmtControl`

Constructor: new Amt.AmtPanel(amtId: string, subsessionId: number = 1)

Class: `AmtRadioButtonGroup` extends `AmtControl`

Constructor: new Amt.AmtRadioButtonGroup(amtId: string, subsessionId: number = 1)

Class: `AmtScrollBox` extends `AmtControl`

Constructor: new Amt.AmtScrollBox(amtId: string, subsessionId: number = 1)

Class: `AmtShape` extends `AmtControl`

Constructor: new Amt.AmtShape(amtId: string, subsessionId: number = 1)

Class: `AmtTabSheet` extends `AmtControl`

Constructor: new Amt.AmtTabSheet(amtId: string, subsessionId: number = 1)

Class: `AmtTimer` extends `AmtControl`

Constructor: new Amt.AmtTimer(amtId: string, subsessionId: number = 1)

Class: `AmtForm`

This class contains properties of the current form that is shown within the web client. Property: activeControlName: String Property: eventSourceName: String Property: formName: String Property: language: String Property: messages: Array<String> Property: objectFields: String Property: userPreference: AmtUserPreference

An instance can be requested by doing the following call:

let form = await Amt.AmtFormInstance();

Extension to `Document`

Method: `document.getElementByAmtId(amtId: string, subsessionId?: number): HTMLElement | null`

This method will retrieve the right HTMLElement based on given amtId. The subsessionId is optional (defaults to 1) and needs to be used to select element within popups.

let buttongroupElement = document.getElementByAmtId('BUTTONGROUP_0');

Method: `document.getAmtControlByAmtId(amtId: string, subsessionId?: number): HTMLElement | null`

This method will retrieve the right AmtControl instance based on given amtId. The subsessionId is optional (defaults to 1) and needs to be used to select controls within popups. The type AmtControl that needs to be constructed is based on the controltype attribute within the HTML element. Therefore, the control must be rendered in the DOM before this method can be used. This is not the case when directly constructing using the constructor of the control.

let myCombobox = document.getAmtControlByAmtId('BUTTONGROUP_0');
myCombobox.setListItems([
    { Text: 'Item 1', Value: '1' },
    { Text: 'Item 2', Value: '2' }
]);

Example scenarios

Handle button click in custom JS and prevent transmit from being executed.

This can be realized using the LoadAndRun functionality by hooking into the LoadObject function of the LoadAndRun script:

LoadAndRun.js

async function LoadObjects() {
    let currentForm = await Amt.AmtFormInstance();

    if (currentForm.formName === "MY_FORM") { // only attaches handler for a specific form
        let myButton = document.getElementByAmtId('BUTTONGROUP_0');
        
        // Add an event listener to handle the click
        myButton.addEventListener('mousedown', function(event) {
            // To prevent the transmit, we need to prevent the default action and stop propagation:
            event.preventDefault();
            event.stopPropagation();

            console.log("Button clicked, but transmit prevented.");
        });
    }
}

Block transmit when a certain checkbox is checked.

This can be realized using the LoadAndRun functionality by hooking into the RunObject function of the LoadAndRun script:

LoadAndRun.js

async function RunObjects() {
    let currentForm = await Amt.AmtFormInstance();

    if (currentForm.formName === "MY_FORM") { // only attaches handler for a specific form
        let myCheckbox = document.getAmtControlByAmtId('CHECKBOX_0');
        
        if (await myCheckBox.getValue() !== 'T') return false; // Only proceed if checkbox is checked

        // In all other cases, we do not want to block the transmit:
        return true;
    }
}

CustomizeJS and LoadAndRun

CustomizeJS

LoadAndRun

AMT CustomJS API

JS namespace: Amt

Abstract base class: AmtControl

Method: getValue(): Promise<string>

Method: setValue(value: string): Promise<void>

Method: getElement(): HTMLElement | null

Abstract base class: AmtListControl extends AmtControl

Method: setListItems(items: [{ Text: string, Value: any }]): void

Class: AmtButtonGroup extends AmtControl

Class: AmtCalendar extends AmtControl

Class: AmtChart extends AmtControl

Class: AmtCheckBox extends AmtControl

Class: AmtComboBox extends AmtListControl

Class: AmtDatagrid extends AmtControl

Class: AmtDynamicForm extends AmtControl

Class: AmtEditBox extends AmtControl

Class: AmtFileUploader extends AmtControl

Class: AmtImage extends AmtControl

Class: AmtLabel extends AmtControl

Class: AmtListBox extends AmtListControl

Class: AmtListview extends AmtControl

Class: AmtMaskEditBox extends AmtControl

Class: AmtMemo extends AmtControl

Class: AmtMenu extends AmtControl

Class: AmtPanel extends AmtControl

Class: AmtRadioButtonGroup extends AmtControl

Class: AmtScrollBox extends AmtControl

Class: AmtShape extends AmtControl

Class: AmtTabSheet extends AmtControl

Class: AmtTimer extends AmtControl

Class: AmtForm

Extension to Document

Method: document.getElementByAmtId(amtId: string, subsessionId?: number): HTMLElement | null

Method: document.getAmtControlByAmtId(amtId: string, subsessionId?: number): HTMLElement | null