Custom Callouts in the SharePoint 2013 Metro UI, Part 1: Basics

Next: Custom Callouts in the SharePoint 2013 Metro UI, Part 2: Actions
Back to contents.

---

A concept of callouts in SharePoint 2013 Metro UI

SharePoint 2013 introduces a Metro-style approach to the UI design. One of the new concepts there are the callouts. Here’s the definition from the ‘Apps for SharePoint UX design guidelines’ article:

These provide relevant contextual information and actions around a particular item. Callouts are generally used to show the user more information or actions about an item in a lightweight UI.

Let’s look at some examples. Here’s the additional info for the document inside the document library:

And here’re the task details from the timeline:

So the callout is the kind of interactive super tooltip – it has a title, a content and even a command menu.

The callout structure

Let’s examine the structure of the callout UI.

title

It’s a little area at the top of the callout. The title isn’t required – there will be no such area if you don’t set its value.

content

It’s the main information area of the callout. .

close button

It’s the one of the ways to close the opened callout. The callout may be closed by:

• the mouse click on the close button
• the mouse click on the area outside the callout
• by the ESC button

There can be no close button on the callout – if the callout is opened on mouse hover instead of click and if the callout is opened programmatically.

commands area

There can be a commands area at the bottom of the callout. It contains a menu with one or several actions. If there are no commands the corresponding area will not be shown.

beak

It’s a small arrow-like element visually connecting the callout with its source. It can be placed on top/bottom or the left/right side of the callout according to the chosen callout positioning scheme.

SharePoint 2013 callouts framework

If you want to employ this concept in your custom solution (app or webpart etc) to provide design consistency with the SharePoint UI you can create custom callouts. There’s a special “framework” to create and show callouts in the SharePoint 2013. As the dialogs framework known from the SharePoint 2010 the callouts framework resides in the out-of-the-box javascript files in the LAYOUTS folder. The main part of the framework is defined in the callout.js file.

How to create a callout

In order to use the callout you have to create it. Note thet the creation of the callout is not the same as the opening – callout is created once and then can be opened/closed many times.
To create a callout you need:

1. Choose the HTML element in your UI that will be the source for callout positioning and for events (click or hover) to open the callout. It’s called the “launch point” in the callouts framework terminology.
2. Configure the options for your callout
3. Call the CalloutManager to create the callout

The launch point

Every callout need the so called “launch point”. It’s an HTML element which will be the source for positioning and opening events for the callout. If you choose the click event to open callout then the click on the launch point element will trigger the opening of the callout.
There can be only one callout associated with the specific launch point element at any given time. If you’ll try to create another callout for the same launch point there will be an error. If you need to create new callout for the launch point you have to remove the old ones first.

// choose the launch point HTML element
var launchPoint = document.getElementById('calloutDiv');

Callout options

To specify the callout parameters you need to configure an instance of the CalloutOptions class. It’s required by the CalloutManager while creating the callout.

// configure options
var calloutOptions = new CalloutOptions();
calloutOptions.ID = 'calloutID';
calloutOptions.launchPoint = launchPoint;
calloutOptions.beakOrientation = 'leftRight';
calloutOptions.content = 'content';
calloutOptions.title = 'title';

Call the CalloutManager

When you have the launch point and the callout options prepared you need to call the CalloutManager.createNew method to create and obtain the callout instance. CalloutManager is the kind of singleton used to manage callouts life cycle – to create, obtain, use and destroy callouts instances.

// call the CalloutManager to create the callout
var callout = CalloutManager.createNew(calloutOptions);

Here’s the result – the created callout is shown on click to launch point div:

To be continued

It's only the start of my research of the callouts framework. In the next articles we'll explore how to:

• create actions
• manage already created callouts
• configure all the available callout options
• open callouts configured to open programmatically (without hover or click event)
• and more...

Stay tuned and feel free to comment, correct or share this article. You can reach me here or at mail@alexboev.com

Next: Custom Callouts in the SharePoint 2013 Metro UI, Part 2: Actions
Back to contents.