Preview

What is the visual preview feature

Olympic Charter 2010

The visual preview feature provides a user-friendly way of presenting files, such as PDFs or images, in any HTML page. It automatically adds a thumbnail preview of the file (as long as its type is supported by Multivio) and allows instant access to its content with the Multivio viewer interface, or a simple file download, as usual. (See the example at the right-hand side.)

This feature can be easily added to any web page, using the setup procedure described below. For improved control, read the advanced configuration section further down.

Setup procedure

[Requires basic html knowledge]

The visual preview is set up by adding a <a> HTML tag to the host page, configured in a specific way. Then, whenever the host page has finished loading in the user's browser, a piece of JavaScript code (the enabler script) is automatically executed, that will modify the content of the tag in order to achieve the desired effect.

Basic example

The easiest way to set it up is to add an <a> tag to the HTML page (or to modify an existing one), in order to apply the visual preview to a file, as follows:

<a class="multivio-preview" href="http://my.file.url...">My label</a>

The href value and the label should be adapted to the context at hand. Note that href must contain an absolute URL for the preview and the Multivio interface to work.

Finally, some static HTML related to the enabler script must be added to the page, as well. Just copy the two code blocks below and paste them verbatim into the HTML page. They can be placed anywhere in the page, for example at the end, before the </body> closing tag. What is important is to keep the order between them.

HTML tags that include required JavaScript and CSS code:

<!-- Enable Multivio preview -->
<!-- jQuery and jQuery-UI JS libraries -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js" type="text/javascript"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/jquery-ui.min.js" type="text/javascript"></script>
<!-- RERO's custom jQuery-UI theme -->
<link rel="stylesheet" href="http://demo.multivio.org/css/rero-theme/jquery-ui-1.8.16.custom.css" type="text/css" />
<!-- Multivio preview's custom CSS and JS -->
<link rel="stylesheet" href="http://demo.multivio.org/css/1.0/multivio-min.css" type="text/css" />
<script src="http://demo.multivio.org/js/1.0/multivio-dev.js" type="text/javascript"></script>

Execution of the enabler script:

<!-- preview enabler script - it applies the required HTML transformations to the page -->
<script type="text/javascript">
$(document).ready(function () {
  $('a.multivio-preview').enableMultivio({
    method: 'overlay',
    downloadButton: true,
    quickViewButton: true,
    previewAttr: 'href'
  });
});
</script>

This script will transform the original HTML in a suitable way. Among other things, it will wrap the original <a> tag with a new <span> tag.

Advanced configuration

How to configure the <a> tag

The visual preview feature allows a fair amount of configuration, in order to adapt to specific needs. The basic example above can be extended with additional configuration possibilities.

Here's the full set of available options for the <a> tag in the context of the visual preview feature:

<a title="My title"
    href="http://my.file.url..."
    data-multivio-options="url=http://my.file.or.doc.url..."
    data-multivio-preview="url=http://my.preview.file.url..."
    class="my-hook-class-name">
  My label
</a>

The meaning of the different options is the following:

title
The regular HTML title attribute (for example, to appear in the mouse hover tooltip)
href
The regular HTML href attribute; if the browser is not JavaScript-enabled (in which case the Multivio preview will not be enabled either), this attribute takes on its usual role
data-multivio-options
This custom attribute contains the options that are passed to Multivio, verbatim; it must contain at least the url parameter, but it may contain any of the accepted parameters of the Multivio client; see examples below
data-multivio-preview
A custom attribute whose role is to specify the file used to generate the preview thumbnail. This is very useful, as it allows a different file to be used specifically for the preview (e.g. an image). Sometimes this attribute is even required, such as when the preview is applied to a composite document (one that contains several files). In that case, one of those files must be chosen and indicated explicitly for the preview. Since the content of this attribute is copied verbatim when the corresponding service is requested to Multivio's server, it is possible to provide additional options, such as page number or rotation angle.
However, if it's not necessary to use a different URL for the preview, it is possible to instruct the script to obtain it from another attribute, namely href; see previewAttr in the available options of the enableMultivio() function below.
class
This is a regular CSS class name. Its value must be combined with the selector given in the call to the enabler script. See the corresponding explanation below.

Hence, the preview widget handles three different URLs:

  • the default download URL (in href), used only when JavaScript is not enabled
  • the URL of the content to be used for the thumbnail (given as url=... in data-multivio-preview)
  • the URL of the actual content to be displayed with the Multivio viewer interface (given as url=... in data-multivio-options)

This provides maximal flexibility and accounts for different use cases. For basic situations, though, in which the same URL applies to the three cases (for example, for presenting a plain PDF file), it is possible to declare it only once, as the basic example above demonstrates.

How to configure the enabler script

The following table describes the full set of options accepted by the enabler script.

Option Type Default value Meaning
className string 'mvo-custom' This string is added to the "class" attribute of the wrapper <span> tag that is added around the preview, in order to improve custom style control. The given class can then be customized via CSS. This is a convenience mechanism, useful when there is no direct control over the generation of the HTML (e.g. when using CMS or wiki software)
method 'newwindow' | 'overlay' | 'download' 'newwindow' Defines how to present the file's content: using the Multivio interface in a new browser window; using the Multivio interface with an overlay in the current window; or with a simple download
previewWidth integer 60 Width of the preview thumbail
previewHeight integer 60 Height of the preview thumbail
supportedDocuments regular expression /.*?(\.pdf|\.jpeg|\.jpg|
\.gif|\.png|\.tif|\.tiff|xm|xml)$/;
Enables Multivio only for certain document types defined by the regular expression
thumbnailAlign 'bottom' | 'top' 'bottom' Vertical alignment of the thumbnail - this is useful when several documents are presented side-by-side, each with its own preview widget
downloadButton true, false true Displays the download button, if available
quickViewButton true, false true Display the quickview button if Multivio is supported
previewAttr string 'data-multivio-preview' The attribute in which the preview thumbnail's URL should be found; see also the explanation of the data-multivio-preview attribute of the <a> tag above
language 'en' | 'fr' 'en' The language of the Multivio interface
multivioClientInstance URL (string) 'http://demo.multivio.org/client' By default, the visual preview uses the demo instance of Multivio provided by RERO (both client and server layers); a different client instance can be defined with this option, which will be used for running the Multivio viewer interface
multivioServerInstance URL (string) 'http://demo.multivio.org/server' By default, the enabler script uses the demo instance of Multivio provided by RERO (both client and server layers); a different server instance can be defined with this option, which will be used for generating the preview thumbnail

How to customize the selector for the enabler script

The enabler script is applied to a specific set of HTML tags in the page, based on the selector directive used in its declaration. This selector uses jQuery notation, which offers a great amount of flexibility in defining which tags get selected for applying the visual preview.

The selector of the example shown above, takes all <a> tags with class="multivio-preview":

$('a.multivio-preview').enableMultivio({...

Another example:

$('.multivio-preview a').enableMultivio({...

selects all <a> tags which are descendent of tags with class="multivio-preview", such as:

<div class="multivio-preview">
  <a href="...  >...
</div>

Many more possibilities exist. They are all documented in the jQuery selector API.

Note that the selector must in all cases target a <a> tag, regardless of its surrounding context.

Multiple calls of the enabler script

It is possible to declare multiple selectors for the enabler script. This makes it possible to apply the preview feature differently to different document occurrences in the same page.

Important: when declaring multiple selectors, make sure that they are mutually exclusive, in order to avoid repeated application of the preview feature to the same document. That is, if more than one selector catches the same <a> tag, the enabler script will apply multiple times, resulting in inappropriate visual rendering.

Declaring the enabler script twice, with different selectors:

<!-- preview enabler script - it applies the required HTML transformations to the page -->
<script type="text/javascript">
  // selector for the second example
  $('.multivio-preview-example-2 a').enableMultivio({
    className: 'dark-and-bold',
    method: 'overlay',
    previewWidth: 120,
    previewHeight: 120,
    downloadButton: false,
    quickViewButton: true,
    previewAttr: 'href',
    language: 'fr'
  });
  // selector for the third example
  $('.multivio-preview-example-3 a').enableMultivio({
    className: 'light-and-soft',
    method: 'newwindow',
    previewWidth: 80,
    previewHeight: 80,
    downloadButton: true,
    quickViewButton: true,
    previewAttr: 'href',
    language: 'en'
  });
</script>

Note the differences between the two calls:

  • the CSS class name; the examples below show how this can be exploited
  • the display method for the Multivio interface
  • the size of the thumbnail
  • the available buttons
  • the interface language

Usage examples

The two following examples demonstrate how to exploit the enabler script declaration shown above.

Example 2

Olympic Charter 2010

In this example, the <a> tag containing the document's URL is enclosed in a <span> tag with the CSS class multivio-preview-example-2.

<!-- HTML code for example 2 -->
<span class="multivio-preview-example-2">
  <a title="Olympic Charter 2010 (2.6 MB)"
    href="http://doc.rero.ch/lm.php?url=1000,20,38,20111121000005-ZZ/2010-Olympic_Charter.pdf">
      Olympic Charter 2010
  </a>
</span>

Hence, the selector used with the enabler script catches the <a> tag, as intended:

$('.multivio-preview.example-2 a').enableMultivio({...

Besides, the className property declaration passed to the enabler script applies the dark-and-bold class to the resulting HTML, which allows further customization of the preview's appearance.

The corresponding CSS applies a blue background to the enclosing <span> and changes the font color and family of the label.

/** CSS for example 2 */
.dark-and-bold {
  background-color: #0F3066;
}
.dark-and-bold a.mvo-caption {
  font-family: Georgia, Times New Roman, serif;
  color: #F7F7F0;
}

Example 3

Olympic Charter 2010

This example is similar to the previous one, the differences being the CSS hook class declared in the original HTML (multivio-preview-example-3), which will allow a different enabler script to be applied, and the CSS class for the final visual formatting (light-and-soft).

<!-- HTML code for example 3 -->
<span class="multivio-preview-example-3">
  <a title="Olympic Charter 2010 (2.6 MB)"
    href="http://doc.rero.ch/lm.php?url=1000,20,38,20111121000005-ZZ/2010-Olympic_Charter.pdf">
      Olympic Charter 2010
  </a>
</span>
/** CSS for example 3 */
.light-and-soft {
  background-color: #F7F7F0;
  border-color: #AAAAAA;
  border-radius: 8px 8px 8px 8px;
  border-style: solid;
  border-width: 1px;
  box-shadow: 4px 4px 8px #AAAAAA;
}