Custom thumbnail templates

Availability

All versions of XS - 28 or later

Article updates

  • First published 16 December 2016
  • Added rf/rm icon example 21 December 2016

Related articles

Website customising

Constants

Functions, tags and conditions

Adding Javascript to your pages

Using Custom CSS

Introduction

This article describes how you can build custom thumbnail templates for search results, galleries and so on. For these pages, you can configure 5 different thumbnail viewing styles via Site configuration, Thumbnail pages. The modal lightbox page uses a grid type thumbnail. 
The code editor provides code examples for each of the styles (grid, list, small, large and flow) and for the modal lightbox thumbnails - that you can use as a starting point. If you load the example code for one of the thumbnail templates, and you save it without making changes, then the client facing result is the standard result (i.e. what you get without customized thumbnail templates). 

Note that you can change just one or a few viewing style templates. You don't have to make custom template for every viewing style if for instance you just want to change the large thumbnail template.

Before you begin

Please understand that there may be no need to make custom thumbnail templates depending on what you want to achieve. A lot can be done by chosing settings in back office and/or changing the CSS, adding Javascript and so on. Custom templates offer more flexibility and may result in better performance (by removing what you don't need), but there is no guarantee that future XS updates will not interfere with your custom templates. If you do not accept this, then do not make custom thumbnail templates.

Make sure that you understand how the xs tags work, before changing the templates described here. You can find more information in the article Infradox XS functions, tags and conditions

You also need to know about constants, locales and repository properties before you start working on the thumbnail templates.

It is recommended that you start configuring the thumbnail pages before you use the code editor to make template changes - because the settings will also affect your custom templates.

Note that the default templates are complex and use several classes so that everything can be configured with back office settings without making code changes. If however you are going to make code changes, then the code can be simplified (and as a result smaller and faster) by removing classes and/or HTML you don't need for you specific situation.  

The above screenshot shows where you can configure the thumbnail templates in backoffice

Site configuration, Thumbnail pages

  • Click on General settings and configure the Data to display setting. This is used with the tag <?xs slot('hovertext') ?>
  • Configure the settings for hovering and so on as needed. Note that the options that are best used depend entirely on what you want to achieve with your custom templates. Create a support ticket if you need advice.
  • Open the section Page layout and enable the thumbnail viewing styles that you want to make available on the client facing pages (i.e. grid, list, mini/small, large, flow).
  • Open the Alt and Title tags section and configure the alt and title tags. These are used in the templates with <?xs slot('alttext') ?> and <?xs slot('titletext') ?>. Note that these are important for several reasons, one of them being SEO.

Site configuration, Metadata display

  • Click on General settings and configure what info (i.e. rights, restrictions and so on) you want to use in the thumbnail templates. 
  • You can use these settings in the templates, e.g. with <?xs rproperty('con_rht') ?> which outputs 1 if "rights info" is configured to show on thumbnails. 

The Grid template explained

This paragraph explains how the grid thumbnail template works and how it can be changed. The other templates are more or less the same, and you should be able to work on those once you have successfully changed the Grid template.

Note that the classes and attributes (set with tags) are important because the script "looks for" elements having - or not having - certain class names and or attribute values. 

In the code editor, select Grid (90) in the dropdown box at the top. Then click "Load example" and load the default code into the editor.

The first line looks like this:

<div class="gridModeBox tfbox supp<?xs slot('supplierid') ?> <?xs slot('rf','boxrf','boxrm') ?>" id="slot_<?xs slot('nr') ?>">

The HTML output of this line may look something like this:

<div class="gridModeBox tfbox supp100 boxrm" id="slot_1">

<?xs slot('supplierid') ?> outputs the supplier id 
<?xs slot('rf','boxrf','boxrm') ?> outputs boxrf if the file is a RF file, otherwise it outputs boxrm
<?xs slot('nr') ?> outputs the number of the thumbnail on the page. This is an important element for the XS script, you should not remove it.

The second line:

<div class="vicon<?xs slot('mediatype') ?> trans50"></div>

uses the 'mediatype' tag. This will output 0 for images, 1 for video, other numbers for other media types. If your website uses only images, then this line can be removed, otherwise it should be there because it's used to position video players and icons.

The following div is the container of the thumbnail: 

<div class="thumbnail na<?xs slot('unavailable') ?>" id="<?xs slot('api_uid') ?>" br="<?xs slot('br','1','0') ?>" mt="<?xs slot('mediatype') ?>" rnk="<?xs slot('ranking') ?>">
<a class="filepreview" href="<?xs slot('previewurl') ?>">
<img class="thmbimg" src="<?xs slot('tcache') ?>" alt="<?xs slot('alttext') ?>" title="<?xs slot('titletext') ?>" />
</a>
</div>

It uses the following important tags:

<?xs slot('unavailable') ?> outputs 1 if the file is unavailable on the server
<?xs slot('api_uid') ?> outputs the unique id, e.g. 0_00082881 - where 0 is the API id, and the 2nd part is the file id
<?xs slot('br','1','0') ?> outputs 1 if the file has a blocking restriction, 0 if it doesn't.
<?xs slot('previewurl') ?> outputs the complete preview url
<?xs slot('tcache') ?> outputs the path to the normal sized thumnail in the tcache folder

The next div in the template holds html that either displays when hovering only or always - depending on what you have configured in back office. 

<div class="buttononlyhover matrixt hover<?xs rproperty('tmb_hover','0') ?>">

The <?xs rproperty('tmb_hover') ?> tag outputs 0 or 1 depending on what you have configured with regards to hovering. So the output will look like either 

<div class="buttononlyhover matrixt hover0">
or
<div class="buttononlyhover matrixt hover1">

The above div contains elements for thumbnail buttons, file id's, restriction info and so on - which is explained below.

The constants used in the thumbnail templates can have a 3rd parameter, e.g.
<?xs constant('cThmbtolightbox','','1') ?>
This 3rd parameter can only be used in thumbnail templates. It tells the parser to replace the constant with data from the repository. It is best to keep these tags as they are in the example code. 

The line:
<li class="fileid<?xs rproperty('tmb_refer','0') ?>"><?xs slot('contentreffield') ?></li>
uses the tag <?xs rproperty('tmb_refer'),0') ?> to output either fileid0 or fileid1 as CSS class name. Class name fileid0 is then used to hide the element (in this case a list item <li></li>).

To display the restriction icons, the following logic is used:

<li title="<?xs constant('cRights_RF') ?>" style="display:none" class="rightsicon rightsicon<?xs slot('rf','rf','norf') ?> rmrf<?xs rproperty('con_rht') ?>"></li>

The HTML output may look something like this for an RF file:

<li title="Royalty Free" style="display:none" class="rightsicon rightsicon rf rmrf1"></li>

The <?xs rproperty('con_rht') ?> outputs 1 if you have configured "Rights info" to display on thumbnail pages (Site configuration, Metadata display, General settings). 
XS uses CSS and Script to hide or show elements based on the HTML output, e.g. rmrf1 to display the info, rmrf0 to hide it. 

If for example, you decide not to use these settings because you always want it to show - then you can replace the tag with a hard coded value. E.g.:
<li title="<?xs constant('cRights_RF') ?>" class="rightsicon rightsicon<?xs slot('rf','rf','norf') ?> rmrf1"></li>
In the above example, style="display:none" has been removed and the class rmrf1 is hard coded.

The tag <?xs slot('contentreffield') ?> outputs the value for the field that you have configured as the field that has the file ids. This can be configured via Website Configuration in back office.

The grid thumbnail template used for the modal lightbox

The modal lightbox uses a grid type layout for the thumbnails by default. You can create a custom version for this template too. To do this, select "Modal lightbox (100)" in the Code editor drop down. Then load the example template into the editor with the "load example" button at the top.

The template is mostly the same as the normal grid styke template, but it has a few different classes and it uses tags that may be used in this template only. These are:

  • <?xs slot('oncartpage') ?>
    Outputs 1 if the the lightbox is opened when on the cart page.
  • <?xs slot('lightboxpreviewurl') ?>
    Outputs the URL to the preview page (or modal preview). 

An overview of all the slot tags that you need to understand

  • <?xs slot('supplierid') ?>
    Outputs the supplier id
  • <?xs slot('mediatype') ?>
    Outputs the mediatype as a number, 0 for images, 1 for video, 2 for audio etc
  • <?xs slot('nr') ?>
    Outputs the number of the thumbnail on the page starting at 1 for the one on the top left
  • <?xs slot('unavailable') ?>
    Outputs 1 if the file is (temporarily) unavailable 
  • <?xs slot('api_uid') ?>
    Outputs the unique file ID, the part before the underscore is the index of the API 
  • <?xs slot('ranking') ?>
    Outputs the ranking value
  • <?xs slot('previewurl') ?>
    Outputs the full url to the preview page 
  • <?xs slot('fileorientation') ?>
    Outputs 0,1,2,3 for Vertical, Horizontal, Square and Panoramic files respectively. Use only in the Flow template.
  • <?xs slot('flowwidth') ?>
    Outputs the calculated image width based on the file's orientation. Use only in the Flow template.

Tags used to output text (these need to be configured via Site configuration, Thumbnail pages)

  • <?xs slot('alttext') ?>
    outputs the ALT text
  • <?xs slot('titletext') ?>
    outputs the TITLE text
  • <?xs slot('hovertext') ?>
    outputs the long text (e.g. used to display when hovering)

Tags for rights / restrictions

  • <?xs slot('rf','true','false') ?>
    outputs 'true' if the file is RF or else 'false'. The output values are just examples and can be anything. The templates use e.g. <?xs slot('rf','rf','norf') ?> to output class names.
  • <?xs slot('rm','true','false') ?>
    as above but for RM
  • <?xs slot('mr','true','false') ?>
    as above but for Model Release
  • <?xs slot('pr','true','false') ?>
    as above but for Proeprty Release
  • <?xs slot('rs','true','false') ?>
    outputs the first parameter if there are restrictions or else the 2nd parameter value.
  • <?xs slot('tr','true','false') ?>
    outputs the first parameter if there are restrictions for the user's territory or else the 2nd parameter value.

Tags for series / similar files / galleries

  • <?xs slot('seriespartof') ?>
    outputs 1 if the file is part of a series (can also be used for similar files)
  • <?xs slot('seriesurl') ?>
    outputs the full url to the series page
  • <?xs slot('seriesglbid') ?>
    outputs the id of the series
  • <?xs slot('seriesfilecount') ?>
    outputs the number of files that are part ofthe series

Tags for thumbnail files

  • <?xs slot('lcache') ?>
    path to the small (mini) thumbnail 
  • <?xs slot('tcache') ?>
    path to the normal (grid) size thumbnail
  • <?xs slot('mcache') ?>
    path to the large thumbnail - also used for hover previews

Examples

Example 1 - how to display the RF / RM icons 

This example explains how you can display an icon to indicate that a file is RM or RF at all times while having hovering enabled.

1) Load the custom CSS into the code editor
2) Add the following CSS:

.rightsiconbox {
     float:left;
     width:20px;
     height:20px;
     margin-top:-15px;
     margin-left:2px;
}

This is the place holder div element in which the icon will be positioned. The div will be added underneath the thumbnail box later. In this example, it has a top margin of minus 15px to move it up. Note that what the CSS should look like for your particular situation depends of course on how you have configured the thumbnail templates and CSS. The above CSS is just an example.

3) Load the "Large" thumbnail template into the code editor
4) Underneath the div with the class "thumbnail" add the following code:

<div class="rightsiconbox">
     <img src="<?xs path('xscss') ?>/../images/1_0/<?xs slot('rf','RF','RM') ?>icon.png" />
</div>

The red box in the above screen shot shows where you need to add the html

The tag <?xs path('xscss') ?> outputs the relative path to the css folder. You need to go up one folder and then to the images/1_0 folder. Hence the .. in the html. 

The tag <?xs slot('rf','RF','RM') ?> will output RF for RF files, or else RM.
So <?xs slot('rf','RF','RM') ?>icon.png will output either RFicon.png or RMicon.png.

You can of course use your own icons instead. Upload your images via Site configuration, Website files, Website artwork. You will then need to change the path accordingly.
For example:

<img src="/siteowner/artwork/artwork/<?xs slot('rf','myrficon','myrmicon') ?>.png" />

5) Change the other thumbnail templates as required.

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk