Friday, April 5, 2013

SharePoint 2013: PDF Support and Behaviors - The Whole Story


Check out the whole SharePoint 2013 Solution Series
New Titles Added Weekly!

EXECUTIVE SUMMARY

SharePoint 2013 supports PDF documents out-of-the-box. Initially, web applications do not allow opening PDFs in the browser, however, by adding PDF as an allowed MIME type, browser rendering via Adobe is achieved.

Office Web Apps server provides Office document previews and rendering in Search results without the need for client applications installed (e.g. Word, Excel, etc.). However, once SharePoint is bound to Office Web Apps, PDF documents no longer open in the browser.
There are two workarounds –





1)      Configure PDF items to render as Word Items which allows PDFs to open and preview in Search within Office Web Apps
2)      Modify the PDF Item display template which allows PDFs to render in the browser via Adobe. Modify the PDF hover template to display previews.
These workarounds take care of Search, but PDFs will still open in the client application (e.g. Adobe) from Document Libraries. The solution here is an update to Office Web Apps. The February/March 2013 Update to Office Web Apps server supports opening PDFs from document libraries within Office Web Apps.

The following table summarizes the various PDF rendering and preview behaviors:



 

Search PDF Preview

Search Open (clicking on result)

Document Library Open (clicking on Document)

Out of the Box (Strict Web App)

 

Available by modifying the Display Template

Opens in Adobe or associated client application

Opens in Adobe or associated client application

Out of the Box

(Permissive Web App or Allowed Mime Type of PDF)

Available by modifying the Display Template

Opens in web browser and search term is passed into Adobe

Web Browser

Office Web Apps Server

(October 2012 Release)

Two options:

1.       Display template (shows in Adobe web)

2.       Modify Result Type to use Word Item (shows in Word App Web)

Opens in Adobe or associated client application.


Opens in Browser with modification of display template

Opens in Adobe or associated client application.

 

Office Web Apps Server (Feb/Mar 2013 Update)

Two options:

1.       Display template (shows in Adobe web)

2.       Modify Result Type to use Word Item (shows in Word App Web)

Opens in browser using Word Web App

 

Can use templates to display in Adobe Web.

Opens in browser using Word Web App

 

If not bound to WordPDF – Opens in Adobe or associated client application.

 
 


It is also worth mentioning that if Office Web Apps is not used for Search results of PDFs, the opening of PDFs in the browser passes the search terms into Adobe and thus finds the occurrences within the document. An example of this “search term pass-through” is displayed below:











Based on my investigations and modifications, when using Office Web Apps server with SharePoint, there are two overall options when handling PDFs. One provides a more consistent user experience and the other provides the most functionality. These options are outline below:
Most Consistent User Experience
The most consistent user experience would be to use Office Web Apps server (with the update) to enable opening of PDFs from libraries in the browser and to modify the search result type to render PDFs as Word Items which enables both preview and opening of the documents from Search results within Office Web Apps.
Most Functionality
The option that provides the most functionality is to use Office Web Apps for document libraries such that PDFs are opened within the browser but then use customized search templates to preview and open PDFs from Search results thus providing the search term pass-through functionality as described above.  For the most consistent preview, use a customized copy of the Word item hover panel template (explained in the last section of this post).
The rest of this post steps through the details and explains how to accomplish the various options and behaviors.
 
OUT-OF-THE-BOX BEHAVIOR (without Office Web Apps)
 
Web Applications are created with the Browser File Handling option set to Strict. This means that only the default allowed MIME types (correlates to document types such Word, PDF, etc.) can open and display within the browser without prompting the user to Open or Save the document. PDF is not one of those default MIME types and thus, the user is prompted when attempting to open a PDF document:

 
The recommended way to enable PDFs to be opened in the browser is to add the MIME type to the allowed list of types by using PowerShell commands:

$webApplication = Get-SPWebApplication "http:/yourwebapplicationurl"
$webAppApplication.AllowedInlineDownloadedMimeTypes.Add("application/pdf")
$webApplication.Update()
Source: http://social.technet.microsoft.com/wiki/contents/articles/8073.sharepoint-2010-and-2013-browser-file-handling-deep-dive.aspx#DownloadFunctions

The other easy option, which is not recommended, is to modify your web application (via Central Admin) and change the Browser File Handling property to Permissive:




Either method will allow PDF files to be opened in the browser. A neat experience in search results is that the search term is passed into Adobe and the terms are highlighted in the document:

 












To get a PDF preview in the search results, you may follow my original idea and post.
 
 
OFFICE WEB APPS (October 2012 Release Version)

Once Office Web Apps is installed and configured, by surprise, PDF documents are no longer opening in the browser. Neither from document libraries nor from the search results. So there two options at this point (at least for the search results).

1. Follow Wictor Wilen's post to use the Word Item template for PDFs. This method both shows a preview and opens up PDF search results in the Office Web App's Word App Viewer.

2. Use my original method for creating a PDF Preview to generate the preview.
Follow these steps to allow opening of the PDF document in the browser via Adobe (maintaining the search term pass-through functionality:

Modify the Item_PDF.html in the display templates folder.
Replace this line:
            ctx.CurrentItem.csr_OpenControl = "PdfFile.OpenDocuments";

With this one:
     ctx.CurrentItem.csr_OpenApp = "word";





Problems solved, right? At this point the search is fixed but PDFs don't open from document libraries in the browser. That's where the Office Web Apps Update comes in to play!


OFFICE WEB APPS PUBLIC UPDATE (Feb/Mar 2013)

There was a cumulative and public update released in early March 2013 that adds additional support for PDFs in SharePoint 2013 using Office Web Apps server. What does this do for us??

The update adds a new application type named WordPDF. It allows PDFs to be opened from document libraries in the browser using the Word App Viewer. What about search?

For search, there is no change. You either need to copy the PDF Result Type and configure it to use the Word Item or modify the search display templates. (Same options as above).

However, I have come up with a hybrid approach that provides a consistent preview using the Word App Viewer but also provides the rendering of PDFs in the browser through Adobe with the search term pass-through!

Open SharePoint Designer and navigate to the search display templates (similar to the steps here).
Find Item_PDF.html. Right-click and select Copy:

 
Right-click again and select Paste:


This process creates a copy of the file which appears at the bottom of the list. Find the copy and rename to something different (such as Item_PDFCustom.html):

 Right-click the new file and select Edit File in Advanced Mode:


Rename the title:


Change the hoverURL:




Replace this line:
ctx.CurrentItem.csr_OpenControl = "PdfFile.OpenDocuments";

With this one:
ctx.CurrentItem.csr_OpenApp = "word";


Save the file. This handles the opening of the PDF document in the browser. Now for the preview.

Locate Item_Word_HoverPanel.html. Right-click and select copy:


Right-click and select Paste:




 
 
Rename the copied file (should be the same name you used for the hoverUrl value):
 

Right-click the new file and select Edit File in Advanced Mode:
 

 
 
Change the title:


Save the changes! Onto the Search Center!

In your Search Center, select Site Settings from the Settings menu (gear).
Under Site Collection Administration, click on Search Result Types:



 
 


Scroll down and find the PDF entry. Select Copy from the drop-down menu:

 
 

Give the type a unique name and select the PDF Customized Item as the display template:




 Click Save.

Now, the search results display previews using Office Web Apps:


And the documents open in Adobe with the search term pass-through:




CONCLUSION
There are various options and behaviors when handling PDFs in SharePoint 2013. Using Office Web Apps server somewhat forces you down a customized search experience path. The easiest and most consistent option is to have Office Web Apps handle all PDF interactions via the Word App Viewer. Providing the search term pass-through is another option but requires display template modification as explained in this post. I hope this post provided insight into this topic.
 






34 comments:

  1. I was trying your 'OFFICE WEB APPS PUBLIC UPDATE (Feb/Mar 2013)' on my German SharePoint Server.

    If I open a PDF from a share it goes to Adobe Reader. A PDF from SharePoint library goes to Word.


    Sven

    ReplyDelete
  2. Hey Steve,

    What would be the easiest way to eliminate the search term pass-through while maintaining the doc preview function and Adobe browser view function?

    Thanks!

    ReplyDelete
    Replies
    1. Modify the Item_PDF.html display template.

      Find and remove:

      + "#search=" + $urlKeyValueEncode(k)

      So this line:
      ctx.CurrentItem.csr_Path = ctx.CurrentItem.Path + "#search=" + $urlKeyValueEncode(k);

      Becomes:
      ctx.CurrentItem.csr_Path = ctx.CurrentItem.Path;

      -=Steve

      Delete
  3. Hi Steve,

    Great article, and I performed all of the steps suggested, HOWEVER: I am on Office365 and I suspect that the cumulative update or patch that allows for this has not yet been applied in O365. When I do a hover in the search, I get the dreaded, "sorry, something went wrong" view. Do you know how I can find out if this trick will work in O365?

    Thanks!
    Brian

    ReplyDelete
    Replies
    1. Which method are you using? Changing PDFs to render as Word Items? I haven't been on Office 365 lately. Maybe I should investigate...

      Delete
    2. I configured the "OFFICE WEB APPS PUBLIC UPDATE (Feb/Mar 2013)" method in Office365, but the Word Web App isn't presented. The hover panel says it's the "Microsoft Word" hoven panel, but no preview. Any updates?

      Delete
    3. Service Pack 1 is out for SharePoint 2013 but Office 365 gets updated automatically. I am not sure of your configuration and haven't been working with Office 365 lately.

      Delete
  4. Hi Steve,
    Thanks for your detailed article. I have a problem in opening pdf document directly in IE10 but I am able to open them in Chrome. I have installed "OFFICE WEB APPS PUBLIC UPDATE (Feb/Mar 2013)" from the link you have shared. I have also added "application/pdf" as trusted MIME type to the SharePoint web application. Are you aware of any specific setup for IE10.

    -Thanks,
    Gaurav

    ReplyDelete
    Replies
    1. I am not aware of any issues or setup with IE10.

      Delete
  5. Hi Steve,

    Brilliant article. Your explanation is simple and clear. However, where can I find the details or documentation regarding the SharePoint JSOM, specifically on the members of ctx.CurrentItem such as csr_OpenControl, csr_OpenApp etc. Although I partially know what these do, I don't seem to actually understand their complete details or significance.

    One of the things that I'm trying as a part of my work is provide some functionality to the user as mentioned below:
    Assuming that the PDF file opens with adobe web (with search term pass through) as mentioned in your post. I want to provide a functionality where user might be able to provide a new search term and later if required, he should be able to toggle to previous search term (note that he is not starting a new search and entering the term again). One of the ideas, was to pass the pdf url with search term to a page that contains iframe and open the adobe web within the same. However, how do I instruct the display template to open the custom page (instead of the directly opening adobe in web)? I guess understanding the JSOM reference in details will help me in deep diving into customization.

    ReplyDelete
    Replies
    1. I usually just loop through the objects and spit them out on the page so I can review. I don't know any resource that explains these in-depth.

      For your custom page, I would modify the csr_path property to use the custom page and pass in the file path. I would then not set the csr_OpenControl value at all.

      So try modifying the following code line to use the custom page:

      ctx.CurrentItem.csr_Path = ctx.CurrentItem.Path + "#search=" + $urlKeyValueEncode(k);

      Delete
    2. Steve,

      Thanks for the response. I'll try this out. Also, I've been tried the following today: Instead, of looping thru the objects, I inserted 'debugger;' code in the display template and set a watch on the objects thru IE developer tools.
      It would have been nice to have some information or documentation on these objects from MS.

      W.r.t the idea that you've mentioned, I'm skeptical regarding its outcome. As far as I understand, the value of csr_Path is the absolute url of the pdf file and the code in the display template 'Item_pdf.html' is appending '#search=sometext' to it. This formatted URL request gets rendered in the browser thru adobe web. As mentioned by you, if I change the value of csr_Path, how will SP instruct which pdf file to be opened?
      Nevertheless, I'll give it a try.

      Delete
    3. The path would be the URL to the custom page. You would need to pass the PDF url as a query parameter. Then, your custom page would need to read the PDF url from tge query string and process accordingly.

      Delete
  6. Steve,

    I tried this out and it works. But I realized that displaying a page in iFrame may not really be good option (atleast when it comes to SharePoint). Also, I didn't try (& I'm not really sure) if adobe web opens up in iFram without any issues.

    Finally, the requirement changed out to be "open the pdf in another tab when user clicks on any file link in the search results page". After a lot of googling and code debugging, i was able to achieve that thru JavaScript code change in the display template file.

    Thanks to you. Your post helped me a lot in understanding the display template customization w.r.t pdf initially.

    ReplyDelete
    Replies
    1. I am glad this helped. Iframes of PDF documents that live in SharePoint render fine but you need to add the SharePoint URL to the HTML Field Security of the site collection.

      Delete
  7. Do you have any advice for the reverse problem? We just upgraded to SP2013, and now it is forcing all PDFs to open in the browser. We have our media department that needs to edit PDFs in an external app, and for some reason sharepoint and/or IE refuse to let the external app open the PDF! This worked perfectly in SharePoint 2007.
    I have set each library involved to "open in client", tried changing "permissive" back to "Strict" on the webapp, checked their IE "app" settings, the Nuance editor settings, (obviously nothing on the client side changed but we checked anyway)

    The only thing I can think of to try last, is to change the MIME type from pdf to octet stream but that would break it for everyone else, and I am loathe to do that.

    ReplyDelete
    Replies
    1. Can you check the allowed mime types and make sure PDF is not in the list? I am hoping it is in the list as when the web app is set to strict, that's the only thing that would let PDFs open in the browser.

      Delete
    2. PDF is on the MIME types list, should I remove it? I was worried that if I removed it then it would force everyone to open PDFs in acrobat even if they didn't want to, but was not sure.

      I managed to fix a couple people who had Acrobat 10 or earlier. In Edit -> Properties -> Internet, there is a checkbox that says to "open in browser", this apparently overrides the IE browser settings. So those people can now open their PDFs in Nuance (I still left it as strict). But the people with Acrobat 11 are still having the trouble. It probably doesn't help they are on an old version of Nuance.

      thanks!

      Delete
    3. Yes sorry - it would force everyone to open in Acrobat. Sounds like you need different behaviors for different people but there are different Acrobat/Nuance versions out there. I don't have any perfect solutions.

      There is also a Site Collection feature called something like "Open Documents in Client Applications" - if the editing team only uses a certain site collection, maybe activating that feature would make things right.

      Delete
  8. Hi Steve,

    Is there a way in the to show the pass-through keywords highlighted in the pdf viewer using or not the office web apps

    ReplyDelete
    Replies
    1. This is provided by the out of the box PDF item display template with or without Office Web Apps.

      Delete
  9. Hi Steve,

    The highlighted keywords are not showing highlighted in the pdf preview unless we open the pdf document then it is showing.

    Is there a way to have it highlighted in the preview before opening the document.

    Thank you.

    ReplyDelete
    Replies
    1. I haven't had a chance to try this but if you follow my original post (http://stevemannspath.blogspot.com/2012/10/sharepoint-2013-pdf-preview-in-search.html) you could add the passthrough using this:

      if(!Srch.U.e(k)){
      ctx.CurrentItem.csr_Path = ctx.CurrentItem.Path + "#search=" + $urlKeyValueEncode(k);
      }

      and then use the ctx.CurrentItem.csr_Path in the object tag.

      Delete
  10. Hi Steve,

    I have added the above code in my item_pdf_hoverpanel I have started getting the following error:"We didn't find any more information about this result. ReferenceError: 'k' is undefined". I did define k using the code from item_pdf "var k = ctx.DataProvider.get_currentQueryState().k;" and started getting the following error:"We didn't find any more information about this result. TypeError: Unable to get property 'get_currentQueryState' of undefined or null reference".

    Thank you.

    ReplyDelete
    Replies
    1. You shouldn't need to copy anything from the item template. Take a look at my hoverpanels on my source code page.

      Delete
    2. k is the value from the search box in the query string.

      Delete
    3. Hi Steve,

      This is what I did, I followed the original post and was able to preview the adobe document and when added if(!Srch.U.e(k)){
      ctx.CurrentItem.csr_Path = ctx.CurrentItem.Path + "#search=" + $urlKeyValueEncode(k);
      } I started getting the error k is not defined.

      Thank you.

      Delete
    4. Ok. You'll have to pass k in from the item template. I haven't had time to play with it. I'll try to look at it soon.

      Delete
  11. Finding this article stopped me from pulling my hair out, specifically the part about changing ctx.CurrentItem.csr_OpenControl. Just wanted to thank you, great article!

    ReplyDelete
  12. Very helpful article ! I was always curious about all these complex algorithms that are being used in these ssl encryptions.

    ReplyDelete
  13. You must have root user privileges to change the Safari plug-ins. To display PDFs using the Safari PDF viewer, you must disable the Adobe PDF Viewer.

    ReplyDelete
  14. I have setup an Hybrid Search environment on SharePoint 2013 and SPO. Currently my Search Center is on On-Prem. I am getting both On-Prem and SPO docs on On-Prem search result page. All the settings and search result looks good.
    However i am not able to Preview PDF docs coming from SPO. Preview is working for all MS office docs from SPO. I have tried to change the On-Prem search result type for PDF files to consume Word Item as display template but still not working. My issue is only with PDF preview not working from SPO files on Serach center which is on On-Prem. Can any one give valuable input to resolve this issue ?

    ReplyDelete