Customizing Share Document Previews Will Abson Senior Integrations Engineer and Share Extras Project Lead

Upfront Notes These examples will work against Alfresco Community 4.0+ It is assumed you are familiar with Web Scripts and basic Share Development Defining, building and deploying your own projects as a JAR

Agenda Background on Document Previews Web Preview implementation Hands-on customization examples from Share Extras Media Viewers project

What are Document Previews? Rich view of the (document) content Found on the Document Details page May render the content itself or a rendition

Changes in Alfresco 4 More screen space for previews Support for more formats Configure and extend the previewers

The web-preview Component

web-preview Implementation Just a web script web-preview.get.desc.xml web-preview.get.config.xml web-preview.get.js web-preview.get.html.ftl web-preview.get.head.ftl (removed in 4.2) web-preview.get.properties (and localized variants) See the code in webapps/share/WEB- INF/classes/alfresco/site- webscripts/org/alfresco/components/preview

web-preview Implementation Client-side components Main Component Alfresco.WebPreview in web-preview.js web-preview.css Plugin implementations (4.0+)

web-preview Implementation From web-preview.get.html.ftl (v4.0) //<![CDATA[ new Alfresco.WebPreview("${el}").setOptions( { nodeRef: "${nodeRef}", name: "${node.name?js_string}", mimeType: "${node.mimeType}", size: "${node.size}", thumbnails: [ "${t}", ], pluginConditions: ${pluginConditionsJSON} }).setMessages(${messages}); //]]> ${msg("label.preparingPreviewer")}

web-preview Implementation From web-preview.get.html.ftl (v4.2.b)

web-preview Implementation As it was in Alfresco 3 Web Scripts / Spring Surf document-details YUI2 / Share JS Framework Alfresco.WebPrevi ew Web Tier Client-side (Web Browser) web- preview.get

web-preview Implementation New implementation in Alfresco 4 Web Scripts / Spring Surf document-details YUI2 / Share JS Framework Alfresco.WebPrev iew Plugins Web TierClient-side (Web Browser) web- preview.get Extend via client-side Plugin classes

OOTB WebPreview Plugins Flash FlashFox StrobeMediaPlayback WebPreviewer Non-Flash Audio Image Video See the code in directory webapps/share/components/preview

Question If we have multiple plugins which can render a particular file, how does Share decide which one to use?

Plugin Applicability and Ordering Plugin Applicability o Which plugins can be used in these circumstances? Plugin Ordering o Out of those plugins, which one should have preference over the others?

Plugin Applicability Statically configured o Via component configuration in web- preview.get.config.xml o Based on MIME type or renditions available o Results in a list of plugins to be tried for a content item

Sample Component Configuration StrobeMediaPlayback FlashFox Video Plugin applicability determined by element attributes Plugin configuration determined by element attributes

Plugin Applicability Statically configured o Via component configuration in web- preview.get.config.xml o Based on MIME type or renditions available o Results in a list of plugins to be tried for a content item Dynamically determined at run time o Plugins are given the opportunity to 'test' a content item o Based on any Javascript-testable condition, e.g. browser type/version, content properties o Plugins can return a ‘yes’ or a ‘no’ (plus a reason)

Plugin Applicability See the code in webapps/share/components/preview/w eb-preview.js

Plugin Ordering Taken from component configuration in web- preview.get.config.xml The first plugin which matches the static conditions and the dynamic test(s) is used. If an error occurs this is logged, then the next plugin is used

Plugin Configuration Also held in web-preview.get.config.xml Allows setting of plugin configuration attributes Change the behaviour of the plugin

Implementing Custom Plugins We need to define 1.Custom plugin class (JavaScript) 2.Localized strings for the UI 3.Presentation resources (images, CSS, etc.) We need to configure 1.Registration in component configuration web- preview.get.config.xml

Implementing Custom Plugins We need to define 1.Custom plugin class (JavaScript) 2.Localized strings for the UI 3.Presentation resources (images, CSS, etc.) We need to configure 1.Registration in component configuration web- preview.get.config.xml

Example: Inline PDF Viewer Displays a PDF directly in the browser within an iFrame Note: Not included in Media Viewers add-on, but 'Embed' plugin does a similar job Code: github.com/wabson/sample-preview-plugingithub.com/wabson/sample-preview-plugin File source/web/someco/components/preview/ PDF.js

Custom Plugin Class Pattern (function() { Alfresco.WebPreview.prototype.Plugins.PDF = function(wp, attributes) { this.wp = wp; this.attributes = YAHOO.lang.merge(Alfresco.util.deepCopy(this.attributes), attributes); return this; }; Alfresco.WebPreview.prototype.Plugins.PDF.prototype = { attributes: { }, report: function PDF_report() { }, display: function PDF_display() { return " My preview "’; } }; })();

Custom Plugin attributes Just an object literal All values are simple string values Default values should be specified in the prototype o Overrides in the component configuration XML will be merged in Don't forget the JSDoc!

Custom Plugin report() method Allows the plugin to dynamically test the document properties, system characteristics and plugin attributes, to test if it can be used Return null if it CAN be used Return a non-empty string value if it can't o Value should give the reason why it can't be used, e.g. "File is too big, only files < 2MB are supported"

Custom Plugin display() method Render the content display Return a String value to be used as the HTML mark-up, OR Return null you want to directly build the display using.innerHTML or DOM manipulation

Example: Inline PDF Viewer The usual Share object prototype approach is used Property attributes can be used to customize behaviour Function report() returns null if the plugin can be used or a string if not indicating the reason Function display() returns a string containing HTML markup or null if Dom manipulation has already been used

Example: Inline PDF Viewer To include the JavaScript file in the HTML document, we can use an extensibility module See file config/alfresco/site- webscripts/com/someco/customization/sample- preview-plugin/web-preview.get.head.ftl Note: in 4.2,.head.ftl webscript templates are deprecated, use directive in.html.ftl template instead. See v4- 2-config branch for new code.

Example: Inline PDF Viewer To include the JavaScript file in the HTML document, we can use an extensibility module See file config/alfresco/site- webscripts/com/someco/customization/sample- preview-plugin/web-preview.get.head.ftl Note: in 4.2,.head.ftl webscript templates are deprecated, use directive in.html.ftl template instead. See v4- 2-config branch for new code.

Implementing Custom Plugins We need to define 1.Custom plugin class (JavaScript) 2.Localized strings for the UI 3.Presentation resources (images, CSS, etc.) We need to configure 1.Registration in component configuration web- preview.get.config.xml

Example: Inline PDF Viewer We can also use our extensibility module to add additional message labels See file config/alfresco/site- webscripts/com/someco/customization/sample- preview-plugin/web-preview.get.properties # Error messages PDF.tooLargeFile=The PDF was too large to display. File {0} was {1}, but must be less than {2}.

Implementing Custom Plugins We need to define 1.Custom plugin class (JavaScript) 2.Localized strings for the UI 3.Presentation resources (images, CSS, etc.) We need to configure 1.Registration in component configuration web- preview.get.config.xml

Example: Inline PDF Viewer To include the a custom CSS file in the HTML document, we can use re-use the extensibility module See file config/alfresco/site- webscripts/com/someco/customization/sample- preview-plugin/web-preview.get.head.ftl Note: in 4.2,.head.ftl webscript templates are deprecated, use directive in.html.ftl template instead

Implementing Custom Plugins We need to define 1.Custom plugin class (JavaScript) 2.Localized strings for the UI 3.Presentation resources (images, CSS, etc.) We need to configure 1.Registration in component configuration web- preview.get.config.xml

Example: Inline PDF Viewer Lastly we must tell the web-preview.get component to use the PDF plugin! To do this add the following to the element in your overidden web-preview.get.config.xml PDF But instead we’re going to use a second extensibility module to add the configuration automatically This can be done by the developer (4.2+)! See file config/alfresco/site- webscripts/com/someco/customization/sample-preview-plugin- config/web-preview.get.js

Demo

Example: pdf.js Viewer

Summary The Web Preview component is an important part of Share Alfresco 4 allows us to display our content in new and interesting ways o Or, display content that is not supported OOTB We can re-use our existing Share customization skills to bring in powerful tools such as pdf.js

More Information extras/wiki/MediaViewers hare-document-previews-in-alfresco-4/ edia-previews-is-dead-long-live-media-viewers/

Questions?