Say 👋 hello to BusyBee, your AI-powered learning & teaching companion for Buzz. Learn more!
Coding required
This is an API task that requires coding and should be done by a content developer with that knowledge.
Agilix partners can add custom, top-level toolbar buttons to Buzz. These buttons are displayed on the top toolbar, left of the Help button (or App chooser if it appears for you) and appear from left to right in the order they are added.
These can be set up to perform any custom action, including:
- The ability to manage a numeric indicator on the button in real time (managed by a hidden iframe).
- The ability to build a custom dropdown that shows when the user clicks the button (managed by a dropdown iframe).
- The ability to open another window.
Buzz manages rendering the button, including the icon, the tooltip or title, and the dropdown container.
Configure the button
You define custom toolbar buttons in Domain Settings > XML Editor [ < > ].
Select the Application Settings tab. An element named toolbarbutton-list allows you to define any of the button attributes outlined in the table below.
<settings>
<toolbarbutton-list>
<toolbarbutton id="chat"
icon="fa-comments"
title="Chat"
dropdownurl="https://example.com/dropdown?userid={{USERID}}..."
dropdownwidth="250"
dropdownheight="400"
hiddenurl="https://example.com/..."
menuentryid="custom-id"
role="parent|student" />
...
</toolbarbutton-list>
</settings>
Button attributes
| Attribute name | Description |
|---|---|
| id |
The unique string identifier for the toolbar button. You may choose any unique value. |
| icon | The Font Awesome icon name to use for the toolbar button. Prefix Font Awesome icon names with “fa-”. |
| title | The display title of the toolbar button. |
| dropdownurl | The *optional URL to your secure (https) server that will be displayed in a dropdown iframe when the user clicks the button. This is ignored if menuentryid is defined. |
| dropdownwidth | The optional desired width of the dropdown iframe. To accommodate newer design styles, this should be no greater than 280 to avoid scrolling. |
| dropdownheight | The optional desired height of the dropdown iframe. |
| hiddenurl | The *optional URL to your secure (https) server that will be rendered in a hidden iframe to manage your custom toolbar button. This iframe can be used to manage the numeric indicator on the button and to perform the toolbar button action, if dropdownurl is not specified. |
| menuentryid | The optional ID of a custom menu entry to launch when the user clicks the button. The ID must match a custom menu entry in the domain customization. You should also ensure that the custom menu entry filters and restrictions are set such that it is visible whenever this toolbar button is visible. |
| role | The optional, bar-separated list of roles to which this toolbar button applies. This can be one or more of the following values: student, teacher, parent, or admin. If omitted, the toolbar button displays for all roles. |
*You MUST specify either the dropdownurl or hiddenurl attributes.
Replacement variables
The dropdownurl or hiddenurl URLs may contain the following replacement variables.
| Variable name | Description |
|---|---|
| TOKEN | The current XLI token. |
| USERID | ID of the currently authenticated user. |
Each replacement variable in the URL must be enclosed within {{double curly braces}}.
Implementing the dropdown iframe
Buzz instantiates the dropdown iframe each time the user clicks the custom toolbar button to show the dropdown. Buzz hides and destroys the dropdown iframe when the user clicks outside the dropdown or if the user clicks the custom toolbar button while the dropdown is open.
If you want to explicitly close the dropdown from your dropdown iframe, you can call the postMessage JavaScript method passing CloseButtonDropdown as the message name. (See thePostMessage calls section for more details about constructing the message.)
Buzz attempts to accommodate the configured dropdown width and height for the instantiated iframe. However, Buzz will reduce the size to fit if the requested size does not fit in the available space. For newer design patterns, the width of your dropdown should be less than or equal to 280.
Cross-frame communication
If you have both a hidden iframe and a dropdown iframe, you may want to communicate between them. To do this, you can call the postMessage JavaScript method passing PostCustomMessage as the message name. (See the PostMessage calls section for more details about constructing the message.)
If you post one of these custom messages to the dropdown iframe when the dropdown is not open, the message will be ignored.
PostMessage calls
Since Buzz and the custom integrations are hosted on different domains, we use the postMessage API to communicate between Buzz and the custom iframe (learn more: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
The custom iframe calls postMessage on the top level window using window.top.postMessage with the target origin of ‘*’. This table summarizes the messages that the custom top level menu button API defines:
| API name | Originator | Data | Description |
|---|---|---|---|
| UpdateButtonCount |
Custom iframe |
{“name": “UpdateButtonCount", “id”: “string”, “count": number } |
Custom iframe posts this to update the count displayed in the button’s status indicator. The id parameter is the ID defined in the configuration for the button to update. If you pass zero or empty as the count parameter, Buzz hides the indicator. |
| ExecuteButtonAction |
Buzz | {“name": “ExecuteButtonAction", “id": “string" } |
Buzz posts this when the user clicks the button, if there is no dropdownurl defined. The id parameter is the ID defined in the configuration for the button that the user clicked. |
| CloseButtonDropdown |
Custom iframe |
{“name": “CloseButtonDropdown", “id": “string" } |
Custom iframe posts this to close the custom dropdown iframe. The id parameter is the ID defined in the configuration for the dropdown to close. |
| PostCustomMessage |
Custom iframe |
{“name”: “PostCustomMessage”, “id”: “string”, “target”: hidden|dropdown, “payload”: “string”} |
Custom iframe posts this to send a message to the other custom iframe. The id parameter is the ID defined in the configuration. The target parameter is the intended target of the custom message and can only be hidden or dropdown. The payload parameter is the payload that will be sent, unmodified, to the target iframe in a call to postMessage. |
You can set window.logCustomMessages = true from the browser console to log all messages that Buzz receives to the console.
Custom top-level toolbar buttons open content in iframes which don't follow Buzz's idle timeout reset parameters. Buzz supports a postMessage API that allows these integrations to reset the idle timeout: How do I keep idle timeout updated in iframes?