Inserting HTML Into Reports

Inserting HTML Into Reports

Logi Info
v12.6 - Oct 2018

The Logi Server Engine generates HTML and JavaScript when it processes a Logi definition, but you may find that you need to insert your own HTML code directly into a Logi report. Several elements are available to accomplish this and they're discussed in this document. Topics include:

 

About Inserting HTML

The "source code" of a Logi definition is an XML document, which is processed by the Logi Server Engine, and output as HTML. However, you may want to insert your own HTML code directly into a Logi report. There are many reasons for wanting to do this, including adding <META> information, adding <SCRIPT> content, and embedding external HTML documents into your report page.

For example, the document you're reading right now is actually a separate, external HTML file that has been embedded into the DevNet site page.
 

Requirements

HTML that's included into a Logi definition must be have properly-formed tag structures, and include all closing tags. For example,

    <p><strong>My Title</strong></p>

If a complete HTML page is embedded, it may include <HTML> and <BODY> tags, but they aren't required.

  Back to the top

 

Using the HTML Tag Element

The HTML Tag element enables you to easily insert custom HTML into your definition. One popular usage is to add <UL> and <LI> tags, which are commonly used by libraries like JQuery to build a unique UI.
 

Attributes

The HTML Tag element has the following attributes. Tokens are supported in all attribute values.
 

Attribute Description

Html Tag Name

(Required) Specfies the HTML tag to be inserted, such as OL or LI or SPAN. Opening and closing tags will be inserted.

Class

Specifies the CSS class to be used by the element.

Condition

Specifies an expression that evaluates to a value of True or False. If True, then the HTML is generated, otherwise it's not. Expressions should be in JavaScript or intrinsic function syntax.

Html Tag Text

Specifies the text content that will be included between the tags. For example, if Html Tag Name = SPAN and Html Tag Text = My dog has fleas, the resulting output is: <SPAN>My dog has fleas</SPAN>.

ID

Specifies a unique identifier for this element.

Security Right ID

When using Logi Security, specifies one or more Security Right IDs, separated by commas. Users with these Security Right IDs will be able to view the HTML tag, users without them will not.


Here's a usage example:
 

As shown above, you can create hierarchies of nested HTML Tag elements, allowing us to create an un-ordered list (ol) with several list items (li). Notice the Html Attribute Params child element being used - it allows you to supply additional attributes (shown highlighted below) for an HTML tag.

The HTML generated by the example looks like this:
 

<ol>
  <li title="my title" id="li_Coffee">Coffee</li>
  <li id="li_Soda">Soda</li>
  <li id="li_Water">Water</li>
</ol>


Also notice that the HTML is not wrapped in <SPAN> tags.

The Conditional Class element is available as a child of HTML Tag, allowing conditional setting of style classes.

The Event Handler element is available as a child of HTML Tag:

 

You can use the Event Handler as a child of HTML Tag to trigger actions related to HTML objects. In the example above, the HTML Tag element has been used to create two radiobuttons that, unlike the Input Radio Buttons element, don't require a datalayer. When the buttons are clicked, the report is redisplayed. As in the case of a typical User Input element, the selected value is passed along as a Request variable that uses the HTM Attribute Params "name" and "value".

  Back to the top

 

Using the Include HTML Element

The Include HTML element allows you to insert HTML at selected points within your report definition.

This element can be placed in your definition as the child of a number of elements, such as Report Header, Body, Division, Data Table Column, Report Footer, and others. See the Element Reference entry for this element for a complete list.

In the past, developers have used a Label element, set to HTML format, for this purpose. However, feedback from developers indicated that this was a somewhat obscure usage, so the Include HTML element is now recommended for this purpose instead.

 


     

A simple example is shown above and the resulting HTML output looks like this:
 

<!DOCTYPE HTML>
<HTML xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:rdXslExtension="urn:rdXslExtension">
<HEAD>
(... various standard tags not shown for clarity )
</HEAD>
<BODY onload="rdBodyLoad()">
(... various standard tags not shown for clarity )
<div id="rdMainBody">
<SPAN><p>Here's my HTML</p></SPAN>
</div>
(... various standard tags not shown for clarity )
</BODY>
</HTML>


As you can, the HTML from the Include HTML element has been inserted between two <SPAN> tags in the code.

Scripts can be entered here in the same way, using <SCRIPT> tags. If you double-click the HTML attribute name and open the Attribute Zoom window, it's easy to enter multi-line scripts, like the following example:
 

<script type="text/javascript">
  NagMsgTimer = function() {
    setTimeout('ShowNagMsg()', 2*60*1000);  /* delay 2 mins, in milliseconds,  */
  }
  function ShowNagMsg() {
    alert('Register your product now!');
    setTimeout('ShowNagMsg()', 2*60*1000);  /* delay 2 mins, in milliseconds,  */
  }
  /* cause function NagMsgTimer to run when page is loaded */  
  if (window.attachEvent) {   /* IE */
    window.attachEvent('onload', NagMsgTimer); /* event name is case sensitive */
  }
  else {      /* Moz, Netscape, Firefox */
    window.addEventListener('load', NagMsgTimer, false);
  }
</script>


This script will be included in the HTML and, because it attaches itself to the page load event, will begin to execute automatically when the page is loaded. To get the script inserted in the <HEAD> section, see the next part of this document and use the Include HTML File element instead.

  Back to the top

 

Using the Include HTML File Element

The Include HTML File element allows an HTML document to be included within your Logi report definition. HTML files stored in your application's _SupportFiles folder will be available for selection in the element's attributes from a drop-down list.

The Include HTML File element can be placed in your definition beneath a number of elements, such as Report Header, Body, Division, Data Table Column, Report Footer, and others. When it's placed beneath any of these lower level elements, the HTML it references will be inserted between the <BODY> tags of the generated report page.

It can also be a child of the Report (root) element in your definition, which places the HTML between the report page's <HEAD> tags. This can be very useful for including scripts, instructing the browser where to find external style sheets, providing meta information, and more.

See the Element Reference entry for this element for a complete list of parent elements.

 

If your HTML file has been added to the application in the _SupportFiles folder, then, in the Include HTML File element's Filename attribute, you need only specify the actual file name (or select it from the drop-down list), as shown above. Otherwise, you'll need to specify a fully-qualified file path (on the web server), starting with a drive letter and the @Function.AppPhysicalPath~ can be used here for that purpose.

You can place script functions in an HTML file (with the proper <SCRIPT> tags) and use Include HTML File to include them in definitions; this can be useful if you want to include the same script functions in a number of Logi definitions but maintain them all in a single file. Or, you may want to use scripting in this manner to include an external JavaScript library.

    <script type="text/javascript" src="_Scripts/tiny_mce/tiny_mce.js"></script>

For example, the TinyMCE editor used in DevNet's forums is added into DevNet using an Include HTML File element and an HTML file containing the script shown above. 

Here are some key points to remember when working with HTML files with visible content and the Include HTML File element:
 

Caching Confusion

Files embedded with the Include HTML File element are cached at the web server. If you forget about this, it can cause great frustration when you edit the HTML content in your file and then it doesn't appear to change in the report page! To abandon the cached content, you will need to delete the value in the Filename attribute, save and browse the page again, then re-enter the filename and continue testing. Or, if it doesn't affect anyone else, you can reset the web server.
 

Width Coordination

When embedding your HTML file in a report definition that you must pay close attention to widths. Possible parent elements, such as Column and Data Table Column, need to be wide enough to accommodate your HTML file; conversely, your HTML file may need to constrain its own width to fit inside the Logi report page. Coordination of widths is essential for a good result.
 

No Scrolling

A file displayed using the Include HTML File element will be shown in its entirety; its full length will be displayed, "pushing" anything below it down the page. There is no option to show a portion of it within a scrolling window. (To create a scrolling area for HTML content within a report, you need to use the Sub-Report element).
 

Style sheet Interaction

The effects of style classes referenced in your embedded HTML document will be combined with those of the Logi report page containing the document. They will interact and this can have unexpected consequences as different classes vie for precedence. There is no hard-and-fast rule to follow concerning the use of style in this situation, but be prepared for the possibility that a little experimentation may be necessary to get things looking right.

  Back to the top

 

Using the Meta Names Element

The HTML <META> tag provides metadata about a Logi report. Metadata is not displayed on the page, but is "machine parsable" and is typically used to specify page description, keywords, modification dates, and other details. The <META> tag always goes between the <HEAD> tags and can be used by browsers (to tell them how to display content or to reload page), search engines (keywords), and other web services.

Logi products provide the Meta Names element, which allows developers to set some of the more common <META> tag variations directly, without the use of an external HTML file and the Include HTML File element. The Meta Names element is child of the report's root element.
 

The example above shows a Meta Names element with every one of its attributes configured (they're all optional),
 

<META name="Description" content="Great document about including HTML" />
<META name="Generator" content="LogiInfo" />
<META name="Keywords" content="Logi Analytics, HTML, Reports" />
<META name="Robots" content="noindex" />
<META http-equiv="refresh" content="60" />


and the resulting <META> tag that each attribute generates in the report page are shown above. The element's attributes are described below:
 

Attribute Description

Meta Description

Specifies a description of the web page. Some search engines use this to provide the user with a document summary in the result of a search.

Meta Generator

Specifies the name of the application used to create the document. The default value is LGXReporting.

Meta Keywords

Specifies a comma-separated list of words that describe the document. Some search engines use this for keyword searches.

Meta Robots

Specifies whether the containing document should be indexed by search engines

Refresh

Specifies an interval, in seconds, for periodically refreshing the report.

 

  Back to the top

 

Inserting <Meta> and Other Tags Using JavaScript

The Meta Names element discussed in the previous section provides one method of inserting common <META> tags into your report, but if you want to insert other tags, you can do so using JavaScript. Suppose, for example, that you want to insert a tag that specifies a character set, like this one:

    <META charset="UTF-8">

To do this, you can use either an Include Script element, beneath the Report Header element, or an Include Script File element, beneath the definition's Report root element, to include the following JavaScript:
 

var headTag = document.getElementsByTagName('HEAD')[0];
var charsetTag = document.createElement('META');
charsetTag.setAttribute("charset", "utf-8");
headTag.appendChild(charsetTag);


This will add the desired <META> tag to the code between the <HEAD> tags in the generated HTML page.

Here's another example: suppose that you want to insert a tag that controls Internet Explorer compatibility settings, like this one:

    <META http-equiv="X-UA-Compatible" content="IE=EmulateIE7">

But, to be effective, this needs to be the first tag in the <HEAD> section. The following code allows you to create this arrangement:
 

var headTag = document.getElementsByTagName('HEAD')[0];
var emulationTag = document.createElement('META');
emulationTag.setAttribute("http-equiv", "X-UA-Compatible");
emulationTag.setAttribute("content", "IE=EmulateIE7");
// next line ensures insert is first element under <HEAD> tag
headTag.insertBefore(emulationTag, headTag.firstChild);


And, for completeness sake, here's code that demonstrates use of a custom "insertAfter" function, should you need to do that. This code inserts the <META> tag from the previous example into the <HEAD> section, after the <TITLE> tag:
 

// create a custom function, which takes two parameters:
function insertAfter(newElement,targetElement) {
   // target is what you want it to go after, look for this element's parent
   var parent = targetElement.parentNode;
   // if the parent's lastchild is the targetElement...
   if(parent.lastchild == targetElement) {
     // add the newElement after the target element
     parent.appendChild(newElement);
   } else {
     // target has siblings, insert new element between the target and it's next sibling
     parent.insertBefore(newElement, targetElement.nextSibling);
   }
}

var titleTag = document.getElementsByTagName('TITLE')[0];
var emulationTag = document.createElement('META');
emulationTag.setAttribute("http-equiv", "X-UA-Compatible");
emulationTag.setAttribute("content", "IE=EmulateIE7");
// call the custom function to do the insert
insertAfter(emulationTag, titleTag);

 


JavaScript can be used, with the Document Object Model, to manipulate the final HTML page in many ways that are otherwise unavailable through elements.

  Back to the top

 

Using The Label Element with HTML Format

The Label element can be used to insert HTML into your report. This is done by setting its Format attribute to HTML and entering the desired HTML code in its Caption attribute.

Because the code is embedded within an existing HTML page when the report is generated, you do not need to include <HTML> or <BODY> tags in the Caption.

Any valid HTML can be entered in the Caption and this is often a simple way to add Bold or Italic effects to text without the need for a style class. The HTML must be "well-formed"; that is, you need to ensure that you have entered all of the matching opening and closing HTML tags required.

For example, have you ever needed to call a Logi report and then automatically scroll to some specific location within it? In HTML, this is done using an Anchor tag (<A>) with a named bookmark in the destination page. Here's how to do it using a Label element:
 


     

  1. In the destination report, use a Label element to create an HTML bookmark, as shown above. The Label element won't be visible, so include it in the appropriate location in your report (the location that the browser will scroll to when the report is displayed). Set its Format attribute to HTML and, in its Caption attribute, enter the HTML code for an anchor, with the anchor name ("Security" in the example).

 


     

  1. In the calling report, in the Target.Report element used to identify the destination Logi report, add a hash mark (#) and the anchor name after the report definition name, as shown above.

Now, when the link, image, etc. that calls the report definition is clicked, the browser will scroll to bring the Label element from Step 1 into view. The URL generated looks like this:

    http://myServer/myLogiApp/rdPage.aspx?rdReport=newReport3#Security

Note that, for the anchor to work correctly, it has to be the very last thing in the query string. This means, for example, that you cannot use this technique with Link Parameters or the Wait Page element, as they will add items to the query string after the anchor name.

  Back to the top

 

Using the Label Element's HTML Tag Attribute

The Label element's HTML Tag attribute allows you to control which HTML tag set will surround the label text.

The default is a <SPAN> tag set and the resulting HTML output looks like this:  <SPAN>Here comes the sun</SPAN>

However, the new attribute allows you to specify a range of other options:

 

A selection of commonly-used tags is available from a pull-down list, as shown in the example above.

 

You can also type in other values. HTML5, for example, supports a number of semantic tags including <article>, <figure>, and <details>, and you can type any of these directly into the attribute value (without brackets) to use a tag set not found in the pull-down list.

  Back to the top

 

Invalid XHTML Characters

The Logi Server Engine may generate errors if it needs to read a string of characters as XML and that XML includes un-escaped, invalid XHTML characters.

A primary examples of this is when AJAX-style requests are used, such as data table sorting or paging (when Ajax Paging = True has been set), or use of an Action.Refresh Element that includes a data table or other data object. In these cases, the XML data may be indistinguishable from XML tags and reserved characters.

This can also happen when HTML is included in a report definition using the techniques discussed earlier.

The most common culprit in this scenario is the inclusion of unencoded "&" characters. In situations like those described above, the application will fail and produce an error message that looks like a parsing error.

Replacing the "&" character with "&amp;" is often an easy solution.

  Back to the top

 


© Copyright 2007-2019 Logi Analytics, Inc. All Rights Reserved