JavaScript Embedder API

CenterView 3.1.7 and later ships with a JavaScript Embedder API (cvembedder.js). This API allows you to embed CenterView dashboards, pages and KPIs in your own web application. For information about determining when to embed resources, see Embedding Pros and Cons.

Note: If your version of CenterView does not include the cvembedder.js file, save it, then copy the file to the \Server\doc_root\common\api10 directory. (If the api10 directory does not exist, create it.)

To include the JavaScript Embedder API

Include the cvembedder.js file using <script src="http://centerview.domain.com:2020/corda/common/api10/cvembedder.js"></script>. For example:

 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
<html>
     <head>
          <title>JavaScript Embedder Example</title> 
          <script src="http://centerview.domain.com:2020/corda/common/api10/cvembedder.js"></script>
     </head> 
<body> 

          <!-- Your page content. --> 

</body> 
</html>

Replace centerview.domain.com:2020 with the domain and port of your CenterView Server.
Optionally, you can load other CenterView CSS and JavaScript files in your page. If the optional files are included, your embedded resource can display its popups in your page. If the optional files are not included, your embedded resource and display its popups only inside your embedded window.

Note: Including the optional files works only when your page and your embedded page use the same URL and port. For more information, see same origin policy.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<title>JavaScript Embedder Example</title>
                <link rel='stylesheet' type='text/css' href='/corda/themes/welcome_default/temp/ext/resources/css/ext-all.css' />
		<script src="http://centerview.domain.com:2020/corda/common/ext/ext-all-comb.js"></script>
                <script src="http://centerview.domain.com:2020/corda/common/corda/centerview-all.js"></script>
                <script src="http://centerview.domain.com:2020/corda/common/api10/cvembedder.js"></script>
	</head>
	<body>

	<!-- Your page content. -->
		
	</body>
</html>

The Basic Embedder API

The Basic Embedder API is a simple means of embedding content in your page. It uses a simple HTML construct. It consists of a div with an anchor tag inside. The div must have a class attribute with cv-embed as its value. The anchor tag must have an href tag with the direct url of what you would like to embed.

The following example embeds a KPI called kpi1.kpixml.

<div class="cv-embed">  
     <a href="http://centerview.domain.com:2020/corda/dashboards/embed/kpis/kpi1.kpixml"></a> 
</div>

The following example embeds a page called page1.pagexml.

<div class="cv-embed">  
     <a href="http://centerview.domain.com:2020/corda/dashboards/embed/pages/page1.pagexml"></a> 
</div>

The following example embeds a dashboard called embed.

<div class="cv-embed">  
     <a href="http://centerview.domain.com:2020/corda/dashboards/embed/main.dashxml"></a> 
</div>

The Advanced Embedder API

The Advanced Embedder API gives you control of how to embed a CenterView dashboard, Page, or KPI. Use a placeholder (usually a div with an id attribute) in your HTML, then use the corda.embed( options ); command to do the actual embedding. For example:

<div id="kpi2"></div>
<script>
	corda.embed({
		id: 'kpi2',
		src: 'http://centerview.domain.com:2020/corda/dashboards/embed/kpis/kpi2.kpixml',
		params: { title: 'title', description: 'new description'},
		method: 'POST',
		style: 'overflow: hidden; position: relative;'
	});
</script>

The corda.embed( options ); command has options you can specify.

Option	Usage	Description
id	Required	The id of the div placeholder in your HTML.
src	Required	The URL of the CenterView resource to embed. The resource can be a URL of a dashboard, page, or KPI.
params	Optional	Any parameters that your embedded resource needs. These parameters are passed to CenterView, which will be able to use them. (For example, you may have variables that need to be passed to a KPI.) Each parameter is separated by a comma and the value is enclosed in single quotation marks. (See the code example.)
method	Optional	The method for sending the parameters to CenterView. The method can be POST or GET. The default is POST.
style	Optional	Any extra CSS styles you want to add to the IFRAME tag that the `corda.embed` command creates. Each command is separated by semicolons and the entire set of styles are enclosed in single quotation marks. (See the code example.)

Some things to note if you are using the advanced embedder API:

The <div id> is an ID you assign to the embedder div on the page. Each embedder div on the page must have a unique ID, or the CenterView object you are trying to embed will not display. The id under the script tag is the same ID.
When you pass variables via params, be sure to update the dashboard's Policy to make the variable public.

Tips and Solutions

To execute a JavaScript function in the parent document when a button is clicked in an embedded resource, preface the function with parent.. For example:
```
parent.myfunction(a, b);
```
For a detailed example, see Example of Using the JavaScript Embedder API.
To drilldown within the embedded window from a page to another page or from a KPI to another KPI, you must add the drilldown action to the page object or KPI object using CenterView Builder.
- To add a drilldown action to go from a page to another page, in CenterView Builder select the object in the Object Browser, add a drilldown object from the Object Palette. Using the DrillAction Wizard that displays, select the Goto action type, the URL action target, specify the URL to drilldown to (e.g., "pages/page2.pagexml"), then select Get.
- To add a drilldown action to go from a KPI to another KPI, in CenterView Builder select the object in the Object Browser, add a drilldown object from the Object Palette. Using the DrillAction Wizard that displays, select the Goto action type, the URL action target, specify the URL to drilldown to (e.g., "kpis/kpi2.kpixml"), then select Get.

Issues

Login (and, by extension, Notify and Email), Home, and Exit buttons are not supported.
If you are embedding pages or KPIs, go-to-nav-id does not work. Use a go-to-url and provide the url for the page or KPI.