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.

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.

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;
    }
}