This recipe provides an overview of the various methods used to provide alternative data structures for the Galleria framework to consume.
The data used to display images and other media for a gallery has a number of attributes that can be set up. Typically, Galleria just finds relevant image URLs, title, and description for the image and displays the gallery with that; however, there are more options possible to create a more robust gallery than what is typically used.
The full list of available image properties that can be set through HTML data attributes (HTML tag attributes that begin with data-
) or JavaScript is as follows:
thumb
: This property provides the thumbnail image
image
: This property provides the main image (required)
big
: This property provides the big image for fullscreen mode
title
: This property provides the image title
description
: This property provides the image description
link
: This property provides the image URL link
layer
: This property provides a layer of HTML that will be displayed on top of the content
video
: This property provides a URL to a video; as of Version 1.2.7 we support Vimeo, Youtube, and Dailymotion URLs
iframe
: This property provides a URL to be displayed in an iframe
original
: This property provides a reference to the original IMG
element
Full documentation covering image properties can be found via Galleria's website at http://galleria.io/docs/references/data/.
Before we start using the different image data properties, we'll create a file in the development folder called data-structures.html
. To start off, we'll create the basic HTML structure for our gallery using the following code:
Specifying extra parameters via IMG tag
The usual HTML structure for image data is to provide an anchor
tag linking to the image displayed in the gallery, which then wraps an img
tag that specifies the thumbnail and additional image properties for the gallery.
The following code is an example of this in practice:
This code will be initialized with the following JavaScript code:
Galleria understands data-
prefixed attributes as settings for Galleria on that image. So data-title
, data-description
, and data-link
are all Galleria image properties that are set via HTML data attributes. Additional properties could be provided here such as data-big
or data-original
.
In addition to images, Galleria can also display video and iframes inside the gallery. The method by which this is accomplished is mostly the same as the way images are specified, with the only difference being that the image URL is replaced with the video or iframe URL. Galleria supports YouTube, Vimeo, and Dailymotion video URLs.
The following code is an example of adding just a YouTube video:
This code should be initialized with the following JavaScript code:
As we can see, the HTML structure is basically identical. The only difference here is that we're using a YouTube video URL instead of an image URL.
It's also possible to use JSON data to initialize Galleria. This is useful when we want to initialize Galleria programmatically with JavaScript or when the image data is gathered on a remote server.
In our example, we'll load the same images as previously, just with a JSON structure instead of HTML, using the following code:
Here, we're just using the dataSource
property to specify an array of images that Galleria will use for the gallery.
HTML structure parsing customization
It's possible that you'll have an existing HTML markup that doesn't fit in the HTML pattern that Galleria expects. Here, we'll look into customizing how Galleria gathers the image properties for the gallery from the DOM.
For example, if working with a definition list (dl
) of images, titles, and descriptions, all the required properties are available in order to create a gallery.
All that's left is instructing Galleria how to gather those properties from the DOM, which can be done with the following JavaScript code:
What is being done here is that Galleria is finding every instance of an img
tag and passing it into the provided dataConfig
function, which then returns the rest of the image properties via simple jQuery DOM traversal.