xFrame API

Host API

XFrameManager

const xFrameManager = new XFrameManager()

Properties

XFrameManager.createGuest()

const guest = await xFrameManager.createGuest()

Creates a guest agent and appends it to the host agent's peers & to the manager's guest agents array.

Returns: Promise<PeerAgent>

XFrameManager.registerGuest(guestWindow, peerId)

• Should be used in one of two ways:

const iframe = document.getElementById('frameId')
let guest = await xFrameManager.createGuest()
guest = await xFrameManager.registerGuest(iframe.contentWindow, guest.id)

const iframe = document.getElementById('frameId')
const guest = await xFrameManager.registerGuest(iframe.contentWindow)

When registering a guest, a communication channel between the host & guest windows is created.

Returns: Promise<PeerAgent>

Parameters

XFrameManager.createFrameByUrl(url)

const guest = await xFrameManager.createFrameByUrl('http://guestURL.com')

Creates an HTML iframe and appends it to the host's document body. Internally uses the registerGuest method - a connection is established between the windows.

Returns: Promise<PeerAgent>

Parameters

XFrameManager.removeGuest(peerId)

xFrameManager.removeGuest(guest.id)

Removes the guest from the host agent's peers & manager's guest agents array. The guest agent no longer exists, therefore the communication is channel is dead.

Returns: void

Parameters

PeerAgent

PeerAgent.send(data)

const xFrameManager = new XFrameManager()
const guest = await xFrameManager.createFrameByUrl('http://guestURL.com')
guest.send('Hello from host window!')

Sends a message/data from the host window to the guest window (iframe).

Returns: void

Parameters

PeerAgent.sendSync(data)

await guest.sendSync({ action: 'createPost', content: 'Hello World' })

Sends a message/data from the host window to the guest window (iframe).

Returns: Promise<any>

Parameters

PeerAgent.sendCode(code)

const result = await guest.sendCode(
    "function helloWorld(name) { return 'Hello ' + name }"
)
// result = { message: '', result: 'success' }

Sends a code message from the host window to the guest window (iframe). The code is being loaded into the guest window.

Returns: Promise<IResult>

Parameters

PeerAgent.sendRPC(data)

// Load the function 'helloWorld' in the guest window
await guest.sendCode(
    "function helloWorld(firstName, lastName) { return 'Hello ' + name + ' ' + lastName }"
)

// Execute the function 'helloWorld' in the guest window
const rpc = {
    func: 'helloWorld',
    inputs: ['Tom', 'Hanks']
}
const result = await guest.sendRPC(rpc)
// result = { output: 'Hello Tom Hanks', result: 'success', message: ''}

Sends a Remote Procedure Call (RPC) message.

Returns: Promise<IResult>

Parameters

PeerAgent.sendEvent(data)

// Send a custom event to the guest window
guest.sendEvent({ name: 'customEventName', payload: 'Test payload' })

Sends an event message to the host.

Returns: void

Guest API

GuestAgent

const guest = new GuestAgent()

Properties

Events it can listen for

guest.on('ready', () => {
    // xFrame is now available
    console.log('I am ready!')
})
guest.on('data', (msg) => {
    if (msg.data === 'hello') {
        console.log('The host says "hello"!')
    }
})
guest.on('customEventName', (payload) => {
    console.log(payload)
})

Interfaces

IResult

interface IResult {
    output: any
    result: string
    message: string
}

EventPayload

interface EventPayload {
    name: string
    payload: any
}