Scroll

Managing Third Party Reports in the Exago UI

The v2016.3 release of Exago comes with the ability to manage the view and execution of third-party (non-Exago) files from within the user interface. This is an opportunity to provide a smooth transition from other report software.

Because we intend to provide a generic solution for a variety of use cases, and because third party reports do not follow any similar standards, this functionality must be implemented on a case-by-case basis. Solutions are code-based. Implementers will be required to familiarize themselves with the Action Event and Server Event extensibility features of Exago.

Implementing External Reports

This feature allows for the Main Menu of Exago, i.e. the reports and folders tree, to have extensive additions in functionality.

To this end, one new server event, and several new action events have been provided. In brief, server events and action events are optional external calls that can be added to Exago whenever certain specific actions are taken in the application. In the following section, we'll briefly discuss the events which can be used to manage the report tree.

Suggested Events

Server Events

OnAfterLoadReportsList

This event is called after reports have been loaded in the report tree, and before the tree is drawn for the user. This is how to add or manage items in the report tree. The event provides a TreeNodeCollection object, which is a list of TreeNode objects each of which is a node (report or folder) in the report tree.

This server event requires importing the WebReports.dll library in addition to the usual WebReportsApi.dll, because the former contains the definitions for TreeNode and TreeNodeCollection, as well as CustomTreeNode and CustomTreeFolder classes which are used to easily differentiate custom nodes.

The following is an example for how you might implement the server event in order to add some new nodes to the tree (for more information, see Server Events).

public class ServerEvent
{
	public static object LoadCustomReportsListItems(SessionInfo sessionInfo, TreeNodeCollection tree)
	{         
		TreeNode folder = new CustomTreeFolder("Custom Items");
		tree.Add(folder);

		TreeNode item0 = new CustomTreeNode("My Test Item 0");
		item0.ImageName = "TreeActiveRole.png";
		folder.Nodes.Add(item0);

		TreeNode item1 = new CustomTreeNode();
		// Example of creating the node and assigning the Text later
		item1.Text = "My Test Item 1";
		item1.ImageName = "Template.png";
		folder.Nodes.Add(item1);
TreeNode item2 = new CustomTreeNode("My Test Item 2"); item2.ImageName = "TreeActiveRole.png"; folder.Nodes.Add(item2); return null; } }

Action Events

Action events function on a client- and server- level, rather than just the server. Interface items can be manipulated using client-side javascript.

We provide the following global action events in order to extend the report tree functionality:

OnEditReport, OnSelectReport, OnDeleteReport, OnRenameReport, OnExecuteReport, OnDoubleClickReport, OnRightClickReport

Each of these events passes a webReportsCtrl javascript object, which contains the full application DOM, in addition to the usual clientInfo methods. These events require some unique handling, when compared to other action events. These events require a true or false return value in the client script. True indicates to Exago that we don't want to continue with the "normal" course of action, which we have replaced with our custom code. False indicates that we should continue with the normal action.

For example, when double-clicking on a third party (non-Exago) report, we may want to launch an external editor instead of the Exago report designer. We would check the report type, and if it is a third party report, we would insert our callout and then return True. If it is a regular Exago report, we would continue with the normal course of action by returning False.

Also note that for these events to be able to have a return value, they must be enclosed within a javascript function. This means that if you want to write the full client scripts in the admin console (rather than calling out to a separate function) each event will need to be wrapped in an auto-executing anonymous function, like so:

string jsCode = @"(function()
	{
		/* javascript stuff; */
		return true;
	}())";

sessionInfo.JavascriptAction.SetJsCode(jsCode);
return sessionInfo.JavascriptAction;

The following is an example for how you might implement an action event to detect whether a selected object is a Custom node and launch a specific handler (for more information, see Action Events). Note that this example makes use of the LoadUrlToNewTab convenience method in ClientInfo in order to load new tabs with selected content.

public static object LaunchCustomReportsListItem(SessionInfo sessionInfo)
{
	string jsCode = @"
	function ShowReportsListItem(clientInfo) {
	// Based on the node that was selected, determine if it was added as a custom node
	// via a server event or not; if so, open a new tab and display contents;
	// otherwise, display the Exago report
	var node = clientInfo.utilities.TreeCtrl.GetSelectedNode(clientInfo.webReportsCtrl.reportsTreeId);
	if (node == null) // The user may have right-clicked on a non-node before a node was selected
		return;
	if (clientInfo.webReportsCtrl.ReportFoldersCtrl.IsCustom(node))
	{
		var reportName = clientInfo.utilities.GetText(node);
		switch (reportName)
		{
		 case "My Test Item 0":
		  clientInfo.LoadUrlToNewTab("http://localhost/handler0.aspx");
		  break;
		 case "My Test Item 1":
		  clientInfo.LoadUrlToNewTab("http://localhost/handler1.aspx");
		  break;
		 default:
		  clientInfo.LoadUrlToNewTab("http://localhost/default.aspx");
		  break;
		}
		return true; // indicates that we're done processing select event
	}
	else
		return false; // indicates that we should continue processing select event normally
	}";

	// Register the Javascript code with the session action; also
	// this is where we inject the c# value into the Javascript script
	sessionInfo.JavascriptAction.SetJsCode(jsCode);
	return sessionInfo.JavascriptAction;
}

Additional Info

For more information, you can download and examine this reference example. Please note that this example will not work out-of-the-box, and should not be used in a production environment.


Hidden Article Information

Article Author
Exago Development
created 2016-12-02 18:41:05 UTC
updated 2017-06-08 13:31:02 UTC

Labels
Server Events, sessionInfo, global action event, Action Events, migrating, migration, transition, transitioning,
Have more questions? Submit a request