Skip to content
Web

Callbacks

Overview

Callbacks run user-defined AmiScript on specific processes to perform a defined action. For example, callbacks can be initiated when layouts are loaded, when a datamodel is run, when a field state changes, and more.

Callbacks can be set in various parts of AMI for different purposes:

  1. Layout Callbacks

    • Sets actions for layout-wide events, such as when a layout is loaded
    • Found in Dashboard -> Custom Callbacks

  2. Divider Callbacks

    • Callbacks that fire when dividers are interacted with
    • Found in the divider sub-menu Div -> AmiScript Callbacks

  3. HTML Field Callbacks

    • Callbacks associated to the various HTML fields such as buttons, upload fields, text fields, etc
    • Found in each individual HTML field creation wizard in the AmiScript tab

  4. Table Callbacks

    • Sets behaviors for changes associated to tables
    • Found in the table sub-menu Table -> AmiScript Callbacks

  5. Datamodel Callbacks

    • Sets actions for datamodel changes
    • Found in the datamodel creation wizard

Layout Callbacks

Definitions

onAsyncCommandResponse(response)
This callback triggers when 3forge receives a response to an execution of a registered command.
onKey(keyEvent)

This callback is triggered on most keystrokes from the keyboard, however there are some keys that this does not apply too, shift, ctrl, and esc for example. It is overridden by any field that has its own onKey callback. For example, the text field in a html field panel will not trigger this callback when the user types in this field however the filter box for a table will trigger this callback as there are no callbacks on a filter field as standard.

keyEvent

The key event is an object that contains the key object. This object holds the key that was pressed.

onMouse(event)

This callback is triggered by all mouse events. The event specifies the type of click (left, middle, right) and the event type (e.g. mouse down). Clicks on the toolbar will not trigger this event.

event

The mouse event is an object that contains the mouse click type, event type, and additional information e.g. position.

onNotificationHandled(id,status,attachment)

This callback triggers when user clicks on a notification.

onStartup()

The script of this callback is executed once when layout finishes loading but before the query-on-startup-datamodel runs (e.g. on user login, rebuild etc.)

onStartupComplete()

This callback is executed when the layout has loaded, query-on-startup-datamodels have run, and user preferences have been loaded or ignored.

onUrlParams()

This callback is executed when a page is refreshed and there are parameters present in the URL e.g. host:33332/portal/portal.jsp?a=b.

These params are passed to the callback in a map.

onUserPrefsLoaded(userPrefs)

This is triggered when user preferences are successfully loaded.

onUserPrefsLoading(userPrefs)

This is triggered when user preferences are in the process of being loaded, this could be when the user first presses the save button to begin the update of their default timezone.

onUserPrefsSaved(userPrefs)

This is triggered when user preferences are successfully saved.

onUserPrefsSaving(userPrefs)

This is triggered when user preferences are in the process of being saved, this could be the user updating their default connection timeout.

userPrefs

This object contains a list of all user preferences.

User Login Diagram

The diagram below describes the natural order of execution when a user logs in and loads an 3forge session of the different 3forge callbacks and their loading processes.

Note

Having deferred statements in any of the callbacks can cause them to finish execution later than other callbacks that follow, however it won't affect the starting order.

Example: onUrlParams()

The onUrlParams(Map params) callback can be used to control a dashboard based on URL parameters.

This example assumes that the base URL for accessing 3forge is localhost:33332.

  1. First, create a new window, click on the green icon, then select Place Highlighted In Tab:

  2. Select the green icon for the Tabs and select Add Tab:

  3. Click on the dropdown arrow for the first tab to access the tab's settings then change both the title and id for the first tab.

  4. Repeat this for the second tab:

  5. Now that we have two tabs, navigate to Dashboard -> Custom Callbacks to the onUrlParams(Map params) callback.

    Note

    You may have to use the arrows on the right hand side to scroll to the onUrlParams(Map params) callback.

  6. Finally, we can import the tabs using the right hand menu and add the following AMIScript to select tabs based on the URL parameters:

    1
2
3
4
5
6
7
    String selectedTab = params.get("tab");

if (selectedTab == "first") {
Tabs1.setSelectedTab(first_tab);
} else if (selectedTab == "second") {
Tabs1.setSelectedTab(second_tab);
}

    The final callback should appear as shown below:

  7. Finally, test the URL by accessing http://localhost:33332/3forge?tab=first and http://localhost:33332/3forge?tab=second.

Divider Callbacks

Definitions

onDividerMoved(offsetPct, offsetPx)

This callback is triggered when a divider is clicked, moved, and dropped in a new location by the user. This does not trigger if the user clicks the divider but doesn't move it.

Example

  1. Create a window with two panels separated by a divider, Div1:

  1. Right click on the divider, go to AmiScript Callbacks -> OnDividerMoving() and enter the following AmiScript:

  1. Hit Submit. Now as we drag the divider, the OnDividerMoved() callback gets fired.

onDividerMoving(offsetPct, offsetPx)

This callback is triggered as soon as the divider is moved regardless of whether the user drops the divider, this is repeatedly triggered on every move the divider makes.

offsetPct

This gives a percentage for the offset value for the divider in relation to the divider to its left in vertical dividers and the divider above it in horizontal dividers.

offsetPx

This gives the offset value for the divider in pixels in relation to the divider to its left in vertical dividers and the divider above it in horizontal dividers.

HTML Field Callbacks

Definitions

onChange()

This is triggered when the field state is changed via user interaction from AMI Web. This could be pressing a button or typing in a text box.

Note

Setting HTML fields programmatically does not trigger the onChange() callback.

For example, the AmiScript textfield.setValue("hello") will not trigger the callback. Typing "hello" into that text field in AMI will trigger the callback.

onFocus()
This callback will run the provided script when the current element becomes active, this could be for example 'tabbing' or clicking into a text box.
onAmiJsCallback()

This callback is executed when javascript invocations of the same function name are executed within the browser.

1
**Example**
  1. Create a HTML Panel and select Edit HTML.
  2. Create a simple button as such: <button onclick='amiJsCallback(this,"action",1, {b:2}, "3")'> Button </button>.
  3. When the button is clicked, the onAmiJsCallback function is fired from the HTML Panel:
    • The 2nd param is passed to the action parameter as a string
    • The 3rd param is passed to the param parameter as a list of all remaining items. In our example, this would result in List(1, Map("b",2), "3")

Table Callbacks

Definitions

onCellClicked(column, val, rowvals)

This callback gives the user the flexibility to add personalized options when a cell is clicked.

Examples

The following three commands will create a pop-up message box stating the column name, cell value or all the row values with their corresponding column names:

session.alert(column);

session.alert(val);

session.alert(rowvals);

Turn "Clickable" on under edit column:

onColumnsArranged()

This callback gives the user the option to add personalized features when columns are rearranged.

onEdit(vals, oldVals)

This callback is triggered whenever a value in the table is edited and then saved. This does not trigger if the value is the same as its original state when saved; if the value has been changed and then reverted to it's original state before being saved it will not trigger.

Two tables are returned when triggered, vals and oldVals. vals contains the latest version of the edited cells while oldVals contains the original values before being saved.

The values stored inside these tables are defined using the "Edit Column" menu.

The menu can be accessed by left clicking the header of a column and choosing the "Edit Column" option from the dropdown box as shown above. Looking at the cell editing section of this menu allows the user to define how they want this column's data to be accessible to the user.

Example

At the bottom of the menu there is an option labelled clickable, when this is set to On the user will be able to double click cells in this column and edit them in real-time. The data in the table backing the table visualization will only be changed if the user has written a specific script to do so.

There are multiple options available, the readonly option allows the user to include the value of the cells in the vals and oldVals tables. The other options define the datatype of the new value that is entered into the edited cell, this datatype must match the original type of the cell.

onFilterChanging()

This callback gives the user the option to add personalized features when any filters are added, changed or removed.

onSelected()

This callback gives the user the option to add personalized features for selecting a cell/row.

onSize(width, height)

This callback gives the user the option to add personalized features when the size of the selected panel is changed.

onVisible(visible)

This callback gives the user the option to add personalized features when the selected panel is visible or not visible(minimized).

Datamodel Callbacks

Definitions

onProcess() and onComplete() are two datamodel callbacks that are executed sequentially.

Every time the datamodel is run, it first runs the code in onProcess() and caches the result in the datamodel cache. Next, it runs the code inside onComplete() and updates the changes in the UI.

Examples

onProcess(WHERE,wheres,rtevents)

First let's create a datamodel on the table "City" from the mySQL database.

In the onProcess() tab, select everything from the "City" table:

onComplete(WHERE,wheres)

In the onComplete() tab, enter the following code to set up a filter and bring the panel to the front:

Upon clicking "Finish", the datamodel is going to do the following:

  • First, it runs the code in onProcess() which instantiates the table.
  • Second, it runs the code in onComplete() which filters out the cities whose population is less than 200000 and brings the panel to the front.