If you’re not familiar with the underlying pdf.js project then you should know that it provides a means of direct rendering of PDF content items using HTML5 and JavaScript in the web browser, with no requirement from additional client-side plugins such as Flash.

Combined with the ability of the Alfresco repository to transform just about any standard document into PDF format, we think this provides a compelling reason to try the Media Viewer add-on if you have not done so before.

An initial version of the PdfJs viewer shipped in the Media Viewers 2.0 release for Alfresco 4, and version 2.5 which we’re releasing today builds on that with support for Alfresco 4.2 while also maintaining backwards compatible with the 4.0 and 4.1 Alfresco product lines.

There’s so much in this release that it felt like much more than a v2.1 release and 2.5 seemed much more appropriate. You can read on for more details of these exciting new capabilities, or go straight to the download, installation and configuration instructions to try it out today.

Easy Configuration

The first thing you’ll notice when enabling the add-on using Share’s Module Deployment console is that additional modules have been added, which provide the configuration needed to bind the viewer into the document details page.

Unless you want a specific custom configuration, you can just enable the new PdfJs Configuration module (in addition to the existing PdfJs Viewer module), click Apply Changes and you should see PDF documents will now use the new viewer. You no longer need to edit your web-preview.get.config.xml file although if you’ve made changes there they will continue to be respected.

Persistent View Settings

Can’t see the text clearly? You can use the zoom controls in the viewer to zoom in, our out if you want to see more. Or pick a preset from the drop-down and the zoom will be auto-calculated.

The next time you come back to the document, these settings – plus the page number you were on – will be remembered.

Powerful Search

Use the Search button in the toolbar or Ctrl+F (Cmd+F on MacOS) to search through the document contents for a particular item of text. You can easily step through the matches one by one, or highlight all matches found.

When you’ve found what you’re after, you can copy the relevant text to the clipboard in order to include it somewhere else, for example in an e-mail.

The feature I like the most will make you wonder how you lived without it before, if you’ve ever searched for a document in Alfresco and then struggled to find the reference to that term in the document itself.

Now, the viewer detects that you have clicked through from the search page, and automatically searches for and highlights the first match of that term. Just hit Enter to continue through any further matches, or Escape to close the search dialog.

Link to Document

The Link button in the toolbar generates a link to the document, or even to a specific page in the document, that you can send to co-workers. If you want them to review Slide 24 in your presentation then simply send them straight there.

Improved Sidebar

You can click the button on the left of the toolbar to toggle the side bar on and off. The side bar shows a thumbnail view of all pages in the document by default and can also show an outline of the document structure if available in the file.

Presentation Mode

At DevCon last November Jared neatly showed how you can use the the new Google Docs integration to deliver a presentation directly from your web browser using Google Drive’s presentation mode, but with the PdfJs viewer you can now do the same thing directly from the Document Details page.

Just click Ctrl+Enter (or Cmd+Enter on MacOS) to go full-screen, then use the left and right arrow keys to move between your slides (the arrow keys will also work in the normal Document Details view).

Document Viewer Dashlet

Just like Site Admins can use the Wiki dashlet to add a selected page to a site dashboard, the Document View dashlet supplied with the add-on allows you to display any chosen document on the dashboard.

The dashlet works well with the PdfJs viewer, but will also work with the others supplied by the add-on or the base viewers supplied with Share (yes, that includes the Flash document viewer, if you really want).

Password-protected PDFs

Viewing password-protected PDFs is no longer a problem with the PdfJs viewer. You will be promoted for the password required to open the file and once supplied the viewer will work as normal.

Lots More

Of course there are many other improvements that you can’t see directly, but that you will benefit from. Peter has been working tirelessly to keep the version of the pdf.js library up-to-date, ensuring that we stay up to date with the improvements in performance and compatibility that the latest versions now provide. We have also improved the performance of page rendering within the dashlet code itself, with improved lazy rendering of all page and thumbnail content.

And of course PdfJs is not the only viewer in the add-on. The Flash-based audio and video players are still supplied, the Embed viewer offers a compelling Flash-free alternative for IE users not on IE 10 who have the Adobe Reader or another PDF plugin installed and the Prettify viewer is great at syntax highlighting any code stored in Alfresco.

Feedback

Like all Share Extras add-ons, we welcome constructive feedback to help us to deliver the next version of Media Viewers. Please use the Issues section on the project to report specific technical issues or ideas for enhancements, or general feedback can be left as comments below.

He also pointed out something that may be obvious to some of you, but it had not occurred to me! When you add a new plugin to Alfresco’s web preview component – as this add-on does – then that is also available on the Quick Share page.

If you’re not familiar with Quick Share it is a great new feature originally in Cloud and now in Community 4.2, providing public sharing of documents via a short URL, which can be easily used by clicking the Share action directly above the document preview.

The result is pretty powerful, since using an iFrame you can easily add those embedded documents to an intranet page or public web page – or just link to the items direct as Peter has done in his post. In fact Sergio Buitrago and I worked on this implementing this very thing as a WordPress plugin at the Berlin DevCon Hackathon last month!

Latest Changes in PdfJs Viewer

It’s worth mentioning that you can try out the features Peter mentions by grabbing the project’s latest source from trunk. In particular, here are two new features that are hot off the press in the PdfJs viewer:

• Perform a search in Share and click through to a PDF file or office document. You should see that the search function is automatically invoked for the term you searched for in the previous page, and highlights the first match.
• If you are using the latest available Firefox or Chrome browsers, you can enter full-screen mode by pressing Ctrl+F on the keyboard. Now you can deliver PowerPoint presentations directly from Share itself!

We are still in the process of finalising the 2.1 release of the Media Viewers add-on, so if you have feedback please file an issue on the Share Extras project site.

Last week kicked off with a full-day hackathon building on top of Alfresco, facilitated by Nathan McMinn, which I would recommend to anyone who has worked with Alfresco before and is interested in expanding  their horizons. This was about people coming together to work collectively on building something in a day, and the format worked fantastically well. I believe Nathan will be posting soon on what was produced in the session.

As always John and John kicked off the main sessions with the high-level view of Alfresco, seamlessly mixing open source content management with tales from the wider IT industry and a satirical take on current global politics. If you’re interested in any of those things, it’s a must see.

I didn’t get to see as many technical sessions as I have done in previous years, but the quality of those I did see really stood out. In particular:

• The public API live coding (part 1, part 2) session by Peter, Gethin and Steve was a great opportunity to get to grips with Alfresco Cloud’s new public API, and like the hackathon it felt great to have some working code at the end, much aided by the sample project provided on the USB sticks.
• Expanding on the idea of developing your own projects, Gab Columbro’s talk on the long-awaited and brand-new Maven SDK was a highlight as much for the content as for Gab’s style, although you’ll want to do some background reading on Maven and how it differs from more traditional build tools before you use it for real.
• On the second day I attended Dave and Erik’s Share Customizations Live session where they demonstrated, through the use of site presets and extensibility modules, some concrete examples which showed them taking a vanilla Share and hacking away until it was barely recognisable. What was interesting was how the mechanisms for doing this have improved over the last year, and the point that often it is just as useful to remove non-required OOTB functions as it is to add new ones, which the framework makes easy.
• Jared’s talk on our own Integrations team and what we’ve been up to over the last year (or six months in my case), and Nathan’s overview of PDF Toolkit and the latest new features, based on the work he’s done recently building on Jared’s earlier work. If you’re interested in integrating Share with external systems and working with PDF content you’ll find both sessions really useful.

Overall what stood out this year for me was the diversity of sessions available, not only in terms of topics but in their formats as well. There were less of the traditional-style PowerPoint-only type of sessions and more richer interactive sessions.

I experimented with a local Git repo in my own Developing Great Dashlets talk, switching between eight different branches of my example project to show progressively adding more features to an at-first-basic dashlet. It was great to see others experimenting in even more ways and adding more diversity to the two days.

If you’re attending the event in San Jose you’re I’ll be presenting the same dashlets “Zero to Hero” talk on Day 1 and Day 2, plus a topic on pimping the Document Details screen with your own document viewers and a lightning talk on the fantastic Leaflet. Do join if you can!

The integration allows LibreOffice to connect to a remote Alfresco server in order to open and save documents. This is a feature Microsoft Office has had for a long time, although limited to SharePoint-compatible servers (including Alfresco, via our SharePoint protocol support!). Now you can do the same thing with LibreOffice, via the magic of CMIS.

The first thing to do is to enable LibreOffice’s experimental features within the Preferences dialogue.

After you’ve confirmed that change, you can open a file stored in Alfresco using the standard Open menu. When the file browser loads, you should notice a small button next to the location drop-down menu labelled with an ellipsis (…).

Clicking that button allows you to add a server. LibreOffice supports a range of server types, including the CMIS AtomPub service provided by Alfresco.

First you must enter a name for the server – I entered ‘Alfresco’ – and select the server type. If you do not see CMIS (Atom Binding) in the list then check to ensure that you have LibreOffice 3.6+ and that you have enabled Experimental Features.

The binding URL for Alfresco 4.2 will be something like http://localhost:8080/alfresco/cmisatom if you are running a local instance. I found that if I used the legacy CMIS URL below /alfresco/service (or the short form /alfresco/s) then document saves did not work, but the newer URL worked great.

Next is the slightly tricky part, entering the CMIS repository ID. Your Alfresco instance will only expose one repository, but other CMIS providers provide others, and so you need to enter this.

Hitting the repository binding URL directly will give you the ID, but unfortunately the non-standard document MIME type returned means it does not open directly in a web browser. You could save the response to disk and then use a text editor to view its contents, but I found it easier to use curl at the command line, together with less.

curl -u admin:admin http://localhost:8080/alfresco/cmisatom | less

In the response, do a search for the string repositoryId and within that element you should see a GUID value which you can copy and paste into the dialogue in LibreOffice.

The last item you need to enter is the username that will be used to access Alfresco (you will enter the password later).

You should now have the full set of information needed to add the server. Click OK, and it should be added to the side panel on the left of the Open dialogue.

You can navigate through the folders below the repository’s Company Home space, and open any compatible document. I used the Word documents located under Sites > swsdp > documentLibrary > Meeting Notes, which opened perfectly.

You can make any modifications, hit Save and the content will be automatically saved back into Alfresco.

I also tried creating a new document from the New menu, and was able to save the document back to a folder Alfresco via the Save As dialogue. I found I needed to set the correct MIME type for new documents back in Alfresco Share to get previews to work, but this could easily be done using a rule.

All in all not bad for an experimental feature, and it will be interesting to see if this makes it into LibreOffice 3.7 for real.

Notice Dashlet

This dashlet may already be familiar to some of you who have used the add-ons available from Share Extras.

The Notice Dashlet allows site managers to add a custom notice that will be displayed to all site members, and allows this to be done directly from the dashlet itself. Now you no longer need to create a wiki page just to display some basic text on the dashboard!

New Bubbling event for dashlet resize notifications

If you’ve developed any complex dashlets to render maps or other graphics, you’ll appreciate that it’s important to know the vertical height of the dashlet when you render your content. That is easy to get via the Dom or using YUI2′s YAHOO.util.Dom.getRegion() function, but what if the user resizes the dashlet?

Now the resizer module can notify your listeners via the new Bubbling event dashletResizeEnd. This is fired when the resizing has been completed and passes a number of parameters in the event arguments, including the new height of the dashlet, the dashlet element and component IDs and the Dom element representing the dashlet. To subscribe to the event, simply define a new custom function in your dashlet class prototype and bind it to the event in the dashlet class constructor, e.g.

YAHOO.Bubbling.on("dashletResizeEnd", this.onDashletResize, this);

In your custom function you can then take any further action which is necessary, e.g. informing a map instance that the element bounds have changed.

More options for Data List actions

The ability to add custom UI actions to Share’s Document Library is well documented and the add-ons site has a number of extensions which utilize this capability. But did you know the same thing can be done for data list items?

Until now the number of actions that can be displayed in the UI has been effectively capped at three. But now you can easily add new actions of your own there too. Thanks to the work done by Dave Draper these definitions can easily be inserted into the application by using an extensibility module to customize the datagrid.get and actions-common.get components.

As an example, the following code could be used to add the Sample Datalist Action provided by Share Extras to your datalist items, as part of an extensibility module.

if (model.widgets)
{
   for (var i = 0; i < model.widgets.length; i++)
   {
      var widget = model.widgets[i];
      if (widget.id == "DataGrid")
      {
         // These two lines only needed if you want to show the action in the 'actions' cell,
         // otherwise a 'More actions' menu will be created to display it.
         //widget.options.splitActionsAt = 4;
         //widget.options.actionsColumnWidth = 105; // splitActionsAt * 25 + 5
         // Add the action definition - this will be action-specific
         model.actionSet.push({
            id: "onActionSample", // Change to match your handler function name
            type: "action-link",
            permission: "",
            href: "",
            label: "actions.datalist.mycustom" // Change to match your custom label in datagrid.get.properties
         });
      }
   }
}

If you have attempted to customize the existing Edit and Create data list actions with your own custom form configuration, then you may also appreciate the ability to increase the width of the modal dialogs used here, which previously were fixed-width.

Better handling of missing custom previewers

This will mainly be of interest to developers and administrators working with custom viewers in the web preview component, such as the pdf.js viewer in Share Extras’s Media Viewers add-on, and is a topic which I’ll be talking about in San Jose next month.

Previously, if the files implementing the viewer were unavailable for some reason then an error would be thrown in the client-side component. With this change the component now logs that the viewer class could not be found, and this will also be printed on the screen if no other viewers can be found.

The instructions on the wiki are pretty comprehensive, and together with the text file provided in the Solr integration package provide all the info you need to understand the process of creating your own keys and certificates for local testing.

After I stepped through the complete procedure documented there, with some slight modifications to avoid the interactive prompting, I found I had a set of commands which I could use in order to repeatedly re-generate a set of keys inside each installation directory on my system.

The first section in the following listing could be placed inside your .bash_profile file, and this is recommended to ensure that the password values you choose to use are not captured in your command history or in your terminal. The commands after that should be used repeatedly against each Alfresco installation you wish to generate keys and certificates for.

# The subject name of the key used to sign the certificates
REPO_SUBJECT_NAME="/C=GB/ST=UK/L=Maidenhead/O=Alfresco Software Ltd./OU=Unknown/CN=Alfresco Repository"
# The repository server certificate subject name, as specified in tomcat/conf/tomcat-users.xml with roles="repository"
REPO_CERT_DNAME="CN=Alfresco Repository, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB"
# The SOLR client certificate subject name, as specified in tomcat/conf/tomcat-users.xml with roles="repoclient"
SOLR_CLIENT_CERT_DNAME="CN=Alfresco Repository Client, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB"
# The number of days before the certificate expires
CERTIFICATE_VALIDITY=36525
# Keystore password
KEYSTORE_PASSWORD=custompassword
BROWSER_KEYSTORE_PASSWORD=alfresco

openssl genrsa -des3 -passout pass:$KEYSTORE_PASSWORD -out ca.key 1024
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -passin pass:$KEYSTORE_PASSWORD -subj "$REPO_SUBJECT_NAME" -passout pass:$KEYSTORE_PASSWORD

# Generate Alfresco Repository SSL keystores
keytool -genkey -alias 'ssl.repo' -keyalg RSA -keystore ssl.keystore -storetype JCEKS -dname "$REPO_CERT_DNAME" -storepass "$KEYSTORE_PASSWORD" -keypass "$KEYSTORE_PASSWORD"
keytool -keystore ssl.keystore -alias 'ssl.repo' -certreq -file repo.csr -storetype JCEKS -storepass "$KEYSTORE_PASSWORD"
openssl x509 -CA ca.crt -CAkey ca.key -CAcreateserial -req -in repo.csr -out repo.crt -days "$CERTIFICATE_VALIDITY" -passin pass:$KEYSTORE_PASSWORD
keytool -import -alias 'alfresco.ca' -file ca.crt -keystore ssl.keystore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt
keytool -import -alias 'ssl.repo' -file repo.crt -keystore ssl.keystore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt
keytool -importkeystore -srckeystore ssl.keystore -srcstorepass $KEYSTORE_PASSWORD -srcstoretype JCEKS -srcalias 'ssl.repo' -srckeypass $KEYSTORE_PASSWORD -destkeystore browser.p12 -deststoretype pkcs12 -deststorepass $BROWSER_KEYSTORE_PASSWORD -destalias repo -destkeypass $BROWSER_KEYSTORE_PASSWORD
keytool -import -alias alfresco.ca -file ca.crt -keystore ssl.truststore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt

# Generate Alfresco Solr SSL keystores
keytool -genkey -alias 'ssl.repo.client' -keyalg RSA -keystore ssl.repo.client.keystore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -keypass "$KEYSTORE_PASSWORD" -dname "$SOLR_CLIENT_CERT_DNAME"
keytool -keystore ssl.repo.client.keystore -alias 'ssl.repo.client' -certreq -file ssl.repo.client.csr -storetype JCEKS -storepass $KEYSTORE_PASSWORD
openssl x509 -CA ca.crt -CAkey ca.key -CAcreateserial -req -in ssl.repo.client.csr -out ssl.repo.client.crt -days "$CERTIFICATE_VALIDITY" -passin pass:$KEYSTORE_PASSWORD
keytool -import -alias 'alfresco.ca' -file ca.crt -keystore ssl.repo.client.keystore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt
keytool -import -alias 'ssl.repo.client' -file ssl.repo.client.crt -keystore ssl.repo.client.keystore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt
keytool -import -alias 'alfresco.ca' -file ca.crt -keystore ssl.repo.client.truststore -storetype JCEKS -storepass $KEYSTORE_PASSWORD -noprompt

# Copy files
cp ssl.keystore ssl.truststore browser.p12 data/keystore/
cp ssl.repo.client.keystore ssl.repo.client.truststore solr/workspace-SpacesStore/conf
cp ssl.repo.client.keystore ssl.repo.client.truststore solr/archive-SpacesStore/conf

# Remove temporary files
rm repo.csr ca.key ca.crt repo.crt ssl.keystore browser.p12 ssl.truststore ssl.repo.client.csr ssl.repo.client.crt ssl.repo.client.keystore ssl.repo.client.truststore

Note that this will not update the Alfresco and Solr configuration with the password you choose for the keystores – you must do this separately in your alfresco-global.properties and in the properties file associated with each Solr core, as detailed in the Solr installation guide.

Lastly, this procedure should not be used in any public-facing or production instances, it is intended to be used in development environments only.

However, one problem has plagued me since I started using the Homebrew-installed version of ImageMagick in conjunction with my local Alfresco installs, with errors such as this in the logs

 2012-08-02 10:20:10,547  DEBUG [transform.magick.AbstractImageMagickContentTransformerWorker] [main] org.alfresco.service.cmr.repository.ContentIOException: 07020000 Failed to perform ImageMagick transformation: 
Execution result: 
   os:         Mac OS X
   command:    [/usr/local/bin/convert, /Users/wabson/Development/projects/share-extras-2/software/tomcat/temp/Alfresco/ImageMagickContentTransformerWorker_init_source_4067880520213204197.gif[0], /Users/wabson/Development/projects/share-extras-2/software/tomcat/temp/Alfresco/ImageMagickContentTransformerWorker_init_target_7684811633126657147.png]
   succeeded:  true
   exit code:  133
   out:        
   err:        dyld: Symbol not found: __cg_jpeg_resync_to_restart
  Referenced from: /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/ImageIO
  Expected in: /usr/local/lib/libjpeg.8.dylib
 in /System/Libra

This frustrated me for a while. It happened every time Alfresco tried to call convert in order to effect an image transform – for instance generating doclib thumbnails – but running the exact same command at a bash prompt worked fine.

Various internet posts all pointed to the environment in which ImageMagick is run as being the cause for such problems. It seemed the environment variable DYLD_LIBRARY_PATH in particular was known to cause problems on OS X, but checking /etc/profile, /etc/bashrc and the custom alfresco.sh script I use to start up Alfresco (included in my Tomcat packages) did not yield any trace of such a variable.

Finally I found a comment in ALF-13452, which led me to check the Spring config within the thirdparty subsystem, responsible for starting up ImageMagick.

   <bean id="transformer.worker.ImageMagick">
      <property name="mimetypeService">
         <ref bean="mimetypeService" />
      </property>
      <property name="executer">
         <bean name="transformer.ImageMagick.Command">
            <property name="commandsAndArguments">
               <map>
                  <entry key=".*">
                     <list>
                        <value>${img.exe}</value>
                        <value>${source}</value>
                        <value>SPLIT:${options}</value>
                        <value>${target}</value>
                     </list>
                  </entry>
               </map>
            </property>
            <property name="processProperties">
               <map>
                  <entry key="MAGICK_HOME">
                     <value>${img.root}</value>
                  </entry>
                  <entry key="DYLD_LIBRARY_PATH">
                     <value>${img.dyn}</value>
                  </entry>
                  <entry key="LD_LIBRARY_PATH">
                     <value>${img.dyn}</value>
                  </entry>
               </map>
            </property>
            <property name="defaultProperties">
               <props>
                  <prop key="options"></prop>
               </props>
            </property>
         </bean>
      </property>
     ...

There it was. The subsystem itself was setting up a few environment variables before firing up the external process, and these were defined in processProperties. One was the DYLD_LIBRARY_PATH variable.

The solution was trivial. I copied the Spring config in tomcat/webapps/alfresco/WEB-INF/classes/alfresco/subsystems/thirdparty/default/imagemagick-transform-context.xml into tomcat/shared/classes/alfresco/extension/subsystems/thirdparty/default/default/imagemagick-transform-context.xml as per the subsystems docs on overriding beans, and commented out the offending <entry> element.

mkdir -p tomcat/shared/classes/alfresco/extension/subsystems/thirdparty/default/default/
cp tomcat/webapps/alfresco/WEB-INF/classes/alfresco/subsystems/thirdparty/default/imagemagick-transform-context.xml tomcat/shared/classes/alfresco/extension/subsystems/thirdparty/default/default/
vim tomcat/shared/classes/alfresco/extension/subsystems/thirdparty/default/default/imagemagick-transform-context.xml

The result – image conversions now work perfectly in my local dev environment using the Homebrew-installed version of ImageMagick.

Share Extras will be moving to a new platform in the next few weeks. The new platform will be GitHub, with the version control obviously provided by Git instead of Subversion, which is used at present.

There are many reasons for moving to Git from Subversion. I’ve spent a while reviewing the project issue list this week and it’s clear to me that there are many enhancement requests which may not be appropriate to make in the main Extras code base, or are simply not achievable within the project due to people’s time constraints.

Git will enable the wider community to fork individual any add-on as they feel the need to. I hope this will lead to more contributions back to the main project and foster greater collaboration (and perhaps a bit of competition?) with others.

Specifically, there is also the need to improve on the localisation of add-ons in a consistent manner, and there are some great tools available for doing that based on Git.

Whilst I had originally intended to simply migrate to a new Git VCS within Google Code, the frequent downtime and increasingly poor feature set and user interface when compared to other providers has led me to conclude that it is not a viable platform for future development.

In contrast, GitHub supports the notion of projects within an overall organisation much better (I have already registered Share Extras as an organisation) and has some great options for improving our documentation using cool standards such as Markdown.

I propose to migrate the current trunk codeline (and perhaps the 1.0 branch should time allow) at the end of August. There are several things that committers need to do before then, in order to help make it a success, such as ensuring that they have a README.md file in all their projects (this will become the main source of documentation, rather than the wiki), and helping to close down any issues that remain open on Google Code (issues will not be migrated over).

As always, if you have any feedback, please let me know. Otherwise I will be in touch with the main committers separately in the coming week or so.

I mentioned at the end of that post that there were some new examples of custom viewers coming in Share Extras and I’m excited that we’re now ready to release them on the site.

Peter Löfgren had the great idea of using the pdf.js project to perform direct rendering of document content in the web browser using HTML5. I’d already started work on some simpler examples of custom viewers, and on refining the Flash audio/video players that Share Extras previously provided for Alfresco 3.3/3.4.

The result is what we’re calling the Media Viewers add-on. This bundles up a total of six viewer implementations designed to show different ways of implementing custom document views, both with and without Flash.

• PdfJs displays documents, presentations and any other file capable of being transformed to PDF in-line in the web browser using the excellent pdf.js viewer, which uses the power of HTML5 to remove Share’s Flash dependency for document viewing.

  The viewer supports a number of features not directly supported by the Flash document previewer, such as a sidebar with thumbnail, outline and search views, bookmarking of individual pages of a document, and will remember the page number and zoom level of previous documents that you have viewed.

  

• FLVPlayer and MP3Player display compatible audio and video files respectively, within the web-browser using the open source FLV Player and MP3 Player media players by neolao. Based on the content’s MIME type, the updated component automatically chooses the appropriate previewer to use.

  While similar to the Flash players provided by Share out-of-the-box, these implementations allow advanced customization of the player via configuration and if FFmpeg is installed, will fire up a transformation to allow viewing of non-H264/FLV video and non-MP3 audio. The user is informed when conversion is in progress and the screen automatically updates when the content can be viewed.

• Embed uses an in-line iFrame to embed the content itself directly inside the web page. It is suitable for use with content types that can be viewed directly within the web browser such as plain text and PDF, with the Chrome or Acrobat plugins installed. Again, this can be used to avoid the use of the Flash previewer for some clients.
• Prettify allows formatted code, mark-up and other supported text formats to be displayed in directly in the document and uses the google-code-prettify project to provide an in-line browser-based view with syntax highlighting.

  

• WebODF is an EXPERIMENTAL viewer which uses the AGPL-licensed WebODF project to display ODF content directly in the web browser.

  WebODF cannot be distributed with the add-in itself, so in order to use it you must also download the latest JAR file from the supporting share-webodf project and install it in the same way as the main media-viewers JAR file.

What’s most exciting is that we’re building on top of some great projects such as google-code-prettify, WebODF and pdf.js, that are evolving at a fast pace and changing the way that documents are viewed in a browser environment.

There is plenty more information including download links on the main Media Viewers project page on Share Extras. Please try it out, let us know what you think and help us to improve this collection.

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.

Web preview component in Alfresco 4 for a PowerPoint Presentation

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.

Web preview component in Alfresco 4 for a JPEG image

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.