Embedding KeyReporter

KeyReporter pages can be embedded in external web pages using an Inline Frame, or “iframe”. This allows you to wrap KeyReporter content within a page design that is consistent with your organization's web site. Navigation within the embedded frame will remain on the KeyReporter pages, while navigation outside the frame is controlled by the embedding page.

It is also possible to embed individual Dashboard widgets on an external web page. Because Dashboard widgets are not stand-alone pages within KeyReporter the mechanism for embedding them is slightly different. Furthermore, each embedded widget requires certain parameters in order to control display and behavior.

Embedding with page titles

In KeyReporter, each page has a navigation bar at the top, a page title, content, and a footer. When embedding a KeyReporter page the navigation bar and footer will be removed, while the page title and content are displayed. The pictures below show what this looks like where two of the Availability Maps pages have been embedded in an mocked-up external page (click to enlarge):

    

To embed a KeyReporter page you add an iframe to your external web site page using HTML markup like this:

<iframe src="//keyserver.sample.net/frame-body/public/maps.html" seamless="seamless" height="500px" width="100%" frameborder="0" > </iframe>

You can use any iframe attributes and style that you need, but three attributes are important to understand. The seamless="seamless" attribute makes the frame look more like part of the page, and is generally recommended. The height="500px" attribute can have any value, but should be large enough to accomodate the KeyReporter content. If the content does not fit in the iframe height, the browser will show a scroll bar. It is also possible to use JavaScript to size the iframe dynamically depending on the browser window size. Any such JavaScript would exist in the embedding page, and is left up to you to implement.

The third and most important attribute is the URL of the KeyReporter page you want to embed. For example, let's say you want to embed the Availability Maps main (list) page, That page has a URL similar to:

//keyserver.sample.net/public/maps.html

To embed this page without the KeyReporter navigation bar and footer you would need to add /frame-body to this URL, as shown in bold here:.

//keyserver.sample.net/frame-body/public/maps.html

This pattern can be applied to any KeyReporter page, and that page's title and content will appear within the iframe on your external page.

Embedding with page content only

In some cases you might want to show only the KeyReporter page content without the title. Note that on many KeyReporter pages the title area will also contain some important sub-navigation and other controls. For example, the Availability Maps pages have a Refresh button in the title area. Any such controls will not be included when the page title is omitted. The pictures below show what this looks like where two of the Availability Maps pages have been embedded in an mocked-up external page (click to enlarge):

    

To embed this page with only the KeyReporter page content you would need to add /frame-core to the URL, as shown in bold here:.

//keyserver.sample.net/frame-core/public/maps.html

This pattern can be applied to any KeyReporter page, and that page's content will appear within the iframe on your external page.

Tips on the src attribute

In the examples above you might have noticed we left out the “scheme” — the http: or https: — in the iframe src attribute URLs. When the scheme is not present in a URL, the browser will use the scheme of the page containing that URL. So if your external page is accessed using http:, the embedded KeyReporter page wil also be accessed using http:. Normally it is good practice to leave out the scheme so that the embedding and embedded pages are accessed in a consistent manner. However, sometimes this is not desireable. For instance, if you only run KeyReporter on HTTPS, but your external pages can be accessed over HTTP, you should include https: in the iframe src attribute.

If KeyReporter is running on non-standard ports, the src attribute URL must include the proper port. For example, if you run KeyReporter on port 8080 you must specify that in the iframe src attribute:

http://keyserver.sample.net:8080/frame-body/public/maps.html

Or similarly if KeyReporter SSL service is configured for a non-standard port, let's say 8443:

https://keyserver.sample.net:8443/frame-body/public/maps.html

In both of these cases we are required to include the URL scheme so the browser knows whether or not to initiate a secure connection on the non-standard port. As explained above, when the URL scheme is included, the embedded KeyReporter page will be accessed in that manner regardless of the scheme used to access the embedding page.

Embedding individual Dashboard widgets

There are two ways to embed widgets on a web page. This first method is the simplest to set up and is the most compatible since it isolates each widget from your main page, but is inefficient if you plan to load more than one widget on a particular page. Behind the scenes, this method will create an Inline Frame, or “iframe” into which the widget will be loaded. The first requirement is that your page load some JavaScript files from the KeyReporter host. These scripts are loaded within the <body> element as follows:

<body> <script type="text/javascript" src="//keyserver.sample.net/include/js/jquery.min.js"></script> <script type="text/javascript" src="//keyserver.sample.net/include/js/krf-embed.js"></script>

Note that if your page already loads any version of jQuery you do not have to load that file from the KeyReporter host.

The script loaded in the krf-embed.js file will scan your page for widgets to embed, and create an iframe for each. First, the script needs to know where the KeyReporter host is located. You indicate the host by adding the following HTML element anywhere on your page:

<div id="kr-info" data-kr-host="//keyserver.sample.net" />

Each widget you want to load is described in a separate <div> element. The div element should be empty initially, but can be contained within any other HTML markup you require in order to place it on the page. Here is an example of an embedded “Recent Logins” widget:

<div class="kr-embed" data-krw-id="RecentLogins" data-krw-title="Recent Logins" data-krw-theme="gt-green" style="width:300px;height:400px" > </div>

There are three important parts to the embedding element. First, the element must have the kr-embed class. This class is used by the embed script to find the widgets to be embedded. Second, the widget's internal ID must be provided in the data-krw-id attribute. This ID is different for each widget, and can be found in this list of Widgets. Third, the display dimensions for the widgets must be specified. In this example the dimensions are given in the style attribute, but they can also come from a CSS rule or other source.

The example also has two optional attributes: data-krw-title for the widget title, and data-krw-theme for the widget theme. The title is used in case the widget is not available from KeyReporter, and otherwise is ignored. The theme is used to change the colors of the widget, as can be done on the main Dashboard.

The embedding element for any widget can be copied from the widget's Settings window. First add the widget to a dashboard in KeyReporter, configure it how you want it to appear, then click the Embed tab in the Settings window. Copy the text that appears and use it to embed the widget in an external page, as described above. You can remove the widget from the dashboard without affecting the embedded widget.

Embedding multiple widgets on the same page

When you are embedding multiple widgets in the same page, it is most eficient if those widgets can share the various scripts and style sheets that are loaded from KeyReporter. One potential pitfall is that these resources might conflict with the scripts that are loaded by your external web page. This method will load jQuery, which is a widely used JavaScript library that you might already use on your page. Also, the Bootstrap CSS framework is loaded. If neither of these will conflict with your external page, this is the best method to use for embedding (otherwise you can use the iframe-based method described above to embed multiple widgets on a single page).

The first requirement is that your KeyReporter must be configured to support Cross-Origin Resource Sharing (CORS). To do this, edit the kr.conf file, which is locate in the KeyReporter Data Folder. Add these two lines to the file, within the <dict> section:

<dict> <key>corsurl</key> <string>*</string>

Once KeyReporter is set up to allow CORS, you can configure your external page. The page must load a style sheet from the KeyReporter host. The style sheet is loaded within the <head> element as follows:

<head> <link href="//keyserver.sample.net/include/css/kr-embed.css" rel="stylesheet">

Your page must also load some JavaScript files from the KeyReporter host. These scripts are loaded within the <body> element as follows:

<body> <script type="text/javascript" src="//keyserver.sample.net/include/lang/kr.dash-en.min.js"></script> <script type="text/javascript" src="//keyserver.sample.net/include/js/kr-embed.js"></script>

The script loaded in the kr-embed.js file will scan your page for widgets to embed. First, the script needs to know where the KeyReporter host is located. You indicate the host by adding the following HTML element anywhere on your page:

<div id="kr-info" data-kr-host="//keyserver.sample.net" />

Each widget you want to load is described in a separate <div> element. The div element should be empty initially, but can be contained within any other HTML markup you require in order to place it on the page. Here is an example of an embedded “Recent Logins” widget:

<div class="kr-embed" data-krw-id="RecentLogins" data-krw-title="Recent Logins" data-krw-theme="gt-green" style="width:300px;height:400px" > </div>

There are three important parts to the embedding element. First, the element must have the kr-embed class. This class is used by the embed script to find the widgets to be embedded. Second, the widget's internal ID must be provided in the data-krw-id attribute. This ID is different for each widget, and can be found in this list of Widgets. Third, the display dimensions for the widgets must be specified. In this example the dimensions are given in the style attribute, but they can also come from a CSS rule or other source.

The example also has two optional attributes: data-krw-title for the widget title, and data-krw-theme for the widget theme. The title is used in case the widget is not available from KeyReporter, and otherwise is ignored. The theme is used to change the colors of the widget, as can be done on the main Dashboard.

The embedding element for any widget can be copied from the widget's Settings window. First add the widget to a dashboard in KeyReporter, configure it how you want it to appear, then click the Embed tab in the Settings window. Copy the text that appears and use it to embed the widget in an external page, as described above. You can remove the widget from the dashboard without affecting the embedded widget.