Tuesday, August 21, 2012

Custom Callouts in the SharePoint 2013 Metro UI, Part 3: the CalloutManager

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


CalloutManager allows to get or create an instance of the callout and manage its state.


How to Get a Callout

If you need to manage already created callout you have to get a reference to the desired instance. The CalloutManager has several methods to do it.


getFromLaunchPoint

This method allows to get an instance of the callout from its launch point. The only argument is the DOM element that is used as a launch point for the desired callout:
// choose the launch point HTML element
var launchPoint = document.getElementById('calloutDiv');
// get the callout
var callout = CalloutManager.getFromLaunchPoint(launchPoint);

If there's no defined callout for the specified launch point the error will be raised.


getFromLaunchPointIfExists

It's the variation of the getFromLaunchPoint (see above) method. The only difference is that there will be no error if the callout isn't founded. In that case the method simply returns null. it allows to check for the existence of the callout instance silently.

// get the callout
var callout = CalloutManager.getFromLaunchPointIfExists(launchPoint);
if (callout == null)
{
   // create
}

getFromCalloutDescendant

This method allows to get a callout instance from the DOM element located inside it's structure. It allows for example to get the callout from its content. The only argument is the DOM element. If the chosen DOM element is not inside the callout or the callout is not found for the some reason the error will be raised.

// choose the descendant HTML element
var descendant = document.getElementById('descendantDiv');

// get the callount
var callout = CalloutManager.getFromCalloutDescendant(descendant);

How to Create a Callout

There are two methods to create a callout. Both methods accept a callout creation options object and return the created callout instance. For the details of the creation see the first article of the series.


createNew

The method createNew which allows to create a callout is described in the first part of this series.


createNewIfNecessary

The method createNewIfNecessary is almost identical to the createNew but creates the callout only if there's no callout for the target launch point already. If there's a callout it will be returned instead of the creation of the new one.

var callout = CalloutManager.createNewIfNecessary(calloutOptions);

How to Remove a Callout

If you need to remove the callout you need to pass it to the remove method of the CalloutManager:

// get the callout
var launchPoint = document.getElementById('calloutDiv');
var callout = CalloutManager.getFromLaunchPoint(launchPoint);
// remove
CalloutManager.remove(callout);

How to Enumerate All Callouts

If you need to get all the defined callouts you can use the forEach method of the CalloutManager:

// close all the callouts on the page
CalloutManager.forEach(function(callout) {
   // close the current callout
   callout.close();
   }
});

You have to specify a function to apply for each callout. The only argument of this function is the callout instance currently being processed.


How to Close All Opened Callouts

The previous section shows how you can close all the callouts enumerating them by forEach method. But for this particular task the CalloutManager has the helper shortcut function - closeAll:

// close all the callouts;
var isAtLeastOneCalloutClosed = CalloutManager.closeAll();

This function return true if at least one callout was closed.


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

15 comments:

  1. This was super helpful. Thank you so much for posting these articles! I have one question though. What is the best way to make a "tour" from these popups? For example, clicking on a page element would open one, but clicking on an option within the callout should close that callout and open the next one. How could we do that? Creating the callout ahead of time and calling open() doesn't appear to work. :(

    ReplyDelete
    Replies
    1. Hi Sunira! Before I will try to help you to implement such a functionality check this library: http://usablica.github.io/intro.js/ (click the green button on the page for quick demo). I think it's a better alternative for your scenario.

      Delete
  2. Hi Alex,
    Thanks for wonderful article but i have some problem.

    I have a custom aspx page in which i want to replicate the callout out of box feature of document library with all the footer link,, I searched in net a lot and didn't get any solution.. could you help me please.. Thanks in advance..

    ReplyDelete
    Replies
    1. Hi! Can you add more detail about the desired functionality? Do you have some data about your files from library on custom page and want to render the same doc callout as in the library itself?

      Delete
  3. Hi Alex, How i can display current item data on a callout?

    ReplyDelete
    Replies
    1. I mean how to display custom field data on a callout

      Delete
    2. Hi!

      It's not obvious what do you mean by "current". This article is about using the callout framework in general, to show any information regardless of context. So here we are talking not about the callouts which are raised by SP when you are clicking on some list items for example.

      Delete
  4. Hi Alex,
    I want to edit URL of Compliance Details of document library item. Do you know how to do it by using callout framework? I took a look into calloutCreateAjaxMenu, CalloutActionMenuEntry but no idea how to get it or override it. It would be much appreciated if you can help.

    ReplyDelete
    Replies
    1. Sorry but I don't know the answer to this particular question and unfortunately I have no time to do some research now. :(

      Delete
  5. Is there any way to stack the menu items instead of having them go next to each other?

    ReplyDelete
    Replies
    1. Hi Patrick! Sorry but unfortunately I've lost my interest in SP development now and I've already fogot a lot. Anyway I've done only a little research on the subject of callouts framework so I don't know the answer to your question. :(

      Delete