Scroll

Introduction to Action Events

Action Events can be grouped into two general categories: Local and Global events.

  • Local events have two sub-categories:
    • Handlers attached to items in reports and set to fire automatically, or when the item is interacted with in the Report Viewer.
    • Handlers attached to items in the Exago UI and set to fire when that item is clicked.
  • Global events are active throughout the application, and fire when specific events occur.

This article explains how to create Local and Global action events, describes the ways in which action events can interact with the Exago application, and lays out examples for common usages.

Creating Event Handlers

Action event handlers are created using the Admin Console or by directly editing the WebReports.xml config file. They can also be added or modified on a per-session basis in a .NET configuration using the 'Api.SetupData.ActionEvents' server call.

  • To create a new Event Handler expand ‘Extensions’ in the Main Menu, select ‘Action Events’, and click the add button.
  • To edit an Event Handler either double click it or select it and click the edit button.
  • To delete an Event Handler select it and click the delete button.

The Action Events tab will open and display the selected event or a New Action Event dialog:

Each Event Handler has the following properties:

  • Name – A unique identifier for each Event Handler.
  • Function – Can either be Custom Code or a .Net Assembly method.
    • Custom Code – To save code directly in Exago, select Custom Code from the first function dropdown. Clicking on the second dropdown opens the custom code menu. See Writing Action Events for information on how to access the arguments for each Event. Press the green check mark to verify the code executes properly.


      Custom Code has four properties:

  • Language – Code can be written in C#, Javascript or VB.NET.
  • References – A semicolon-separated list of any .NET Assembly dlls that need to be referenced by the Event Handler.
    NOTE. System.dll does not need to be listed as a reference as it is already available.
  • Namespaces – A semicolon-separated list of namespaces in the referenced dlls or the Exago API library.
  • Code – The code that will be executed.
  • .NET Assembly Method – To utilize a .NET Assembly method first create a .NET Assembly Data Source. Select the desired assembly from the first Function dropdown. Clicking on the second dropdown will open a list of available methods. See Writing Action Events for information on how to access the arguments for each Event.
    NOTE. The Assembly’s dll will be locked by Exago when it is first accessed. To replace the dll, unlock it by restarting the IIS App pool.
    NOTE. If you want to utilize the sessionInfo object that is passed to all Event Handlers the Assembly must include a reference to WebReportsApi.dll. For more information see SessionInfo.
    NOTE. All methods used as Event Handlers must be static.
  • Event Type – Select an option in this dropdown to create an event that will be executed when certain client-side actions are taken.
    • None – This event handler is a Global Event. You must specify a Global Event Type in the following dropdown.
    • Load – The event handler will execute when a report item is loaded in the Report Designer, Viewer, or (v2016.2.5+) upon Export. This type of handler is typically used to interpret and then apply alterations to report data, e.g. conditionally changing the colors on charts or maps. As of v2016.2.5 Load events can affect Export formats (PDF, Excel, RTF, CSV).
    • Click – The event handler will execute when a user clicks on an item in a report or in the Exago UI. This type of handler is typically used to add additional interactive elements to reports or to the Report Designer. Click events will not function on Export formats.
  • Global Event Type – Select an option in this dropdown to create an event that will be triggered when a condition is met in the Exago application. See Global Events.
    NOTE. Selecting a Global Event Type will cause Exago to ignore any selected Local Event Type.
  • Assigned UI Item(s) – This field designates a comma-separated list of UI item IDs for items in the Exago interface. These elements can be intercepted and modified by assigning them in this field. For a list of compatible UI items, see UI Elements.
    NOTE. This selection field only applies when the Event Type is Click. This field will be ignored when any other options are selected.

Writing Action Events

When an Action Event is fired, two primary parameter objects are passed: sessionInfo and clientInfo. These are the main points of interaction with the Exago application.

  • sessionInfo – Provides access to all the elements of the current Exago session. This is the server-side information. For more information see SessionInfo. The most relevant elements are the following:

    To access the sessionInfo from a .NET Assembly, you must include a reference to WebReportsApi.dll.
    • SetupData – The Admin Console options and data.
    • UserId and CompanyId
    • Report – The current report object.
    • JavascriptAction – This object is set when sessionInfo is called from an action event. It is primarily used to load the client-side Javascript:
      • JavascriptAction.SetJsCode(string JsCode) – Sets the javascript string.
        NOTE. An action event must return the JavascriptAction object.
  • clientInfo – A Javascript object that is called from within the client-side script. Provides access to any specified client-side parameters and information about the item attached to the event handler. For a breakdown of the elements in clientInfo, see ClientInfo.

arguments array – Action events can also access an array of input values called args[]. These parameters can be set manually using a ServerCallback, but a few Global Events pass some preset parameters related to their specific action.

 


Hidden Article Information

Article Author
Alex Agoado
created 2015-12-30 17:44:17 UTC
updated 2017-02-21 16:38:07 UTC

Labels
net assemblies, session info, sessionInfo, actionables, actionable events, local action event, global action event, event handlers,
Have more questions? Submit a request