Smart gallery

On this page

Sirv can automatically generate a gallery to display the contents of a folder. You can publish and maintain galleries with total automation. When new content is uploaded to a folder, the smart gallery automatically updates with the new content, so you can publish new assets instantly, without any coding. (Available to paid accounts only.)

Smart galleries can contain images, 360 spins or videos. Whatever content is in the folder, it will be included in the gallery. You can exclude items, if you wish, by applying a filter.

Example

To create a smart gallery, replace the trailing slash of the folder path with .view. For example, if this is your folder:

https://demo.sirv.com/Examples/b74317/

... this will be smart gallery URL:

https://demo.sirv.com/Examples/b74317.view

Embed a smart gallery in your page like this:

<script src="https://scripts.sirv.com/sirvjs/v3/sirv.js"></script>
<div class="Sirv" data-src="https://demo.sirv.com/Examples/b74317.view"></div>

Here's the result:

.view files

.view files are JSON text files, containing the filename and properties of each asset. You can see the content of the .view file by appending ?info to the URL:

https://demo.sirv.com/Examples/b74317.view?info

The contents can be returned as JSONP, by adding a callback to the URL:

https://demo.sirv.com/Examples/b74317.view?callback=abc

.view files are generated dynamically and won't appear in your Sirv account but you can also create your own .view files and upload them to your account.

Options

All the usual Sirv Media Viewer options can be applied to smart galleries. There are options for customizing the image zoom, 360 spin videos, thumbnails and styling of the gallery. Try the interactive demo to test all the different settings and see the code required.

<div class="Sirv" data-src="https://demo.sirv.com/Examples/b74317.view" data-options="video.autoplay:true; fullscreen.native:true;"></div>

Content filtering

The gallery content is shown in alphabetical order (uppercase first). Content from any sub-folders will be shown at the end of the gallery.

You can change the content in two ways - simple ordering or advanced ordering with filters.

Simple ordering

You can use the itemsOrder option to specify which items should appear in what order. Use the interactive demo to try these options and see the code.

Possible values are:

  • zoom (zoomable image)
  • spin
  • video
  • model
  • image (static image)

The following example will set the spin first, then the video, then everything else:

itemsOrder: [ 'spin', 'video']

The following example will set an image zoom first, then a spin, then 2 more image zooms, then a video, then everything else:

itemsOrder: [ 'zoom', 'spin', 'zoom', 'model', 'zoom', 'video']

Items will always appear in alphabetical order (uppercase first), so if your gallery has 2 spins, the first spin alphabetically chosen. If the gallery doesn't have an item, it will be skipped.

Here's a complete script:

<script>
  SirvOptions = {
    viewer: {
      itemsOrder: [ 'zoom', 'spin', 'zoom', 'model', 'zoom', 'video']
    },
  };
</script>

Advanced ordering and filtering

You can perform advanced filtering, for example to exclude items from a gallery, by applying a filter in JavaScript.

The following array of functions can be executed as a pipeline, when the gallery initializes.

Method Parameters Description
Sirv.viewer.filters.add (function) Add filter
Sirv.viewer.filters.remove (function) Remove filter
Sirv.viewer.filters.removeAll (event name) Remove all filters

The filter function is provided with the Viewer Id and array of items as arguments and must return the arrays of items.

The functions are called in the order they appear, each passing its return value through to the next. The last return value is used as the actual list of items.

This simple example shows a filter to remove any videos from the gallery:

<script>
  function filterVideo(viewerId, items) {
    return items.filter(item => item.type !== 'video');
  }
  Sirv.viewer.filters.add(filterVideo);
</script>

The following example will filter out a sub-folder named INSTAGRAM:

<script>
  function filterINSTAGRAM(viewerId, items) {
    return items.filter(item => !/\/INSTAGRAM\//.test(item.url));
  }
  Sirv.viewer.filters.add(filterINSTAGRAM);
</script>

The following example applies a filter to sort items, showing the spin first and the video last:

<script>
  function sortItems(viewerId, items) {
    function sortByType(a, b) {
      const types = {
        spin: 0,
        zoom: 1,
        video: 2
      }
    if (types[a.type] < types[b.type]) {
      return -1;
    }
      if (types[a.type] > types[b.type]) {
        return 1;
      }
      return 0;
    }
    return items.sort(sortByType);
  }
  Sirv.viewer.filters.add(sortItems);
</script>

The following script would show spins first, then zoomable images from a subfolder named productImages then a zoomable image called hero.jpg from a subfolder named lifestyleImage:

<script>
  function filterItems(viewerId, items) {
    const spins = items.filter(item => {
      return item.type === 'spin';
      });
      const productImages = items.filter(item => {
        return item.type === 'zoom' && /productImages\/\d+.jpg$/.test(item.url);
      });
      const lifestyleImage = items.filter(item => {
        return item.type === 'zoom' && /lifestyleImage\/hero.jpg$/.test(item.url);
      });
    return spins.sort().concat(productImages.sort(), lifestyleImage);
  }
  Sirv.viewer.filters.add(filterItems)
</script>

The following script will also sort the contents of alphabetically:

<script>
  function sortByName(a, b) {
    const nameA = a.url.split('/').pop().split('.').shift().toUpperCase();
    const nameB = b.url.split('/').pop().split('.').shift().toUpperCase();

    if (nameA < nameB) {
      return -1;
    }
    if (nameA > nameB) {
      return 1;
    }
    return 0;
  }

  function filterItems(viewerId, items) {
    const spins = items.filter(item => {
      return item.type === 'spin';
    });
    const productImages = items.filter(item => {
      return item.type === 'zoom' && /productImages\/d+.jpg$/.test(item.url);
    });
    const lifestyleImage = items.filter(item => {
      return item.type === 'zoom' && /lifestyleImage\/hero.jpg$/.test(item.url);
    });
    return spins.sort(sortByName).concat(productImages.sort(sortByName), lifestyleImage);
  }

  Sirv.viewer.filters.add(filterItems);
</script>

If your smart gallery contains no files, you could show a default image from your account. Use this script, changing the URL of the image to one of your own:

<script>
 var noImageURL = 'https://demo.sirv.com/website/no-image.jpg';

function filterEmptyView(viewerId, items) {
 if (!items.length) {
  const img = document.createElement('img');
  img.setAttribute('data-src', noImageURL);
  return [{
   enabled: true,
   node: img,
   type: "image",
   url: noImageURL
  }];
 }
 return items;
}
 Sirv.viewer.filters.add(filterEmptyView); 
</script>

It's easy to add assets from a different folder into the gallery. Just append the URL of the asset to the div, like so:

<div class="Sirv" data-src="https://demo.sirv.com/Examples/b74317.view, https://demo.sirv.com/Examples/warranty-2-year.png"></div>

You can also use this technique to add multiple smart galleries. More examples.

Thumbnails

You can generate thumbnails of the gallery contents. This is useful, for example, when you need to show product images on a category page of an ecommerce site.

Default thumbnail

Display a thumbnail by appending ?thumb to the .view file:

https://demo.sirv.com/Examples/b74317.view?thumb

All the usual dynamic imaging options can be applied to thumbnails, such as scaling. This image has width of 180px:

https://demo.sirv.com/Examples/b74317.view?thumb&w=180

Choose thumbnail

If the folder contains a spin, the thumbnail will be an animated GIF spin (but not if it is in a subfolder). Otherwise, the thumbnail will be the first image in alphabetical order.

You can specify a particular asset type as your thumbnail - an image, spin or video. Set the thumb parameter to either image, spin or video. For example, set it to image like so:

https://demo.sirv.com/Examples/b74317.view?thumb=image&thumbnail=400

Set fallback assets with commas. The example below sets a spin thumbnail, if unavailable then a video thumb, if unavailable then an image thumb:

https://demo.sirv.com/Examples/b74317.view?thumb=spin,video,image&thumbnail=250

Additional thumbnails

As well as showing a thumbnail of the first item alphabetically, you can display thumbnails of the second and third etc. items. The other assets can be shown by setting thumb to the item number, alphabetically. For example, thumb=2, will show the second item:

https://demo.sirv.com/Examples/b74317.view?thumb=2&thumbnail=400

Follow the instructions to achieve the popular image hover effect to swap images on rollover (without knowing the image names).

To apply a specific asset type and the order number, add the number, then the asset type. The following URL will display the 2nd spin from the folder:

https://demo.sirv.com/spins.view?thumb=2,spin

Placeholder image

For faster user experience and better PageSpeed score, we recommend adding a placeholder image to your gallery. The placeholder will be requested straight after page load, before sirv.js loads and avoiding any blocking from other scripts on your page.

Follow the approach below to create an external container for thumbnails. Reference the name of that container with the thumbnails.target parameter. You can apply different styles and settings for mobile, if you wish.

HTML:

<div class="SirvGallery-Wrapper">
 <div class="pdp-gallery-container">
  <div class="pdp-gallery-thumbnails"></div>
  <div class="pdp-gallery-main">
   <img class="pdp-gallery-placeholder" src="https://demo.sirv.com/Examples/b74317.view?thumb" alt="" loading="lazy">
   <div data-src="https://demo.sirv.com/Examples/b74317.view"
        data-options="itemsOrder:['spin']; thumbnails.target: .pdp-gallery-thumbnails; thumbnails.size:106; thumbnails.position:left; thumbnails.always:true; fullscreen.always:false; fullscreen.thumbnails.position:left; fullscreen.enable:true"
        data-mobile-options="thumbnails.target: .pdp-gallery-thumbnails; thumbnails.size:60; thumbnails.position:bottom; fullscreen.thumbnails.position:bottom"
        class="Sirv mainimage">
   </div>
  </div>
 </div>
</div>

CSS (in this example, thumbnails are aligned left):

<style>
  /* Sirv Media Viewer placeholder */
  .pdp-gallery-container {
    display: flex;
    height: 100%;
    max-height: 100%;
  }
  /* Set the size of thumbnails */
  .pdp-gallery-thumbnails {
    width: 114px;
  }
  .pdp-gallery-thumbnails .smv-thumbnails.smv-v.smv-external .smv-selectors {
    min-width: unset !important;
  }
  .pdp-gallery-thumbnails .smv-selector>img {
    width: auto !important;
    height: auto !important;
  }
  .pdp-gallery-main {
    flex: 1 1;
     position: relative;
  }
  .pdp-gallery-main .Sirv.mainimage {
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
  }
  /* Non-first item should overlap placeholder */
  .pdp-gallery-main .Sirv .smv-slides-box .smv-slides .smv-slide.smv-shown:not(:first-child) {
    background-color: #fff;
  }
  /* Placeholder */
  .pdp-gallery-main .pdp-gallery-placeholder {
    width: 100%;
    height: 100%;
    max-height: 100%;
    object-fit: contain;
  }
</style>

If you'd like to set the placeholder as the first frame from a spin, use this:

https://demo.sirv.com/Examples/b74317.view?thumb=spin&image.frames=1

Here is a demo showing a media gallery with placeholder and thumbnails below.

You can add YouTube, Vimeo or other video URLs to your smart gallery by creating a .url file. The file should be in JSON format, like so:

{
 "title": "Enigma Evoke bike review on YouTube",
 "url": "https://www.youtube.com/watch?v=xx0EPhHX2U4"
}

Example: https://demo.sirv.com/Examples/Enigma/enigma-youtube.url
Smart gallery: https://demo.sirv.com/Examples/Enigma.view

Manually create .view files

As well as automatically creating .view files upon request, you can also manually create them. This gives you total control to specify which files should be included in your gallery. Any file, anywhere in your Sirv account could be included in the gallery, in any order you wish.

Simply generate a file with JSON coding, like the example below. The example would create a gallery with 4 images, a spin, a Sirv video, a YouTube video and a Vimeo video. The gallery looks like this. The code should be saved in a text file named with a .view extension and uploaded to Sirv.

{
  "dirname": "/demo/sirv-media-viewer/moosejaw/10487919",
  "assets": [
    {
      "name": "10487919x1011935_zm.jpg",
      "type": "image"
    },
    {
      "name": "spin/spin.spin",
      "type": "spin"
    },
    {
      "name": "10487919x1020171_vAlt_image_3.jpg",
      "type": "image"
    },
    {
      "name": "Moosejaw-x-Mystery-Ranch.mp4",
      "type": "video"
    },
    {
      "name": "10487919x1020171_vAlt_image_4.jpg",
      "type": "image"
    },
    {
      "name": "10487919x1020171_vAlt_image_1.jpg",
      "type": "image"
    },
    {
      "name": "https://youtu.be/M1mLIeA3_-I",
      "type": "youtube"
    },
    {
      "name": "https://vimeo.com/319074143",
      "type": "vimeo"
    }
  ]
}

Usage limitation

The Smart Gallery feature is available only to paid plans and trial plans. Free plans cannot use .view files.

Credit

Special thanks to Gravity 360 for the Adidas shoe 360 spin.

Was this article helpful?

Array

Get help from a Sirv expert

Contact Us

help ukraine help ukraine Powered by Ukrainian determination and British ingenuity

How can you support Ukraine