CallOuts In SharePoint

Callout is a short string of text connected by a line, arrow, or similar graphic to a feature of an illustration or technical drawing, and giving information about that feature. The term is also used to describe a short piece of text set in larger type than the rest of the page and intended to attract attention from Wikipedia

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

1. CalloutManager
2. CalloutOptions
3. CalloutOpenOptions
4. Callout
5. CalloutAction
6. CalloutActionOptions
7. 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.

1. create a callout menu actions option objects if required
2. create a callout action option object
3. create a callout action object using above callout action option
4. 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

1. wzISrc: string
2. Url of the icon
   
   
3. wzIAlt: string
4. Alternative text for the icon image
    
5. wzISeq: number
6. Sequence for the menu item
    
7. wzDesc: string
8. 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...