Work with Show Modes
Show Modes is a feature in Logi applications that allows elements to be shown or hidden. This allows report content and appearance to be changed dynamically. Show Modes can be used to format reports for special purposes and even lead to a reduction in the number of report definitions you need.
- About Show Modes
- Using Built-in Show Modes Values
- Setting the Report-Level Default Show Modes
- Overriding Default Show Modes with Action.Report
- Toggling Show Modes with Action.Show Element
About Show Modes
The Show Modes feature allows developers to control to the visibility of elements. This has many uses, from customizing reports based on individual user needs to changing the look of a report when it's exported. For example, if your report includes an "Export" button or link, you may not want that button or link to appear in the actual exported report. Or you may want to add special page headers to reports exported for printing purposes, but you don't need them when the report is viewed in a browser.
Many elements have a Show Modes attribute and the value of this attribute determines the element's visibility. If the value is left blank, the element will always be visible.
If they have a value, element Show Modes are compared against a list of values assigned to the entire report (also known as the "Report-level"). Elements with matching values are then handled appropriately (shown or not shown) when the report is displayed.
Don't use Show Modes to attempt to secure data. Show Modes controls element visibility by applying CSS at the client, which mean "hidden" information may actually be in the page's HTML source and available to anyone who looks for it.
Standardized built-in Show Modes values are automatically included and available at the Report-level. Developers can also provide their own custom values at the Report-level and work with them to handle circumstances not covered by the built-in values. Let's take a look at how Show Modes works.
Show Modes in Action
A custom Show Modes value can be any arbitrary string you choose. For example, "Show Documents" or "ExportMode"; anything that makes sense in the circumstances. These values can be defined at the Report-level in several ways, which are discussed separately in later sections.
When selecting a Show Modes value, keep in mind that embedded spaces are allowed and that the comparison between element Show Modes values and Report-level values is case-sensitive, so capitalization matters.
The example above presents Show Modes in action. Assuming that the first Division has no value in its Show Modes attribute, it and its contents will always be visible. But the second Division, which may display sensitive information, has a Show Modes attribute value of ShowHROnly. Therefore it will only be visible when ShowHROnly has been assigned as a Show Modes value at the Report-level.
Setting or removing this Report-level value dynamically at runtime will make the column appear or disappear. Tokens can be used to provide Show Modes attribute values, for both individual elements and at the Report-level, with one exception.
Additional flexibility is also available: multiple values can be entered in a Show Modes attribute, separated by commas. Matching any one of them with another Show Modes value will cause an element to be visible.
Show Modes vs. Conditions
Logi Info also includes another mechanism for conditionally showing or hiding elements: the Condition attribute. Many elements have this attribute and the way it works is that if the attribute value, which is typically an expression, evaluates to True or blank, the element is visible. If it's False, the element is hidden.
When should you use Show Modes and when should you use Conditions? Here are some factors to consider:
- Some elements have a Show Modes attribute but not a Condition attribute, and vice versa, so your choice will be dictated by the availability of the attributes. Some elements have both.
- For export purposes, the built-in Show Modes values for exports clearly offer the easiest configuration.
- Show Modes is a client-side effect that uses CSS to hide elements. Conditions, on the other hand, are applied at the server; elements hidden using Conditions are not rendered at all and do not appear in the page HTML. So the results of Show Modes are less secure but do not require a return trip to the server to change the page, while Conditions are more secure but their changes require a full or partial refresh of the page from the server.
- Expressions used with Conditions can include scripting functions so they make certain types of comparisons possible, especially those involving math and dates, and they generally use some kind of Data, Request, or Session token. Show Modes, on the other hand, use literal string values, don't generally use tokens, and provide fast string comparisons from a list.
- If you're using Show Modes in a definition with a "super-element", such as the Analysis Grid or Dimension Grid, you must exercise caution to treat the super-element in an independent manner. Super-elements include their own internal Show Modes that may interfere with, or be interfered with by, Show Modes on the report page. If possible, use Conditions when working with super-elements, instead of Show Modes.
- To show and hide Data Table Column elements, we recommend that you use Condition attributes, not Show Modes. In Logi Info v12.1+, Data Table Column elements no longer have a Show Modes attribute, though you may encounter it in earlier versions.
You can find out more about Conditions in Work with Conditions.
Built-in values provide the easiest method of working with Show Modes. They work like switches, automatically including or excluding elements from appearing under certain standard situations. These values are:
|All||Element will always be visible|
|None||Element will never be visible|
|rdBrowser||Element will only be visible when report is viewed in a browser|
|rdExport||Element will only be visible when report is exported|
|rdExportCsv||Element will only be included when report data is exported to a CSV file|
|rdExportExcel||Element will only be included when report is exported to an Excel worksheet|
|rdExportPdf||Element will only be included when report is exported as a PDF|
|rdExportWord||Element will only be included when report is exported to a Word document|
When one of these built-in values is used, developers do not need to set a corresponding value at the Report-level. When a specific action occurs, like an export, the application will compare these values to internal system values to determine what action to take.
The built-in values are available for selection from a drop-down list in the Show Modes attribute value field, in the Attributes panel, as shown above. Here's an example of one of them in use:
In the example above, in the main content we provide a button that lets the user export the report to PDF. However, we don't want to include the page header and footer in the PDF. By setting the Report Header and Report Footer elements' Show Modes attributes to the standard rdBrowser value, we ensure that they will only appear when the report is browsed, but not when it's exported to PDF.
When using custom Show Modes values, the most direct way to implement it at the report-level is to set the report's Default Show Modes attribute.
As shown above, the root element of a report definition has a Default Show Modes attribute. A string literal entered in this attribute's value will affect the rest of the report (as a "Report-level" value). Going back to our earlier example with the three data table columns, entering the "NotHRStaff" value here will ensure that the "colSalary" element will be invisible by default, because the Report-level Show Modes value and the element Show Modes value do not match.
Now suppose we want to alter the Show Modes (and column visibility) dynamically. We can do that with a special query string variable named "rdShowModes". For example, if the URL for this report includes rdShowModes=ShowHROnly this will override the Default Show Modes attribute's value and in our earlier example colSalary will become visible. So, by altering the query string, parts of this report can be made visible on the fly.
In the previous section we learned that use of the rdShowModes query string variable will override a report's Default Show Modes setting. The query string variable can be included when calling a report by using a number of methods, including Link Parameters. One of the easiest methods is available when using Action.Report and Target.Report elements to call the next report.
The example above shows a simple Label element, used as a link, with Action.Report and Target.Report elements beneath it. If the Target.Report element's Report Show Modes attribute is given a value, as shown above, that value will be automatically paired with the rdShowModes keyword and placed in the query string of the URL that calls the target report. The resulting URL would look like this:
Great runtime flexibility is possible because the Report Show Modes attribute value can be an @Data, @Request, or other token. Multiple comma-separated values, or tokens, can also be entered.
The following elements also have a Report Show Modes attribute that can be used in the same way:
- Action.Refresh Element
You may have a need to allow the user, at runtime, to alternately show and hide ("toggle") a report section. Two elements, the Division and Action.Show Element, using Show Modes, make this easy to do.
In the example above, a Label element has been placed in a report to be the link for showing and hiding instructions, which are in their own Division. The Division element's Show Modes attribute is set to an arbitrary value, XYZ, which causes it to be hidden initially.
An Action.Show Element element has been added beneath the link Label and its attributes configured as shown above. Clicking the link will now result in the Show Modes of the Division element being manipulated, "toggling" it between being shown and being hidden.