Transcript Registration in component configuration web-preview.get

Customizing Share Document Previews
Will Abson
Senior Integrations Engineer and Share Extras
Project Lead (@wabson)
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/WEBINF/classes/alfresco/sitewebscripts/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)
<#if node??>
<#assign el=args.htmlid?html>
<#if (node?exists)>
<script type="text/javascript">//<![CDATA[
new Alfresco.WebPreview("${el}").setOptions(
{
nodeRef: "${nodeRef}",
name: "${node.name?js_string}",
mimeType: "${node.mimeType}",
size: "${node.size}",
thumbnails: [<#list node.thumbnails as t>"${t}"<#if (t_has_next)>, </#if></#list>],
pluginConditions: ${pluginConditionsJSON}
}).setMessages(${messages});
//]]></script>
</#if>
<div id="${el}-body" class="web-preview">
<div id="${el}-previewer-div" class="previewer">
<div class="message"><#if (node?exists)>${msg("label.preparingPreviewer")}</#if></div>
</div>
</div>
</#if>
web-preview Implementation
From web-preview.get.html.ftl (v4.2.b)
<@standalone>
<@markup id="css" >
<#-- CSS Dependencies -->
</@>
<@markup id="js">
<#-- JavaScript Dependencies -->
</@>
<@markup id="widgets">
<#if node??>
<@createWidgets group="${dependencyGroup}"/>
</#if>
</@>
<@markup id="html">
<@uniqueIdDiv>
<#if node??>
<#assign el=args.htmlid?html>
<div id="${el}-body" class="web-preview">
<div id="${el}-previewer-div" class="previewer">
<div class="message"></div>
</div>
</div>
</#if>
</@>
</@>
</@standalone>
web-preview Implementation
As it was in Alfresco 3
Web Tier
document-details
Client-side (Web
Browser)
Alfresco.WebPrevi
ew
webpreview.get
Web Scripts / Spring Surf
YUI2 / Share JS
Framework
web-preview Implementation
New implementation in Alfresco 4
Web Tier
document-details
Client-side (Web
Browser)
Alfresco.WebPrev
iew
Plugins
webpreview.get
Web Scripts / Spring Surf
YUI2 / Share JS Framework
Extend via client-side Plugin classes
OOTB WebPreview Plugins
Flash
Non-Flash
Flash
Audio
FlashFox
Image
StrobeMediaPlayback
Video
WebPreviewer
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
o
o
Via component configuration in webpreview.get.config.xml
Based on MIME type or renditions available
Results in a list of plugins to be tried for a content item
Sample Component Configuration
Plugin applicability determined by <condition> element attributes
Plugin configuration determined by <plugin> element attributes
<config>
<plugin-conditions>
<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>
<condition mimeType="video/m4v" thumbnail="imgpreview”>
...
</condition>
...
</plugin-conditions>
<config>
Plugin Applicability
•
Statically configured
o
o
•
o
Via component configuration in webpreview.get.config.xml
Based on MIME type or renditions available
Results in a list of plugins to be tried for a content item
Dynamically determined at run time
o
o
o
Plugins are given the opportunity to 'test' a content item
Based on any Javascript-testable condition, e.g.
browser type/version, content properties
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 webpreview.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 webpreview.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 webpreview.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-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 "<p>My preview</p>"’;
}
};
})();
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 <element>.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/samplepreview-plugin/web-preview.get.head.ftl
Note: in 4.2, .head.ftl webscript templates are deprecated,
use <markup> directive in .html.ftl template instead. See v42-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/samplepreview-plugin/web-preview.get.head.ftl
Note: in 4.2, .head.ftl webscript templates are deprecated,
use <markup> directive in .html.ftl template instead. See v42-config branch for new code.
<#include "/org/alfresco/components/component.head.inc">
<@script type="text/javascript"
src="${page.url.context}/res/someco/components/preview/PDF.js"></@script>
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 webpreview.get.config.xml
Example: Inline PDF Viewer
•
We can also use our extensibility module to add
additional message labels
•
See file config/alfresco/sitewebscripts/com/someco/customization/samplepreview-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 webpreview.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/samplepreview-plugin/web-preview.get.head.ftl
Note: in 4.2, .head.ftl webscript templates are deprecated,
use <markup> directive in .html.ftl template instead
<#include "/org/alfresco/components/component.head.inc">
<@script type="text/javascript"
src="${page.url.context}/res/someco/components/preview/PDF.js"></@script>
<@link rel="stylesheet" type="text/css"
href="${page.url.context}/res/someco/components/preview/PDF.css" />
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 webpreview.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 <plugin-conditions> element in
your overidden web-preview.get.config.xml
<condition mimeType="application/pdf">
<plugin>PDF</plugin>
</condition>
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/sitewebscripts/com/someco/customization/sample-preview-pluginconfig/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
https://github.com/wabson/sample-preview-plugin
http://code.google.com/p/shareextras/wiki/MediaViewers
http://blogs.alfresco.com/wp/wabson/2012/04/11/s
hare-document-previews-in-alfresco-4/
http://blogs.alfresco.com/wp/wabson/2012/07/04/m
edia-previews-is-dead-long-live-media-viewers/
Questions?
http://twitter.com/wabson