Custom (non-Exago) links can be added to the Report Tree in the user interface. This is an opportunity to provide a smooth transition from another reporting system.
Non-Exago content will not be executed by the Exago execution engine.
This feature allows custom items to be added to the Report Tree including interactivity with those custom items.
The Report Tree should contain no more than 1,000 items in it for best user experience.
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. Developers will be required to familiarize themselves with Action Events and Server Events.
The general procedure for adding external content to the report tree is outlined below. Examples of implementations of each Server and Action Event are included as starting points.
- Implement the OnAfterLoadReportsList Global Server Event
- Implement the OnSelectReport Global Action Event
- Implement the OnDoubleClickReport Global Action Event
- Optional: implement the remaining user interface Global Action Events if needed.
Implementing step 1 is required to place the custom items into the Report Tree. Implementing steps 2 and 3 is required because without them, a warning error message will display to the user that the Action Event has not been implemented. The remaining Action Events in Step 4 are optional.
This server event requires importing the
WebReports.dll library in addition to the usual
WebReportsApi.dll, because the former contains the definitions of
TreeNodeCollection, as well as
CustomTreeNode which are used to differentiate custom nodes.
This event is called after reports have been loaded in the report tree and before the tree is drawn for the user. A WebReports.UI.Controls.TreeNodeCollection object is passed in as an argument. The collection contains WebReports.UI.Controls.TreeNode objects, one for each report or folder in the tree.
The following example demonstrates how to add three new nodes to the Report Tree with the OnAfterLoadReportsList Server Event with the Admin Console.
//Get the tree object from the arguments array. TreeNodeCollection tree = (TreeNodeCollection)args; //Add a new folder named "Custom Items" to contain our new custom items
//and then add it to the tree. TreeNode folder = new CustomTreeFolder("Custom Items"); tree.Add(folder); //Add a new custom item to the folder, with the name My Test Item 0 //passed into the constructor of the item. Use the icon TreeNode item0 = new CustomTreeNode("My Test Item 0"); item0.ImageName = "TreeActiveRole.png"; folder.Nodes.Add(item0); //Add a new custom item to the folder, with the name My Test Item 1 //passed as the Text property of the item TreeNode item1 = new CustomTreeNode(); item1.Text = "My Test Item 1"; item1.ImageName = "DropDownArrow.png"; folder.Nodes.Add(item1); //Add a new custom item to the folder, with the name My Test Item 2 TreeNode item2 = new CustomTreeNode("My Test Item 2"); item2.ImageName = "TreeActiveRole.png"; folder.Nodes.Add(item2); return null;
Report Tree Icons
This article references
<WebApp>/as a placeholder for the Web Application's install location. The default install location is
/opt/Exago/on Linux); however, these directories can be changed during installation.
The image files referenced by
item2.ImageName above belong to the currently active Application Theme. The Basic Application Theme icons included at installation can be found in
<WebApp>/ApplicationThemes/Basic/Images/. For more information, refer to the Application Themes article. Images are available in both PNG and SVG format.
When choosing or generating images to display in the tree, we recommend selecting one that has a matching
<filename>Selected.png partner. For example,
Edit.png has a matching
EditSelected.png. When the custom item is selected in the Report Tree, Exago will automatically substitute <fileName>Selected for the original <fileName>. If the image selected has no matching <fileName>Selected, then a broken image placeholder will be displayed in the user interface instead.
|Unselected Icon||Filename||Selected Icon||Filename|
Now that the Server Event is impleted, the custom items will appear in the user interface. However, without implementing the Action Events, users cannot interact with them. In fact, wihtout implementing at least OnSelectReport and OnDoubleClickReport, users will be presented a warning message:
To add interactivity and prevent the warning message, implement the Action Events as outlined in the following section.
These events require some unique handling when compared to other Action Events, as they require a boolean return value or the Promise of a boolean value. 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 a custom Report Tree item, it might be desirable to launch an external editor instead of the Exago Report Designer. In an Action Event, check the report type, and if it is a third party report, insert the custom action then return True. If it is a regular Exago report, continue with the normal course of action by returning False.
The examples that follow have been formatted as anonymous functions so that they may be copied directly into the Admin Console. For more information, refer to the Action Events article.
The following is an example how an Action Event with Global Event Type OnSelectReport can be used to allow standard Exago behavior when a user clicks on an Exago report, but to prevent the same when clicking on a custom item.
|Global Event Type||OnSelectReport|
For additional information, refer to the Global Action Events article.
The following is an example how an Action Event with Global Event Type OnDoubleClickReport can be used to detect whether the selected object is a custom node and launch a specific handler. The example makes use of the
LoadUrlToNewTab() method in ClientInfo in order to load a new user interface tab with the content.
|Global Event Type||OnDoubleClickReport|
For more information, refer to the Global Action Events article.
4. Optional Action Events
The remaining Global Action Events are not required to permit basic interactivity with the Report Tree and custom items. Their implementation would be similar in fashion to the above examples, depending on use case.