CallOuts In SharePoint

Callouts were introduced in SP2013 to Highlight content and enhance the functionality of SharePoint. Callouts provides a flexible way to engage your user and showcase your SharePoint functionality.

Let's see how to create callouts.

callout.js is the js, through which we can create custom callouts, so we have to make sure it's referenced in master page and loaded before using callouts.

How to load?

make sure callout.js is registered in your master page, if not register it using script block and make sure it's rendered as shown below.

Then you have to examine the page on which you are working.

If it's a new webpart/wiki/enterprise page callout.js has to be loaded using SP.SOD.exceuteFunc.

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

If it's an inbuilt or already created page check if any functionality is using callouts or check for calloutManager in console F12. If undefined you have to load the callout.js as shown above. If it's defined there's no need to load but we have to wait untill it's loaded by SP.SOD.executeOrDelayUntilScriptLoaded.

(function(){
SP.SOD.executeOrDelayUntilScriptLoaded(function () {
///logic
}, "callout.js");
})();

Below are the main objects in callouts. Let's see each one by one and how to use them

CalloutManager
CalloutOptions
CalloutOpenOptions
Callout
CalloutAction
CalloutActionOptions
CalloutActionMenuEntry

CalloutManager

The CalloutManager is a singleton that stores references to every Callout object on a page inside an associative array, it exposes different methods.

closeAll() : boolean : Closes all callouts on the page.
createNew(options : CalloutOptions): Callout : Creates a new callout.
createNewIfNecessary(options: CalloutOptions) : Callout : Checks if callout with specified ID already exists. If it doesn't, creates it, otherwise returns the existing one.
forEach(callback : (callout: Callout) => void): any : Perform some action for each callout on the page.
getFromLaunchPoint(launchPoint: HTMLElement) : Callout : Searches for a callout associated with the specified launch point. Throws error if not found.
getFromLaunchPointIfExists(launchPoint: HTMLElement) : Callout : Searches for a callout associated with the specified launch point. Returns null if not found.
remove(callout: Callout): any : Detaches callout from the launch point and destroys it.

CalloutOptions

Defines the callout properties(Note: HTMLElement we have to use javascript to get element not Jquery)

ID : string : Some unique id for the callout.
beakOrientation : string : One of the following: "topBottom" (default) or "leftRight".
content : string : String (HTML allowed) that represents contents of the callout window.
contentElement : HTMLElement : HTML element that represents contents of the callout window.
contentWidth : number : Content element's width in pixels. By default = 350.
launchPoint : HTMLElement : Element on that the callout is shown
onOpeningCallback : (callout: Callout) => void : Fires after the callout is rendered but before it is positioned
and shown
onOpenedCallback : (callout: Callout) => void : Fires right after the callout is shown
onClosingCallback : (callout: Callout) => void : Fires right before the callout is closed
onClosedCallback : (callout: Callout) => void : Fires right after the callout is closed
openOptions : CalloutOpenOptions : Defines opening behavior
title : string : Title for the callout

CalloutOpenOptions

Defines how callout should open

closeCalloutOnBlur: boolean : Callout will be closed on blur
event: string : HTML event name, e.g. "click"/"hover"
showCloseButton: boolean : Close button will be shown within the callout window with above objects we can create normal callouts.

Create a webpart page and add script editor webpart and add div with id 'my_callout' and add below code

Callout manager has an extension though which you can create a callout using createNew or createNewIfNecessary depends on requirement to which we need to pass CalloutOptions object.

(function(){
SP.SOD.executeFunc("callout.js", "Callout", function () {
var myCalloutOptions = new CalloutOptions();
myCalloutOptions.ID = "my_callout";
myCalloutOptions.beakOrientation = "topBottom";
myCalloutOptions.title = "my callout";
myCalloutOptions.launchPoint = document.getElementById("my_callout");
myCalloutOptions.content = "<div id='my_callout_content'>my callout content</div>";
myCalloutOptions.openOptions = {
closeCalloutOnBlur: false,
event: "click",
showCloseButton: true
}
myCalloutOptions.onOpeningCallback = function(clOut){
$("#my_callout_content").html("my callout content changed on onOpeningCallback ")
};
myCalloutOptions.onOpenedCallback = function(clOut){
console.log("onOpenedCallback")
};
myCalloutOptions.onClosingCallback = function(clOut){
console.log("onClosingCallback")
};
myCalloutOptions.onClosedCallback = function(clOut){
console.log("onOpeningCallback")
};
var myCallout = CalloutManager.createNew(myCalloutOptions) //it will return callout object
});
})();

Output

Now let's see Callout,

addEventCallback(eventName: string, callback: (callout: Callout) => void): any : Adds event handler to the callout.(eventName: string
one of the following: "opened", "opening", "closing", "closed") we can use this to get data using rest api/jsom and change the content of callout
close(useAnimation: boolean): any : Hide the callout. Animation can be used only for IE9+
getBeakOrientation(): string : Returns the beak orientation defined for the callout during its creation.
getContent(): string : Returns the contents of the callout.
getID(): string : Returns the ID of the callout.
getLaunchPoint(): HTMLElement : Returns the launch point element of the callout.
getOpenOptions(): CalloutOpenOptions : Returns the object that represents open behaivor defined for the callout during its creation.
getTitle(): string : Returns the title of the callout.
open(useAnimation: boolean): any Display the callout. Animation can be used only for IE9+
set(options: CalloutOptions): any : Sets options for the callout. Not all options can be changed for the callout after its creation.
addAction(action: CalloutAction): any : Adds a link to the actions panel in the bottom part of the callout window
we can create above callout and bind callback functions using addEventCallback on callout

(function(){
SP.SOD.executeFunc("callout.js", "Callout", function () {
var myCalloutOptions = new CalloutOptions();
myCalloutOptions.ID = "my_callout";
myCalloutOptions.beakOrientation = "topBottom";
myCalloutOptions.title = "my callout";
myCalloutOptions.launchPoint = document.getElementById("my_callout");
myCalloutOptions.content = "<div id='my_callout_content'>my callout content</div>";
myCalloutOptions.openOptions = {
closeCalloutOnBlur: false,
event: "click",
showCloseButton: true
}
var myCallout = CalloutManager.createNew(myCalloutOptions) //it will return callout object
myCallout.addEventCallback("opening", function(clOut){
$("#my_callout_content").html("my callout content changed on onOpeningCallback ")
})
myCallout.addEventCallback("opened", function(clOut){
console.log("onOpenedCallback")
})
myCallout.addEventCallback("closing", function(clOut){
console.log("onClosingCallback")
})
myCallout.addEventCallback("closed", function(clOut){
console.log("onclosedCallback")
})
});
})();

But in general, callouts are used to highlight the information and take some action(review the item and aprrove/reject/send back) so we need to add some actions to our callout. So using addAction method on callout object we can add actions to callouts. Below we are creating Approve, Reject and Manage which will have Edit/Delete. steps to add callout action.

create a callout menu actions option objects if required
create a callout action option object
create a callout action object using above callout action option
add the callout action to callout by using addAction

CalloutActionOptions

defines properties of callout actions,

disabledTooltip : string : tool tip when action is disabled.
isEnabledCallback : (action: CalloutAction) => boolean : Callback which returns if the action link is enabled
isVisibleCallback : (action: CalloutAction) => boolean : Callback which returns if the action link is visible
onClickCallback : (event: Event, action: CalloutAction) => any : Callback that is executed when the action link is clicked.
text : string : Text for the action link
tooltip: string : tool tip of action

var approveActionOptions = new CalloutActionOptions();
approveActionOptions.disabledTooltip = "Approve";
approveActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return true;
};
approveActionOptions.isVisibleCallback = = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
approveActionOptions.onClickCallback = = function(evt, action){
//rest api to update;
};
approveActionOptions.text = "Approve";
approveActionOptions.tooltip = "Approve";
var rejectActionOptions = new CalloutActionOptions();
rejectActionOptions.disabledTooltip = "cant rejectas it is created by PRAVEEN";
rejectActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return false;
};
rejectActionOptions.isVisibleCallback = = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
rejectActionOptions.onClickCallback = = function(evt, action){
//rest api to update;
};
rejectActionOptions.text = "Reject";
rejectActionOptions.tooltip = "Reject";

CalloutActionMenuEntry

Defines properties of Menu actions, create menu entries and assign them to calloutaction options.

constructor(text: string, onClickCallback: (actionMenuEntry: CalloutActionMenuEntry, actionMenuEntryIndex: number) => void, wzISrc: string, wzIAlt: string, wzISeq: number, wzDesc: string): CalloutActionMenuEntry

Parameters
text: string
Text to be displayed as the menu item text

onClickCallback: (actionMenuEntry: CalloutActionMenuEntry, actionMenuEntryIndex: number) => void Callback that will be fired when the item is clicked

wzISrc: string
Url of the icon
wzIAlt: string
Alternative text for the icon image
wzISeq: number
Sequence for the menu item
wzDesc: string
Description of the menu item

var editMenu = new CalloutActionMenuEntry("Edit", function(actionMenuEntry, actionMenuEntryIndex){
alert("edit")
});
var deleteMenu = new CalloutActionMenuEntry("Delete", function(actionMenuEntry, actionMenuEntryIndex){
alert("Delete")
});
var menuEntries = [editMenu, deleteMenu];
var reviewActionOptions = new CalloutActionOptions();
reviewActionOptions.disabledTooltip = "Manage";
reviewActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return true;
};
reviewActionOptions.isVisibleCallback = = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
reviewActionOptions.text = "Manage";
reviewActionOptions.tooltip = "Manage";
reviewActionOptions.menuEntries = menuEntries;

Add callout actions to callout using CalloutAction;

CalloutAction: Object which will host CalloutActionOptions.

var approveAction = new CalloutAction(approveActionOptions);
var rejectAction = new CalloutAction(rejectActionOptions);
var reviewAction = new CalloutAction(reviewActionOptions);
myCallout.addAction(approveAction);
myCallout.addAction(rejectAction);
myCallout.addAction(reviewAction);

Complete code Example.

(function(){
SP.SOD.executeFunc("callout.js", "Callout", function () {
//Define Callout Options
var myCalloutOptions = new CalloutOptions();
myCalloutOptions.ID = "my_callout";
myCalloutOptions.beakOrientation = "topBottom";
myCalloutOptions.title = "my callout";
myCalloutOptions.launchPoint = document.getElementById("my_callout");
myCalloutOptions.content = "<div id='my_callout_content'>my callout content</div>";
myCalloutOptions.openOptions = {
closeCalloutOnBlur: false,
event: "click",
showCloseButton: true
}
//Creat a callout using callout manager
var myCallout = CalloutManager.createNew(myCalloutOptions) //it will return callout object
//Add Events
myCallout.addEventCallback("opening", function(clOut){
$("#my_callout_content").html("my callout content changed on onOpeningCallback ")
})
myCallout.addEventCallback("opened", function(clOut){
console.log("onOpenedCallback")
})
myCallout.addEventCallback("closing", function(clOut){
console.log("onClosingCallback")
})
myCallout.addEventCallback("closed", function(clOut){
console.log("onclosedCallback")
})
//Adding Actions
//Create Action Options
var approveActionOptions = new CalloutActionOptions();
approveActionOptions.disabledTooltip = "Approve";
approveActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return true;
};
approveActionOptions.isVisibleCallback = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
approveActionOptions.onClickCallback = function(evt, action){
//rest api to update;
};
approveActionOptions.text = "Approve";
approveActionOptions.tooltip = "Approve";
var rejectActionOptions = new CalloutActionOptions();
rejectActionOptions.disabledTooltip = "cant rejectas it is created by PRAVEEN";
rejectActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return false;
};
rejectActionOptions.isVisibleCallback = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
rejectActionOptions.onClickCallback = function(evt, action){
//rest api to update;
};
rejectActionOptions.text = "Reject";
rejectActionOptions.tooltip = "Reject";
//Menu Actions Entries
var editMenu = new CalloutActionMenuEntry("Edit", function(actionMenuEntry, actionMenuEntryIndex){
alert("edit")
});
var deleteMenu = new CalloutActionMenuEntry("Delete", function(actionMenuEntry, actionMenuEntryIndex){
alert("Delete")
});
var menuEntries = [editMenu, deleteMenu];
//Action with Menu entries
var reviewActionOptions = new CalloutActionOptions();
reviewActionOptions.disabledTooltip = "Manage";
reviewActionOptions.isEnabledCallback = function(action){
//logic to decide enable/disable if not mentioned default is true
return true;
};
reviewActionOptions.isVisibleCallback = function(action){
//logic to decide hide/show if not mentioned default is true
return true;
};
reviewActionOptions.text = "Manage";
reviewActionOptions.tooltip = "Manage";
reviewActionOptions.menuEntries = menuEntries;
//Creating Callout Actions
var approveAction = new CalloutAction(approveActionOptions);
var rejectAction = new CalloutAction(rejectActionOptions);
var reviewAction = new CalloutAction(reviewActionOptions);
//Adding Actions to callout
myCallout.addAction(approveAction);
myCallout.addAction(rejectAction);
myCallout.addAction(reviewAction);
});
})();

Final output

All is well...