Say 👋 hello to BusyBee, your AI-powered learning & teaching companion for Buzz. Learn more!

Administrator

How do I set up custom top-level toolbar buttons?

  • Updated:
    info
    Created:

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>
Click to copy

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 hidden iframe

Buzz renders your hidden iframe when the custom button is rendered on the toolbar. It is rendered without any visibility to the user. Any visible UI should be implemented in the dropdown iframe.

When your hidden iframe is rendered, or any time information from any of your data sources changes, you can call the postMessage JavaScript method passing UpdateButtonCount as the message name to initialize or update the numeric badge indicator on the toolbar button. (See the PostMessage calls section for more details about constructing the message.)

If you do not have dropdownurl set, you also need to handle the button click from your hidden iframe. To handle the button click, your iframe must handle the ExecuteButtonAction message that Buzz posts to your iframe using postMessage. (See the PostMessage calls section for more details about the details of the message.)

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?

forum

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