TriggerCustomEvent Method

Triggers a custom Newlook event which can be consumed by a different session.

Session.TriggerCustomEvent(Name, Value)

Client support

Newlook Smartclient only.

Version Support

Introduced in version 11.1.

Parameters

Name - (String, Required)

A string that is used to identify the event.

Value - (Value, Required)

This parameter can contain any primitive value (string, number, datetime etc.) or a structure.

Use

This method allows you to trigger a custom Newlook event.

When the TriggerCustomEvent method is called, it will generate an event which can be hooked onto by the OnCustomEvent property. This method (and its associated property) are useful if you want to provide callbacks between sessions. For example, you may wish to notify another session that a particular action has finished or that an error has occurred.

The OnCustomEvent property is typically set during the creation of a session (by including the OnCustomEvent parameter in the Options argument of the Add method - see example below), and is used to specify the macro or script to be run when a custom event is triggered. The SessionName parameter of the event can be used to query which session the event was generated from and the EventName can be used to identify the specific event that is being triggered.

The event triggered by TriggerCustomEvent consists of a single argument - an object with the following parameters:

Name	Type	Comments
SessionName	String	The name of the Newlook session that triggered the event.
EventName	String	Name of the event. The name parameter of the 'TriggerCustomEvent' method.
EventValue	Value	Value of the event. The value parameter of the 'TriggerCustomEvent' method.

BE AWARE:

Newlook form and/or control events cannot be triggered by this method.

NOTE:

The events triggered by TriggerCustomEvent can be consumed by Smartframe. This method is essentially the same as the TriggerExternalEvent Method however when you use TriggerCustomEvent, the events can also be consumed by other sessions.

EXAMPLES

JSCRIPT

The following example creates a new session, assigning the OnCustomEvent in the process. This specifies that the script "OnHelperCallback" should run whenever a custom event is triggered in the new session:

var helperSession1 = Session.Add("Helper", {

StartupType: "Logic",

Startup: "HelperStartup",

//Assign "OnHelperCallback" to the 'Session.OnCustomEvent' property

OnCustomEvent: "Events.OnHelperCallback"

});

These examples show two different TriggerCustomEvent calls:

function NameLookup()

{

var memberID = Sessions.Session1.App.GetValue("MemberID");

var result = App.PlayTransaction("GetCustomerName", "CustomerNumber=" + memberID);

if (result != "")

{

// Trigger an event to notify the user that the lookup has completed

TriggerCustomEvent("Lookup Success", "Customer name retrieved.");

}

function OnFirstReceive()

{

// Trigger an event to notify the startup session that the helper session has started.

ThisSession.TriggerCustomEvent("SessionStatus", "Started");

}

The following is the event callback inside the script 'Events':

function OnHelperCallback(args)

{

switch(args.EventName)

{

case "Lookup Success":

// Notify the user that the look up has completed successfully

Sessions.Session1.App.MsgBox(args.EventValue,args.EventName);

break;

case "SessionStatus":

if (args.SessionName == "Helper")

{

//Set a Newlook variable to monitor session status

Sessions.Session1.App.SetValue("Helper", args.EventValue);