Building a custom preview page


All versions of XS - 27.1 or later

Article updates


Related articles

Website customising


This article describes how you can build a custom preview page. A number of page fragments can be included in your custom HTML to build the final preview page or modal dialog. The page fragments have code and conditions to automatically adapt to the user's permissions, the type of file that's showing, certain backoffice settings and so on.

The modal dialog preview

You can create both a modal preview dialog and you can create a custom full screen preview page.

If you want previews to display using a modal dialog (as opposed to displaying a separate page), you can do so by enabling the "Preview Modal HTML" template in the Code editor. Note that the normal preview page (either the standard version or your own custom version) will still be available, this is the page that search engines / site crawlers will see - which is important for SEO. 

You can also use the modal preview for certain page types/functions, and the normal full screen preview page for other functions. If you want to do this then go to Site configuration > Preview page > Modal preview dialogs and select the page types where you want to use the modal preview dialog.


  • previewH1 
    This tag outputs the field that you have configured in back office as the field to use for the preview title as H1. Note that this is important for search engines. 
    Example of use: <h1 id="previewpagetitle"><?xs var('previewH1') ?></h1>
  • previewwidth
    Outputs the width of the preview image.
    <?xs media('previewwidth') ?>
  • previewheight
    Outputs the height of the preview image.
    <?xs media('previewheight') ?>
  • restrictionsterritories
    Outputs the names of territories for which territorial restrictions exist.
    <?xs media('restrictionterritories','preview') ?>
  • partofgalleries
    Outputs links to galleries of which the file is part
    <?xs media('partofgalleries','preview') ?>

Datafields and Datafield tag

You can output all the datafields (as you have configured in the metadata repository) with a single tag:

<?xs datafields('preview') ?>.

This will output the HTML for all fields that are configured to display in the metadata repository. The resulting HTML applies classes and properties to automatically display values as links, to hide labels if a field is blank and so on - based on what's configured in the repository.

If however, you want more control - then you can use the datafield tag instead. This is described below.

Outputting the complete field HTML

Use the 'c' parameter to output the complete HTML with an outer container div, a div for the label and a div for the field's data. The output HTML uses the repository settings to apply properties, e.g. show only if the user is an admin, show as link, hide outer container if the field's value is blank - and so on.


<?xs datafield('preview','c','headline') ?>

Example output:

<div class="fieldcontainer headline">
   <div class="fieldname">File title</div>
   <div class="fieldvalue" style="color:#ccc">
      <a href="/search?s=Protest in Amsterdam"><span>Protest in Amsterdam</span></a>

The class names (as showing in the above example) are fieldcontainer, fieldname and fieldvalue. If you want to use different class names, then you must supply all three class names as tag parameters. For example:

<?xs datafield('preview','c','headline','containerclass','fieldlabelclass','fieldvalueclass') ?>

The Style attribute color is applied if you have configured this in the metadata repository (e.g. <div class="fieldvalue" style="color:red">).      

Outputing the field label only

Use the 'l' parameter to output the field's label only (as configured in the repository and based on the active locale). Example:
<?xs datafield('preview','l','headline') ?>

Outputting the field's value only

Use the 'v' parameter to output the field's value only (as configured in the repository and based on the active locale). Example:
<?xs datafield('preview','v','headline') ?>

If you want to display just a single field in a different postion, you can still use the <?xs datafields('preview') ?> tag, and then simply hide the field that you don't want to show with css. For example, let's say that we want all the metadata fields on the right next to the preview image, but we want the caption to show underneath the preview image. 

Add this underneath the preview image:

<div style="clear:both;float:left;margin:10px 0 10px 0;width:<?xs media('previewwidth') ?>px">
     <?xs datafield('preview','v','caption') ?>

Then add this css to hide the caption that is ouput as a result of the <?xs datafields('preview') ?> tag, e..g.:

     #preview .fieldcontainer.caption {

Page fragments

    This page fragment outputs the preview image, video (or other file type). The HTML is automatically parsed to out output the correct HTML depedning on the media type, user permissions and so on.

    <div class="media" style="width:<?xs media('previewwidth') ?>px;height:<?xs media('previewheight') ?>px">
         <?xs html('previewc\') ?>

    This outputs the html for the thumbnail scroller that is used to paginate when viewing full screen previews, you cannot use this in the code for the modal previews. The appearance of the scroller is configured in backoffice Site configuration > Preview page > Pagination. You can then embed the scroller in a div with class name tspaginationbar and add the attribute scrollersetting with a value between 0 and 5. This attribute represents the setting as configured in backoffice. E.g. 0 for Fixed size, five thumbnails, 1 for Dynamic size, five thumbnails et cetera.

    <div class="tspaginationbar" scrollersetting="0">
          <?xs html('previewc\') ?>
    Outputs the html with the links for add to cart, add to lightbox etc. The HTML is automatically parsed to get the final output based on the user's permissions, file restrictions, the page the user is on et cetera. For example on the preview page of a lightbox image, the button "Remove from lightbox" will show and the button "Add to lightbox" will not. This include file uses the settings that you have configured in backoffice, i.e. whether or not you want labels to display, which button set to use and so on.

    <?xs html('previewc\') ?>
    <?xs html('previewc\') ?>
    <?xs html('previewc\') ?>
    This outputs the text for the active media (image, video or other) that you have configured in backoffice.
    <?xs html('previewc\') ?>
  • keywords{number}
    You can include 3 different page fragments for keywords. keywords0 outputs the HTML for the Draggable keywords, keywords1 outputs the HTML for keywords with checkboxes, and keywords2 outputs a simple list of clickable keywords.

    Use either <?xs html('previewc\') ?> <?xs html('previewc\') ?> <?xs html('previewc\') ?>
    Outputs the file sizes table HTML which is automatically parsed to display the correct details based on the user's permissions, site configuration settings and so on.

    <?xs html('previewc\') ?>


If you have protected galleries, then make sure to use the condition gallerylocked. Example of use: 

<?xs if gallerylocked {
     This gallery is locked
} ?>
<?xs if not gallerylocked {
     ... normal preview page html here...
} ?>


You can use <style></style> for CSS but it best to move your css to the separate custom CSS editor when you are done developing the custom pages. However, if for example you want to apply a fixed with to an element that is based on the width of the preview image, then you can use e.g. 

#preview .newkeywordsbox {
    width:<?xs media('previewwidth') ?>px;

or inline

<div style="width:<?xs media('previewwidth') ?>px;">
     some text here

Before and after methods

When the preview HTML loads and the related Javascript will be executed, a call to
is made and after the Infradox script has completed execution, a call to
is made.
Both calls receive the parameter modal to indicate whether the preview HTML was loaded in a modal dialog or as a normal HTML page.

You can define these methods in your client Javascript object, for eample:

var client = {
   init: function() {
   beforepreview: function(modal) {
      alert('before preview')
   afterpreview: function(modal) {
      alert('after preview')


Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk