Highlight content and enhance the functionality of SharePoint-hosted SharePoint Add-ins with the callout control

The SharePoint callout control provides a flexible way to engage your user and showcase your SharePoint-hosted add-in's functionality. You can configure it in a variety of ways to suit your add-in's UI. You can construct this control, add it to your page, and customize its appearance and behavior.

When you do searches in a SharePoint site, you'll see examples of the callout control in action because it appears whenever you hover over a search result.

The following figure shows the callout for a single search result and shows a few of the typical things in a content control: a title, some information about the item on the page, and actions (Open and Send) that you can take on the item.

In this case, the information and actions are relatively simple, but you can already see two advantages to using it. First, it lets you show additional information about elements on a page when that's needed, and second, it gives you an elegant way of adding functionality to the page.

Example of the callout control on a SharePoint search results page

Make the control available to your HTML page by including the callout.js file

This example uses the SP.SOD.executeFunc method to ensure that the script file loads before you run any code that depends on it.

SP.SOD.executeFunc("callout.js", "Callout", function () {
    });

The function that you pass to the SP.SOD.executeFunc function contains the code that you want to run after the callout.js file loads. After you load those files, you use the CalloutManager object to create a Callout object for each page element that needs to have a callout control associated with it.

The CalloutManager is a singleton that stores references to every Callout object on a page inside an associative array.

The Callout object has only two required members: ID and launchPoint. The ID member is the key that is mapped to the Callout object in the CalloutManager: CalloutManager["value of the callout's ID member"]. The launchPoint member is an HTML page element.

You can, for example, create or get a div element on your page and pass it as a member of the Callout object. By default, the callout control appears whenever a user selects the launchPoint element.

This example shows you how to create the simplest possible callout control with only the two required members and a title string.

var calloutPageElement = document.createElement("div");
var callout = CalloutManager.createNew({
   ID: "unique identifier",
   launchPoint: calloutPageElement,
   title: "callout title"
});

This particular callout appears and displays a title at the top of the control whenever a user selects the page element. You use the optional members to customize the control's appearance, behavior, positioning, and actions in some very powerful ways. The callout control also has a set method that you can use to set a value for any parameter after you create an instance of the control.

callout.set({openOptions:{event: "hover"}});

You can also set values for all of the callout members in a CalloutOptions object, and then pass that object to the createNew method.

var calloutPageElement = document.createElement("div");
var calloutOptions = new CalloutOptions();
calloutOptions.ID = unique identifier;
calloutOptions.launchPoint = calloutPageElement;
calloutOptions.title = callout title;
var callout = CalloutManager.createNew(calloutOptions);

Customize the appearance of the callout control

You can use these members to control the display of callout.

Member	Purpose	Valid values (default in bold)
title	Display a title at the top of the control.	string, null, string containing HTML
content	Display HTML inside the control whenever there is no value for the contentElement member.	string containing HTML, null, must be null if contentElement has a value
contentElement	Display an HTML element inside the control when there is no value for the content member.	Any HTML element, null, must be null if content has a value
contentWidth	Specify the width in pixels of the callout body container. This container also has a 1-pixel border and 15-pixel padding on each side, so the control is 32 pixels wider than the body width that you specify. The control's CSS overflow property is set to hidden, so your content is clipped if it does not fit inside the width that you specify. If you set this member on an open callout, the change takes effect immediately. This is not true of the other members.	Any number between 240 and 610, 350 (making the control 382 pixels wide by default)
beakOrientation	Specify the orientation of the beak or pointer of the callout control.	topBottom orientation leftRight orientation

Customize the behavior of the callout control

You can use the following members to control the behavior of the callout. Begin with the important openOptions member because it lets you specify how the control opens and closes when the user interacts with it on the page.

These are the other members that you can set to control the callout's behavior.

Use the callout control methods

You can use these methods to customize the behavior of the callout control.

Add actions to the callout control

You add actions after you've created an instance of the callout control. A callout action can consist of either a single action or a menu of actions. You can add up to three actions to a callout control. After you have created a callout action, you add it to the CalloutControl object with its addAction method. This sample action opens a new window in your browser after the user selects the text.

//Create CalloutAction
var calloutAction = new CalloutAction({
            text: "Open window"
            onClickCallback: function() {                
                window.open(url);
            }
        });

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

You can also set values for all of the CalloutAction members in a CalloutActionOptions object and pass that object to the CalloutAction constructor.

//Create CalloutAction
var calloutActionOptions = new CalloutActionOptions();
calloutActionOptions.text = "Open window";
actionOptions.onClickCallback = function() {
    window.open(url);
};
var calloutAction = new CalloutAction(calloutActionOptions);

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

You can use these members to define the behavior of a callout action.

The next section explains how to create a CalloutActionMenuEntry and add it to a CalloutAction object.

Add action menus to the callout control

When a callout action contains a menu instead of a single action, the user sees a down arrow next to the callout action text, as in the following figure.

A callout action displays a menu when a user selects the arrow next to the action label

You can create as many menu entries as you want and add them to the callout action by passing them in an array as the value of the menuEntries member of the CalloutAction object.

//Create two menu entries.
var menuEntry1 = new CalloutActionMenuEntry("Entry One", calloutActionCallbackFunction, "/_layouts/images/DOC16.GIF");
var menuEntry2 = new CalloutActionMenuEntry("Some Other Entry", calloutActionCallbackFunction, "/_layouts/images/XLS16.GIF");

//Add the menu entries to the callout action.
var calloutAction = new CalloutAction({
   text: "MENU W/ ICONS",
   menuEntries: [menuEntry1, menuEntry2]
})

//Add the callout action to the callout control.
callout.addAction(calloutAction);

The CalloutActionMenuEntry constructor takes three parameters. The first two parameters are required. The third is optional, but it can be helpful because it lets you display an icon with the text.

• Pass a string as the first parameter to display a text label for each menu entry.

• Pass a function as the second parameter to define the action that occurs when the user clicks on the menu entry text.

• Pass a string that contains the URL for the icon that you want to display to the left of the text label.

Use the CalloutManager to create and manage instances of the callout control

The CalloutManager singleton object stores references to every Callout object on a page. It stores each instance of the callout control in an associative array where the ID value of each control is the key. The CalloutManager contains methods that help you create and manage the Callout objects that it stores.

Position the callout control on the page

The following section describes how to use the calloutPositioningProxy object to write positioning algorithms for the callout control.

Write positioning algorithms with calloutPositioningProxy

The calloutPositioningProxy object contains methods and properties that you can use to override the positioning logic that the callout control uses by default. For example, if you want the control to appear below and to the right of the launchPoint element all the time, you write a positioning algorithm that looks like the following.

function alwaysGoDownAndRight(calloutPositioningProxy)  {
    calloutPositioningProxy.moveDownAndRight();
} 

You would then pass that function as the value of the Callout object's positionAlgorithm member. You can do that when you create the Callout, or later by setting the value.

callout.set({positionAlgorithm: alwaysGoDownAndRight});

You can always take a look at the default positioning logic by launching your browser's JavaScript console (the Internet Explorer F12 Developer Tools, for example).

CalloutOptions.prototype.positionAlgorithm.toString()

You can use these methods in the CalloutPositioningProxy object to write your own positioning logic.

This positioning algorithm makes the control go above or below the text. The isRTL property of the CalloutPositioningProxy tells you whether the text is displaying a right-to-left language. You check for this property to ensure that the control is always positioned correctly in relation to the text on the page.

function examplePositionAlgorithm(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL) {
        calloutPositioningProxy.moveDownAndRight();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndRight();
        }
    }
    else {
        calloutPositioningProxy.moveDownAndLeft();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndLeft();
        }
    }
}
callout.set({positionAlgorithm: examplePositionAlgorithm});

This positioning algorithm changes the default direction of the control to downAndRight instead of upAndRight, but it uses the default algorithm if there are any collisions.

function tryDownAndRightThenGoDefault(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL)
        calloutPositioningProxy.moveDownAndRight();
    else
        calloutPositioningProxy.moveDownAndLeft();
    
    if (calloutPositioningProxy.numberOfEdgesCollidingWithBoundingBox() > 0)
        return CalloutOptions.prototype.positionAlgorithm.apply(this, arguments);
};
callout.set({positionAlgorithm: tryDownAndRightThenGoDefault});

See also

• Create UX components in SharePoint
• Code sample: Use list views, callouts, and dialogs in SharePoint-hosted add-ins
• Get started creating SharePoint-hosted SharePoint Add-ins