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 imageimage: This property provides the main image (required)big: This property provides the big image for fullscreen modetitle: This property provides the image titledescription: This property provides the image descriptionlink: This property provides the image URL linklayer: This property provides a layer of HTML that will be displayed on top of the contentvideo: This property provides a URL to a video; as of Version 1.2.7 we support Vimeo, Youtube, and Dailymotion URLsiframe: This property provides a URL to be displayed in an iframeoriginal: This property provides a reference to the originalIMGelement
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:
<!DOCTYPE html>
<html lang="en">
<head>
<script src="http://code.jquery.com/jquery.min.js">
</script>
<script src="../galleria-1.2.8.min.js"></script>
<script>
// Galleria initialization will be placed here
</script>
</head>
<body>
<div id="galleria" style="height: 500px;">
<!-- html image structure will be placed here -->
</div>
</body>
</html>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:
<div id="galleria-img-tag" style="height: 500px;">
<!—- anchor tag wrapping img tag -->
<a href="images/image1-1600px.jpg">
<img data-title="Image 1"
data-description="Image 1 description"
src="images/image1-200px.jpg"
data-link="images/image1-1600px.jpg" />
</a>
<!-- More images defined in this way -->
</div>This code will be initialized with the following JavaScript code:
<script>
$(document).ready(function(){
Galleria.loadTheme(
'../themes/classic/galleria.classic.min.js');
Galleria.run('#galleria-img-tag');
});
</script>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:
<div id="galleria-media" style="height: 500px;"> <a href="http://www.youtube.com/watch?v=8gSPbmgWr_Y"> <img data-title="Youtube video" data-description="Youtube description" src="http://i3.ytimg.com/i/vC4D8onUfXzvjTOM-dBfEA/1.jpg?v=50aaaeea" data-link="http://www.youtube.com/watch?v=8gSPbmgWr_Y" /> </a> </div>
This code should be initialized with the following JavaScript code:
<script>
$(document).ready(function(){
Galleria.loadTheme('../themes/classic/galleria.classic.min.js');
Galleria.run('#galleria-media');
});
</script>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:
<script>
$(document).ready(function(){
Galleria.loadTheme(
'../themes/classic/galleria.classic.min.js');
var data = [
{
thumb: 'images/image1-200px.jpg',
image: 'images/image1-1600px.jpg',
title: 'Image 1',
description: 'Image 1 description'
},{
thumb: 'images/image2-200px.jpg',
image: 'images/image2-1600px.jpg',
title: 'Image 2',
description: 'Image 2 description'
}];
Galleria.run('#galleria-json', {
dataSource: data });
});
</script>Here, we're just using the dataSource property to specify an array of images that Galleria will use for the gallery.
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.
<div id="galleria-dataconfig" style="height: 500px;">
<dl>
<dt><img src="images/image1-1600px.jpg"
data-thumb="images/image1-200px.jpg" />
</dt>
<dd>
<span class="title">Image 1</span>
<span class="description">Image 1 Description</span>
</dd>
<dt><img src="images/image2-1600px.jpg"
data-thumb="images/image2-200px.jpg"/>
</dt>
<dd>
<span class="title">Image 2</span>
<span class="description">Image 2 Description</span>
</dd>
</dl>
</div>All that's left is instructing Galleria how to gather those properties from the DOM, which can be done with the following JavaScript code:
$(document).ready(function(){
Galleria.loadTheme(
'../themes/classic/galleria.classic.min.js');
Galleria.run('#galleria-dataconfig', {
dataConfig: function(img) {
var img = $(img);
return {
thumb: img.data('thumb'),
title: img.parent().next().
find('.title').html(),
description: img.parent().next().
find('.description').html()
}
}
});
});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.