SubReports

Logi developers often find a need to include other reports in their Logi reports, either as readily visible parts of the page or as hidden areas that are displayed on demand. This topic discusses use of the SubReport element to achieve this.

• About SubReports
• Use Embedded Mode
• Use IncludeFrame Mode
• Use IncludeFrameAsynch Mode
• Use a SubReport with More Info Row

About SubReports

A "subreport" in Logi parlance is an HTML page that is displayed inside a Logi report page. One method of doing is this by using the SubReport element, which identifies the report to be included (either a Logi report, or an internal or external HTML page).

Other available methods, which are not discussed here, include use of the Include Html File element (see Insert HTML Into Reports) and our JavaScript-based Embedded Reports API. For non-hierarchical tabular data, a subreport with a Data Table is recommended instead of using a Subdata Table.

Let's look at two examples of the SubReport element in action:

In the example shown above, the subreport is the shaded area inside the dotted lines, embedded into the DevNet Logi report page. The Support Plan Portal content is actually part of a service provided by a third-party vendor and, by using a SubReport element, we can embed their web pages, forms, and reports right into a DevNet page. To access their web site, an absolute URL ("http://www.support.com/...") is used. This technique allows us to maintain a consistent "look and feel" for the DevNet page while taking advantage of external web-based applications and services.

In the next example, shown above, an Analysis Grid super-element uses a child More Info Row element (see Data Table Rows) to display detail data. Clicking the Order ID data causes a subreport, shown in the shaded area within the dotted lines, to be displayed beneath the clicked row. The subreport consists of a separate Logi report definition that contains only a data table. This technique is useful because it allows the subreport definition to be independently developed and tested, and then integrated into the Analysis Grid report definition.

As we've seen, the SubReport element is capable of including a subreport that's either a separate HTML page from the same or another web site, or another Logi report definition. The functionality of any pages included is preserved, so data entry, links, video, etc. are all active.

Several subreport modes are used for including files: Embedded,IncludeFrame, and IncludeFrameAsynch. These are described in the following sections.

Use Embedded Mode

When the SubReport element's SubReport Mode attribute is set to Embedded, the subreport must be a Logi report definition.

As shown above, the SubReport element is added and its SubReport Mode attribute value is Embedded. With this mode setting, the attributes with an "X" next to them are ignored and a Target.Report child element must be used to specify the Logi report definition to be embedded.

When the Logi Engine renders the page, it will render the embedded report first and then merge its HTML code right into the code for the main report, surrounding it with DIV tags. The resulting page looks like the example above.

 Note these important restrictions when using this mode:

• Do not embed report definitions containing super-elements, such as the Analysis Grid, using this mode. Internal component naming and session variable conflicts will arise and the super-element will not work correctly.
• Do not embed report definitions that use the Wait Panel/Wait Page using this mode.
• Any Sort elements used beneath individual data table columns and Interactive Paging elements in the subreport definition will be ignored and will not be rendered.
• Drilling down using subreports in this mode is limited to two levels. In other words, you cannot drill down through one report to a subreport, which itself embeds another subreport, then drill down again using links in the second embedded subreport. Those links will not work correctly.

Use IncludeFrame Mode

When the SubReport element's SubReport Mode attribute is set to IncludeFrame, the subreport may be a Logi report definition or an external HTML page. When the Logi Engine renders the main report, it will include IFRAME tags referencing the subreport. The subreport then runs in its own little "window" (which is an isolated, separate environment) in the main report page. Super-elements, such as the Analysis Grid, will operate correctly when included using this mode.

 Note that creators of external content may choose to prevent you from embedding their pages in an iFrame by using the X-Frame-Options header in their HTTP Responses. Browsers typically respond to this by displaying either a message indicating that embedding is not allowed or by displaying nothing. If necessary, you can use online or browser tools (often F12) to view the HTTP headers and confirm the presence of X-Frame-Options. There is little you can do to overcome this restriction.

As shown above, the SubReport element's other attributes are now usable and can be configured to constrain the subreport to a specific size, to add scrollbars, or to draw a border around the subreport. If the Height and Width attributes are left blank, the window will be automatically sized to include the entire subreport page.

In the example shown above, the subreport is displayed in a bordered window inside the main report, restricted to a specific size, and with its own scrollbar.

If, instead of a Target.Report element, we use a Target.Include Frame Link, we can enter an actual URL and include a page from an internal or external web site.

And here we see the Microsoft.com home page displayed as a subreport. Note that you must always start the URL attribute value with "http://" to ensure that the Logi Engine recognizes it as a URL.

Style Considerations

The style of your subreport may be affected by the style of your main report. Generally, IncludeFrame mode helps isolate the subreport from the main report's style, but you may need to work with your style sheets to iron out occasional conflicts.

Use IncludeFrameAsynch Mode

This SubReport Mode option, added in v11.0.127, is similar to IncludeFrame mode, except each request to the web server will be processed in its own thread. This may provide improved performance, for example when SubReports are used in multiple dashboard panels, with the caveat that session variables cannot be saved for SubReports run in this mode.

Use a SubReport with More Info Row

We've seen the elements and attributes used to place a subreport in the body of a main report, and now let's see how we can use a subreport to display information on demand, specifically when using a More Info Row element with an Analysis Grid. For more information on the More Info Row, see Data Table Rows.

The example above shows an Analysis Grid (AG) and its columns (some of which are represented here by an ellipsis "..." to save space). A More Info Row element has been added beneath the AG, and configured as shown, above right, to span all of the AG columns and to be hidden, using Show Modes, by default.

Next we need to add the trigger that will display and hide the More Info Row, by placing an Action.Show Element element beneath the Label element in the AG's first column, and configuring its attributes as shown. Note that its Element ID attribute value matches the element ID given to the More Info Row element. With this in place, clicking the data value in the first AG column will cause the More Info Row to appear and disappear. Now let's create the subreport:

In a new definition, the subreport content is created. As you can see in the example above, it does not need Report Header or Report Footer elements, and may not need a Style element. It uses a Data Table and has its own datalayer and some kind of filter element that restricts the data to a unique identifier that will be passed to the report as a Request variable. Or, if using DataLayer.SQL, the query's SELECT statement could use the Request variable in its WHERE clause, and a filter element would not be necessary.

The subreport can be tested independently of the rest of the application, by passing it test Request variables, to ensure that it's retrieving the correct data and displaying it properly. Now we're ready to put the subreport into the main report:

As shown above, a SubReport element is added beneath the More Info Row element. Beneath it, Target.Report, and Link Parameters elements are added. Their attributes are configured as shown. Note that the SubReport and Target.Report elements have slightly different internal names, which appear at the top of the Attributes panel. The target report is, of course, the subreport definition that we created in previous step, and the parameter passed is the unique identifying value that the subreport is expecting.

And, the resulting Analysis Grid should look like the one shown above, when an Order ID column value is clicked.

Performance Note: When the Logi Engine renders a report with a More Info Row, it runs the subreport datalayer for each row of the AG, which could result in slow performance. If this is problematic, you may be able to avoid it: the Target.Report element has a Link Data Layers attribute which, when set, will cause the AG's datalayer cached data to be used for the subreport. The subreport then uses a DataLayer.Linked element to access the data.

When a SubReport in Embedded mode is used beneath a More Info Row, any Sort elements used beneath individual data table columns and Interactive Paging elements in the subreport definition will be ignored and will not be rendered.

There are a lot of ways subreports can be used, and the Action.Show Element element can be used to make them appear/disappear in a variety of places in a report, not just within a More Info Row.