Administrator

[Select partners] How do I create Custom activity toolbar buttons?

  • Updated:
    info_outline
    Created:

Note: This content is visible only to select partners.

Buzz's activity player renders third-party-hosted course activities in an iframe. Buzz also has a standard activity-player toolbar where it displays the Print and Text-to-speech buttons, which apply to the current activity when clicked. Buzz hides those buttons for externally hosted content because of the iframe boundary limitations enforced by browsers and because it cannot implement these buttons for the external content.

You can configure Buzz to display custom Print and Text-to-speech buttons and implement handlers for those buttons in your Custom activities, so that your externally hosted content has toolbar buttons with the same look and similar behavior to those implemented in Buzz. 

This article shows you how to do this.

Add buttons to Domain settings > Domain customization

To display toolbar buttons in Custom activities in a domain, you add an activity-toolbarbutton entry to the Domain settings > Domain customization window. In domains with that customization, Buzz shows the button when it renders your activity, and sends messages to your activity via the postMessage JavaScript method when an enduser clicks the button. 

Buzz shows the buttons for an activity when these conditions are met:

Add button elements and attributes

To add the Custom activity toolbar buttons to a domain:

  1. Sign in as a domain administrator.
  2. From the More menu, open Domain settings.
  1. Click Show text editor in the toolbar.
  1. Open the Domain customization tab.
  2. Add an <activity-toolbarbutton-list> element and one <activity-toolbarbutton> for each button (Print and Text-to-speech). Each button can include the following attributes:
    • id is the unique ID of the button. We recommend a guid or similar ID to avoid collisions when merging settings with subdomains.
    • type identifies the button type. Possible values are:
      • print is a button that looks like Buzz's standard Print button.
      • speechstream is a button that looks like Buzz's Text-to-speech button, which launches the SpeechStream application.
    • includetoken applies only when type is print. A boolean value that defines whether Buzz sends the authentication token to the iframe in a message. The default is false. 
    • role is the optional, bar-separated list of roles to which this button applies. This can be one or more of the following values: student, teacher, parent, or admin. If omitted, the button displays for all roles.
    • origin is the trusted origin that handles the button-click event for this button (origin is defined at https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage in the origin parameter for the dispatched event). Buzz displays the button if the origin sends a postMessage to Buzz indicating it is OK to display the button.
      • This url must match the postMessage origin (case-insensitive).
      • This url must start with https:// if includetoken is true.
      • Example: https://mydomain.example.com
  3. Save.

Example: This example configures a domain to show a Print button in the teacher app and a Text-to-speech button in all apps for activities hosted at https://mycourses.com:

<activity-toolbarbutton-list>
  <activity-toolbarbutton id="btn11111" type="print" origin="https://mycourses.com" includetoken="true" role="teacher" />
  <activity-toolbarbutton id="btn22222 type="speechstream" origin="https://mycourses.com" />
</activity-toolbarbutton-list>

PostMessage calls

Since Buzz and the Custom activity are hosted on different domains, we use the postMessage method to communicate between Buzz and the activity (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Each message is a JSON-stringified object containing the message name and its associated data. 

The activity calls postMessage on its parent DOM element with the target origin of ‘*’. 

Activity posts this message to tell Buzz it is ok to display a custom button:

Name Data Description
ShowButton {“name”: “ShowButton”,
“type”: string,
“id”: string}
  • id: The button’s ID from the Domain settings defintion. 
  • type: The button type. Possible values are print and speechstream.

Buzz posts this message to the activity when a user clicks a custom button:

Name Data Description
Click { “name”: “Click”,
“id”: string,
“type”: string,
“app”: string,
[“token”: string,]
[“ssUrl”: string,]
[“ssConfig”: string,]}
  • id: The button’s ID from the Domain settings defintion. 
  • type: The button type. Possible values are print and speechstream.
  • app: Buzz app that is currently running. Possible values are student, teacher, parent, or admin.

This field is included only if the button type is print:

  • token: The current user’s authentication token. Included only if the button definition has includetoken=true.

These fields are included only if the button type is speechstream

  • ssUrl: The speechstream.url setting currently configured on the domain.
  • ssConfig: The speechstream.v3config setting currently configured on the domain. 

To debug your integration, you can set window.logCustomMessages = true from the browser console to log messages to the console.

forum

Have a question or feedback? Let us know over in Discussions!