Share Document Previews in Alfresco 4

cancel
Showing results for 
Search instead for 
Did you mean: 

Share Document Previews in Alfresco 4

wabson
Active Member II
0 8 7,498
One of the improvements introduced in Share's Document Library as part of Alfresco 4 was the refactoring of the web-preview component, which is responsible for rendering the in-line document views in the Document Details page.



These preview capabilities are one of the core strengths of Share, and now these changes allow developers and administrators to tweak the capability as they need.



[caption id='attachment_480' align='alignnone' width='628' caption='Web preview component in Alfresco 4 for a PowerPoint Presentation']Flash Document Previewer[/caption]

The Basics



Let's start with a quick overview.



The web-preview component is similar to most other Share components. The page component itself is rendered by a web script, which is responsible for loading some basic information about the document being requested, and outputting this into the markup that then forms part of the overall page.



The output does not render HTML directly, but rather instantiates a client-side component Alfresco.WebPreview, passing over the document metadata as an object literal.



Previously, that was it. The logic to set up the Flash previewer was contained within Alfresco.WebPreview, and that was what you got for all documents and images. Anything else that couldn't be transformed by the repository to a SWF file would not be previewed.

What's Changed?



Alfresco 4 changes that. Now, the rendering of content items is separated from Alfresco.WebPreview and instead performs the work via a series of plug-ins. The component still takes care of loading the document metadata, setting up the basic screen layout and working out which plug-ins can be used to render the content on-screen. This has several benefits -



  • System administrators can decide which plug-ins should be used under which circumstances, via configuration.


  • Plug-ins are chained together in the configuration. If one fails, then the other available ones are tried in turn, until one succeeds.


  • The implementation of the plug-ins by developers does not need to touch any core files. They are tied into the component via configuration alone.


What's more, Share comes with a number of different plug-ins already present. It's likely that you will still see the Flash document previewer for most of the content you look at, but you should notice that by default images are now rendered as real images within the page, and will be automatically resized if they are too big. That's because images are now handled by a different plug-in, but you can still use the Flash previewer if you reconfigure the component.



[caption id='attachment_482' align='alignnone' width='346' caption='Web preview component in Alfresco 4 for a JPEG image']Image Viewer[/caption]



Other previewers are provided for displaying audio and video content using Strobe Media Player or FlashFox, plus direct playback of supported formats using the HTML5 <video> and <audio> tags. Take a look in the directory components/preview within the Share webapp and you will see them there. It's worth looking at the source code if you're thinking of implementing your own custom previewers, as many of them are surprisingly simple.

Configuring Plug-ins



The configuration that dictates which plug-ins are used under what circumstances is contained in the web script configuration file web-preview.get.config.xml. You can find this in the Share webapp in the directory WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/preview and view it there, but if you're planning on making any changes you should first copy it into tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/preview (you may need to create the directories below web-extension).



You should see that the config is expressed as a series of conditions, each of which contains a list of plug-ins to attempt to use. For each condition that matches, each of the plug-ins within it is then added to the list to try to use.



Here's an example for MPEG-4 video files

<condition mimeType='video/mp4' thumbnail='imgpreview'>

    <plugin poster='imgpreview' posterFileSuffix='.png'>StrobeMediaPlayback</plugin>

    <plugin poster='imgpreview' posterFileSuffix='.png'>FlashFox</plugin>

    <plugin poster='imgpreview' posterFileSuffix='.png'>Video</plugin>

</condition>


The <condition> element's attributes form sub-conditions, which are AND-ed together to give the overall result. In this case, the condition will match when the content being viewed has the MIME type video/mp4 and the thumbnail with the name imgpreview can be generated (note, it may not yet have been generated) via the thumbnail service. Other conditions will only test one of these sub-conditions, but here we test both.



Each of the <plugin> elements then provides the name of the plug-in in the element body and any configuration attributes required as element attributes. In this case, each of the plug-ins is being configured to use the imgpreview thumbnail as the static 'poster' image to display in the player before the play button is pressed, and to assume this image is in PNG format. Note, these attributes will be different for each plug-in since they are mapped to the options object on the plug-in implementation.



As an administrator, within this file you can add, remove and re-order plug-ins or conditions as you need, change the conditions or change the configuration that is passed to the plug-ins at instantiation time.

Implementing Your Own



It's easy to create your own plug-ins to render content in interesting and different ways. A plug-in is implemented as a single JavaScript class, which must meet the following simple criteria



  • The name of  its constructor must be the same as the value used in the <plugin> configuration element to tie it into the component, and must be defined as a child property of Alfresco.WebPreview.prototype.Plugin. By convention CamelCase is used for the name, e.g. WebPreviewer, FlashFox, Image.


  • The object prototype must define an object literal named options and two functions report() and display(). See the in-line JSDoc of the out-of-the-box plug-ins for full details of the method signatures and return types required.


You will also need to ensure that the client-side file where you define the plug-in object is included in the <head> section of the Document Details page, you can do this as an administrator by overriding the web-preview.get.head.ftl template, or (better) as a developer by extending the .head.ftl template using a customization module applied to the web-preview.get web script.

New Viewers on Share Extras



Keep an eye out for the upcoming release of the (to-be-renamed) Media Previews add-on in Share Extras. Peter has been instrumental in helping to build up some new plug-ins for viewing different types of content that we hope can be used to remove the Flash dependency that still remains in Share for viewing document-based content. They should also provide some further examples of how you can define your own, custom, plug-ins.
8 Comments
blog_commenter
Active Member
Great work!



Will these enhancements be available in Web Quick Start ?
wabson
Active Member II
Hi Juan, you would need to consult the road map for Web Quick Start. The product team run periodic events on these subjects, as do the partner team that I'm a member of. If you can't find any roadmap info and you're not a partner, I would suggest you ask the question in the forums.
blog_commenter
Active Member
Hello!,

One question, It is posible to preview the .doc mimetype using the pdf plugin of the web explorer instead of the flash one?

by default alfresco transforms docs to swf to preview them on the previewer. It is possible to tell alfresco to try to preview the transformation of the doc mimetype to a pdf?



Thank you
wabson
Active Member II
Hi Gabriel, Peter Löfgren and I are currently adding this to Share Extras. You can check out the Media Previews project from SVN for a sneak preview or join the development list for the discussion or if you have questions.
blog_commenter
Active Member
+1 for removing the Flash dependency - any progress on that?
wabson
Active Member II
Hi Rob, if you build the Media Previews project from trunk it's pretty stable at the moment. If you have time to do that and post your feedback on the development list, that would be really helpful.
blog_commenter
Active Member
[...] Will Abson on Alfresco Alfresco development, customisation and related themes      « Share Document Previews in Alfresco 4 [...]
blog_commenter
Active Member
just wanted to add;

thanks so much for these posts Will, succinct and extremely helpful for an Alf novice.

cheers



chris