Help
Hosting Components in an External Web Site With iframes

The simplest way to host BrainHoney components in an external web site is by using iframes and SSO.

Embedding Components in iframes

Embed any BrainHoney component in an iframe on your page by setting the src parameter to a Standalone Component URL for the desired component. For example:

<iframe src="https://dev.brainhoney.com/Component/AnnouncementList" />

If you require communication between the iframe and your page, create a placeholder DIV instead and let the RPC connection create the iframe for you. (See the Communication section below for details.) For example:

<div id="contentFrame" style="width:800px;height:500px;"></div>
Authentication

Setting up Single Sign On (SSO) is the simplest way to handle the authentication required for most BrainHoney components. To set up SSO for your domain, see the details of the <authentication> domain customization tag.

Communication

Most BrainHoney UI components are self-contained and require no communication between them and the containing page. For those that do require communication, because the BrainHoney components are hosted on a different server from the containing page, any communication between the containing page and the BrainHoney UI component must use a cross-domain communication mechanism.

BrainHoney uses the open source easyXDM library for cross domain communication. It also supplies a cross-domain RPC interface on the Frame API that gives access to some of it's more important methods and properties.

Including easyXDM

Download easyXDM from easyXDM.net. Include easyXDM in your page containing the BrainHoney UI component by adding something similar to the following in the head of your HTML document:

<script type="text/javascript" language="javascript" src="easyXDM.min.js"/>
<script type="text/javascript" language="javascript">
  easyXDM.DomHelper.requiresJSON('json2.js');
</script>
Initializing Communication

BrainHoney uses the RPC mechanism of easyXDM for communication. To set up the initial communication with the Frame API for the embedded BrainHoney component, you first need to create the connection. Most likely, you will want to do this in the "onload" event of your page.

var rpc = new easyXDM.Rpc({
    //Standalone component URL for the BrainHoney component to display
    remote: "http://yourdomain.brainhoney.com/Component/ItemEditor" + 
            "?enrollmentid=1234&itemid=ABCD&showcancel=true",
    //Name of the <div> or other element that will contain the iframe
    container: 'contentFrame',
    //HTML props for the created iframe
    props: {
        frameborder: 0,
        height:'100%',
        width: '100%'
    }
}, {
    //Your half of the communication implementation
    local: {
        // Perform any initialization, like registering for events
        init: function(successFn, errorFn){
            rpc.addListeners('componentsaved|componentcancelled');
            if(successFn) {
                successFn();
            }
        },
        // Handle any events 
        onEvent: function(event) {
            switch(event) {
                //Handle each event using the 'arguments' variable
                case 'componentsaved':
                    if(arguments[1] == 'itemeditor' && 
                       arguments[2] == 'FrameContent') {
                        alert('componentsaved: ' + arguments[3].itemId);
                    }
                    break;
                case 'componentcancelled':
                    if(arguments[1] == 'itemeditor' && 
                       arguments[2] == 'FrameContent') {
                        alert('componentcancelled');
                    }
                    break;
            }
        }
    },
    //Define the Frame API stub interface
    remote: {
        addListeners:{},
        fireEvent: {},
        saveComponent: {},
        navigate: {},
        getProperties: {},
        getComponentState: {},
        callComponentMethod: {},
        hasRight: {},
        setShowBeforeUnloadPrompts: {}
    }
});

After the connection has been created, the Frame API will call your "init" method on the connection. This method takes two optional callback parameters. Call the first one on successful initialization. Call the second one on errors with the error message as its parameter.

RPC Frame API methods

The table below describes the methods supplied by the Frame API RPC interface.

MethodDescription
addListeners Takes a single parameter that is a bar-separated list of events on the Frame API to listen to. Each event fired will call your RPC implementation of onEvent.
fireEventPass-through to the fireEvent method of the Frame API
saveComponentPass-through to the saveComponent method of the Frame API
navigatePass-through to the navigate method of the Frame API
getPropertiesTakes no parameters and returns an object with all of the Properties of the Frame Api.
getComponentStatePass-through to the getComponentState method of the Frame API
callComponentMethodPass-through to the callComponentMethod method of the Frame API
hasRightPass-through to the hasRight method of the Frame API
setShowBeforeUnloadPromptsPass-through to the setShowBeforeUnloadPrompts method of the Frame API
Calling RPC Frame API methods

To call a method on the Frame API RPC interface, simply call the method as if it were defined on your connection object. Any return values are passed to an additional, final function parameter. The example below calls the getComponentState method to retrieve the item ID being currently edited.

rpc.getComponentState('itemeditor', 'FrameContent', function(state) {
    alert(state.itemId);
});
See Also
Without iframes <authentication> URL Syntax Frame API