Sunday, August 25, 2013

Custom Callouts in the SharePoint 2013 Metro UI, Part 5: Modification of the Document Library Item Callout Content


Previous: Custom Callouts in the SharePoint 2013 Metro UI, Part 4: How to use callouts in autohosted app
Back to contents.




Modification of the Document Library Item Callout Content

Summary

This article describes my approach to modification of the content inside the callout that SharePoint 2013 renders for item inside the document library. The result of my research is a little javascript helper I wrote. You can find the code and the documentation on CodePlex at https://sp13doclibcalloutmodification.codeplex.com.

 

The Problem

SharePoint 2013 renders a special type of callout for every item inside the document library:


The quite popular question is – is it possible to modify the content of this callout? I have never seen the answer so I have decided to do a little research.

 

The research

I thought the new SharePoint client rendering templates feature could help to customize this content so I have tried to find the correct template to override. However, I have found that it is not the case and the structure and the data of the content area for this callout is strongly hardcoded inside the out-of-the-box clienttemplates.js file:

function CalloutRenderItemTemplate(renderCtx) {
    var ret = [];

    if (renderCtx.ListSchema.IsDocLib)
        ret.push(CalloutRenderFilePreview(renderCtx));
    ret.push(CalloutRenderLastModifiedInfo(renderCtx));
    ret.push(CalloutRenderSharingStatus(renderCtx));
    ret.push(CalloutRenderSourceUrl(renderCtx));
    return ret.join('');
}



The code of this function leads us to the following facts:

1.       Structure. There are 4 different “sections” of this callout:

  • File content preview area
  • The date of the last file modification
  • The information on the file sharing parameters
  • The absolute URL for downloading this file

2.       Context. This function itself and the section rendering functions inside it use some kind of context – it contains the data about the item we render, the parent list, and the parent web and so on.

3.      No modification. This structure is hardcoded and cannot be modified to hide some sections or add anything new

 

The Solution

My approach to solve this problem is to substitute this function at runtime by slightly modified copy. Of course, it is not perfect to change the out-of-the-box code of SharePoint but it looks we have no other choice there. Besides this function is a simple wrapper to the underlying sections rendering functions so I think it is quite safe to alter it. 

I have made the modified version of the function and have added the ability to configure the following:
  • You can hide any of the four out-of-the-box sections
  • You can specify the callbacks to render the new sections before or after any of the standard sections

 

The Library

I have implemented the code in the new javascript file – it defines all the code for the new function and the code to substitute the original function at runtime. Therefore, you have to do the following actions to let this helper library work:
  1.  reference the library file CalloutRenderItemTemplateCallbacks.js inside the page where you want to add callout modification
  2. define your own javascript code inside the same page to set up the library configuration.
Please note that you don’t need to modify any of the Sharepoint system files at all!

Hiding of the standard sections

If you want to hide any of the standard sections in this callout, you have to set the appropriate flag for target section:

CalloutRenderItemTemplateCallbacks.SharingStatus.renderSection = false;

Rendering of the new section

If you want to add a new section before or after any of the standard section, you have to specify the rendering callback function:
CalloutRenderItemTemplateCallbacks.LastModifiedInfo.Before = function(renderCtx)
{
 // generate the content for the section based on current rendering context
var newSectionHtml = ‘
This is the content of the new callout section.
’ return newSectionHtml; }
It’s the simplest code of the callback made for the sake of simplicity of the example. Now let us see the more realistic example. Now we are rendering the data of the field of the list item we render:

CalloutRenderItemTemplateCallbacks.LastModifiedInfo.Before = function(renderCtx)
{
 // Create the id for the div inside our section markup where we will place new content.
 // We create the dynamic Id based on the item being rendered. We can get the current item from the rendering context.
 // Please note that we can get an info on the item being rendered from the supplied rendering context ('renderCtx' parameter)
 var id = 'calloutAdditionalInfoSection_' + renderCtx.CurrentItem.ID;

 // Let's define the function to render the content of the new section inside the created container div
    function fillSection(sender, args){
     // Find the container inside the created section
     var div = document.getElementById(id);

     // Add the content of the item's field via Client Side Object Model (CSOM)
  div.textContent = oListItem.get_item('DocLibCalloutPreviewTestColumn');
 }

 // Load the item data via rendering context and CSOM
 var clientContext = SP.ClientContext.get_current();
 var oList = clientContext.get_web().get_lists().getById(renderCtx.listName);
 var oListItem = oList.getItemById(renderCtx.CurrentItem.ID);
 clientContext.load(oListItem);
 clientContext.executeQueryAsync(Function.createDelegate(this, fillSection));

 // return the new section HTML
    return  'LastModifiedInfo.Before for file "' + renderCtx.CurrentItem.FileLeafRef +  '"'; 
}
// Hide the out-of-the-box Sharing Info section
CalloutRenderItemTemplateCallbacks.SharingStatus.renderSection = false;


Pleace note that the rendering context (renderCtx param) is quite powerful and data rich. It contains the info about the current item, current list, current web and much more – you can inspect its properties in the browser debugger. Here’s the result (Share Info section is hidden and the new section is added:

The Source

You can find the code of the library on the Codeplex project site I have made for it: https://sp13doclibcalloutmodification.codeplex.com. There you can find the library itself and the documentation. I hope my little research helps someone!


Previous: Custom Callouts in the SharePoint 2013 Metro UI, Part 4: How to use callouts in autohosted appBack to contents.

8 comments:

  1. Alex - you are an absolute star! I had create a custom callout but was disappointed with the results as I lost lots of functionality (actions, list filtering, etc.).

    This is a simple and elegant solution. Such a pity that Microsoft did not provide this in the first place!

    ReplyDelete
  2. Excellent solution, thanks Alex. By chance do you think this solution could be expanded to hide individual CallOut actions (Edit, Share, Follow) as well?

    ReplyDelete
    Replies
    1. Hi! I'm glad you like my solution! :) As for your question - I suppose there are some out-of-the-box ways to hide standard callout menu actions. Here's one approach: http://www.learningsharepoint.com/2013/07/08/hideremovecustomize-callout-actions-in-sharepoint-2013/ and here's the another: http://www.estruyf.be/blog/hiding-the-social-actions-follow-share-from-the-document-libraries-in-sharepoint-2013/ I have to create my solution because I couldn't find any other way to customize the ***content*** section of the callout as it's hardcoded. It appears there's no need to expand my solution on the menu section.

      Delete
  3. Hi, Is it possible to customize 'new document' call out?. I need to add few options and remove 'powerpoint presentation' from the content section and add few custom actions in footer. thanks

    ReplyDelete
    Replies
    1. Hi!

      Unfortunately I haven't much time now to investigate in full details but my little research shows that it's the custom callout and it can be relatively easily customized via JS. You can modify the objects and functions created in clienttemplates.js (use the clienttemplates.debug.js version for tests) script.

      To remove PowerPoint item I suggest to remove the relevant item on the fly from the InitializeNewDocumentInfo object. Here the definition for the PowerPoint item:
      docInfo[DocumentType.PowerPoint] = ...

      To add new options instead of PowerPoint you have to create the similar option markup as it is for the default options. You can embed it somewhere around the RenderNewDocumentCallout function.

      To add your own options in footer look at the CreateNewDocumentCallout function as the start point - it's the place where the existing option is defined. You can add additional options with the callout.addAction method used there - it's from the standard callout framework.

      Of course the implementations details may be various but it's the directions I can suggest to you now.

      Delete