Instructure Canvas PostMessage messages

examples.md

Canvas iFrame PostMessages

Here's the controls you have inside an iframe in Canvas based on the code here: https://github.com/instructure/canvas-lms/blob/master/public/javascripts/lti/messages.js#L74-L170

Updated w/ help from https://github.com/bagofarms after he realized my original information was incorrect. He found some readme docs from Bracken on the subject which opened things up: https://github.com/bracken/lti_messaging

Sending a post message to Canvas

const message = {
	subject: 'lti.frameResize',
	// message specific options like...
	// height: 500
}

window.parent.postMessage(message, targetOrigin)

A word on targetOrigin from MDN:

Always provide a specific targetOrigin, not *, if you know where the other window's document should be located. Failing to provide a specific target discloses the data you send to any interested malicious site.

The following are the availible message.subject options

lti.frameResize

Resize the height of the Canvas Iframe containing your page.

const message = {
	subject: 'lti.frameResize',
	height: 500
}

options:

• height height in px
• token don't bother, I think it lets you target specific iframes, may allow you to change the size of a different iframe than the one you're inside?

lti.fetchWindowSize

Ask Canvas for the size of the containing window

const message = { subject: 'lti.fetchWindowSize'}

PostMessage event sent from canvas to iframe

window.parent.addEventListener("message", (event) => {/* ... */ }, false)

// event.data will contain json encoded string:
// see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for origin and source values
const event = {
	data: '{"subject":"lti.fetchWindowSize","height":0...}',
	origin: ...,
	source: ...
}

/*
event.data will contain the follwing keys:
height
width
offset
footer
scrollY
*/

lti.showModuleNavigation

I believe this shows and hides the next/previous buttons in the footers of module pages

const message = {
	subject: 'lti.showModuleNavigation',
	show: true
}

options:

• show Boolean

lti.scrollToTop

Scroll the canvas window to the top

const message = {subject: 'lti.scrollToTop'}

lti.setUnloadMessage

Display a beforeunload message. If the user closes the canvas tab/window while this is set, the message will be displayed.

const message = {
	subject: 'lti.setUnloadMessage',
	message: 'Drink more Ovaltine.'
}

options

• message text to display

lti.removeUnloadMessage

Clear beforeunload message.

const message = {subject: 'lti.removeUnloadMessage'}

lti.screenReaderAlert

Send an alert to screen readers.

const message = {
	subject: 'lti.screenReaderAlert',
	body: 'Alert to screen readers'
}

options

• body (string or json) I'm not sure what is possible using the json format

lti.enableScrollEvents

Subscribe to scroll events from the parent Canvas window. Your iframe will receive debounced postmessage events on the canvas window.scroll event.

const message = {subject: 'lti.enableScrollEvents'}

PostMessage event sent from canvas to iframe

window.parent.addEventListener("message", (event) => {/* ... */ }, false)

// event.data will contain json encoded string:
// see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for origin and source values
const event = {
	data: '{"subject":"lti.scroll","scrollY":500}', // canvas window.scrollY value
	origin: ...,
	source: ...
}