Instant Galleria How-to: Recipes to make you an expert user of the Galleria JavaScript framework

Before we start developing with Galleria, you'll need a text editor to use throughout this book since we'll be modifying HTML, JavaScript, and CSS.

Assemble together a group of images that you'll use while working with Galleria and place them into your Galleria development image source directory (galleria/development/images).

Galleria searches the div tag with the id "galleria" to find images to load the gallery. Galleria then calls the theme JavaScript initialization code to generate additional HTML and JavaScript events that set up the gallery further. Essentially, galleria.js provides the basic gallery components and the theme uses these components to further customize the look and feel of the gallery.

In this example, please utilize the code we wrote in the first How to do it... section, or work with the themes/classic/classic-demo.html file. Both will allow us to manipulate configuration options.

To configure Galleria, we'll use the Galleria.configure method. This method accepts a JavaScript object of keys and values.

Galleria.configure({
    autoplay: true
});

In this example, we're invoking Galleria to automatically start the gallery when the page is loaded with the autoplay option.

The JavaScript object passed into the Galleria.configure method overrides or extends the default Galleria configuration. This configuration is then passed on to the theme loaded and plugins that are installed.

We can also combine the Galleria.run method call with configuration options. Using the example we've been working with, the Galleria.run method call would look as follows:

Galleria.run('#galleria', {autoplay: true});

The theme we'll be working with is the classic theme that comes with the Galleria source code.

There are two ways by which we can load theme files into Galleria:

The theme JavaScript file needs to be loaded before the Galleria.run function in order to start Galleria with the theme loaded.

The theme file will automatically load dependent CSS files required for the theme. It will additionally run initialization code for theme specific look and feel.

It's possible to dynamically change Galleria themes by loading other themes with the Galleria.loadTheme function.

In order to keep all the theme related files together, create a new folder inside the development folder named themes. Within the new themes folder, create another folder named basic. After this is done, our folder structure should be identical to the following screenshot:

Lastly, create empty galleria.basic.js, galleria.basic.css, and galleria.basic-example.html files inside the basic folder that was just created. Then, copy the contents of the myfirstgallery.html file and insert the text into the galleria.basic-example.html file. These are the files that we will be customizing in this recipe.

Once finished, the theme should be rendering a screen like the following screenshot:

Galleria loads the theme JavaScript file we specified in the Galleria.loadTheme function. Galleria then looks at the CSS file specified in the theme JavaScript file to load the stylesheets. The markup is generated by Galleria and then all the styling is done by us.

Before we start working on the code, we'll need to copy the basic gallery example code from the previous example and rename the folder and files to be prefixed with mobile. After this is done, our folder and file structure should look like the following screenshot:

We should now have a gallery that scales well for smaller device sizes, as shown in the following screenshot:

The responsive option tells Galleria to actively detect screen size changes and to redraw the gallery when they are detected.

Then, our responsive CSS rules style the gallery differently for different device sizes. You can also provide additional rules so the gallery is styled differently when in portrait versus landscape mode. Galleria will detect when the device screen orientation has changed and apply the new styles accordingly.

Using the myfirstgallery.html file we created in the first section, we'll customize it to include the history plugin that is packaged with Galleria.

All that is required to install a plugin is to include its JavaScript file. Place the following code inside the head tag:

<script src="../galleria-1.2.8.min.js"></script>
<script src="../plugins/history/galleria.history.min.js">
</script>
<script type="text/javascript">
  $(document).ready(function(){
    Galleria.loadTheme('../themes/classic/galleria.classic.min.js');
    Galleria.run('#galleria');
  });
</script>

With plugins, it's possible to hook into Galleria to customize its behavior. This ranges from customizing how Galleria retrieves its images, what images it loads, and how it handles JavaScript events.

In the case of the history plugin for image change, it adds a hash value to the URL so that each image visited in the gallery can have a unique URL. This allows users to link directly to an image inside the gallery. Then, when the page is requested with the specified hash, it will load that image instead of the initial image in the gallery and also allow the user to go backward/forward in history.

Galleria includes three plugins in its distribution: flickr, picasa, and history. The flickr and picasa plugins provide an ability to view galleries directly from those photo services.

We're going to use the myfirstgallery.html file and modify the example again, though it's fine to use whatever gallery implementation is available if preferred.

The flickr plugin uses the flickr RESTful API to retrieve images that are used with the Galleria API to dynamically add images to the gallery.

There are additional flickr plugin options that can be used; however, they need to be specified in their own flickrOptions object:

Galleria.run('#galleria', {
  flickr: 'search:beach',
  flickrOptions: {
    max: 50
  }  
});

The following list is a complete listing of flickr plugin options:

For this exercise we're going to walk through the process of creating a Facebook plugin that will get all the public photos for the user or page provided in a Galleria option.

Before we get started, we need to create a new folder named facebook. Inside the folder, please create empty files with the names galleria.facebook.js and galleria.facebook-example.html.

Creating a plugin can include hooking into Galleria events, customizing options, or overriding Galleria methods. In the later stage, we need to make sure we still allow Galleria to function properly if the plugin isn't used, even though it might be loaded.

The plugin overrides the original load behavior of Galleria, retaining the original load behavior to fall back on if the facebook plugin is not used. Then, we use the Facebook Graph API with AJAX to retrieve the images.

For this exercise, we'll be going through an example that utilizes an event listener and API calls. To start us off, create an api-example.html file in the development folder.

The following list provides a quick reference to useful Galleria events:

The following list provides a quick reference for useful Galleria API methods:

Galleria.on('mygalleriaevent', function(e){
  /* event code */
});

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:

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>

<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>

<script>
  $(document).ready(function(){
    Galleria.loadTheme(
      '../themes/classic/galleria.classic.min.js');
    Galleria.run('#galleria-img-tag');
  });
</script>

<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>

<script>
  $(document).ready(function(){
    Galleria.loadTheme('../themes/classic/galleria.classic.min.js');
    Galleria.run('#galleria-media');
  });
</script>

<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>

<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>

$(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()
            }
        }
    });
});

Before an image is displayed in a gallery, Galleria uses the various methods we described previously to parse image data so that it can easily be customized.

Since this recipe is just discussing various techniques to improve the performance of Galleria, we'll not use a specific example to walk through. The following techniques can be applied to any of the galleries created throughout the book.

For this example, we're going to assume all our images are located in a single directory and follow specific naming conventions. This allows us to dynamically load more images according to those conventions.

To start out, we'll create a file in our development directory named dynamic-images.html with the contents as shown in 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 type="text/javascript">
      /* Galleria initialization code */
    </script>
  </head>
  <body>
    <div id="galleria" style="height: 500px;">
  </div>
</body>
</html>

This will just provide us with the basic structure before we start writing our JavaScript code.

The following process of dynamically loading more images in a gallery is simple:

Here is a sample JavaScript snippet that will provide what was just discussed:

<script>
    /* function to get images with URLs generated
       from one number to another larger number */
    var getImages = function(from, to){
        var data = [];
        for(var i=from; i<=to; i++){
            data.push({
                image: 'images/image' + i + '-1600px.jpg',
                thumb: 'images/image' + i + '-200px.jpg',
                title: 'Image ' + i,
                description: 'Image ' + i + ' Description'
            });
        }
        return data;
    }
    $(document).ready(function(){
        Galleria.loadTheme(
            '../themes/classic/galleria.classic.min.js');
        /* Load with the first 2 images */
        Galleria.run('#galleria', {
            dataSource: getImages(1, 2),
        });
        Galleria.ready(function(options) {
            var galleria = this;
            galleria.bind('loadstart', function(e) {
                /* after an image starts load, check to see
                   how close we are to loading more images */
                var size = galleria.getDataLength();
                if((e.index + 2) > size && size <= 10){
                    galleria.push(
                        getImages(size + 1,
                            Math.min(size + 2, 10)));
                }
            })
        });
    });
</script>

The getImages method is designed to retrieve a section of the 10 available images on the filesystem. The dataSource Galleria parameter is used to load the initial couple of images in Galleria. Finally, we bind the loadstart event, and inside it we add more images to Galleria with the galleria.push method if more images are available.

Since we know the naming convention of the images on the filesystem, we can dynamically construct the necessary image URLs for the gallery. In addition, Galleria provides the necessary events and API calls for us to be able to hook in and dynamically load images.

Sometimes it's required to delay loading Galleria until sometime after a page is rendered. Additionally, you may want to trigger displaying a specific image in the gallery with an event outside the gallery. With this recipe, we'll configure Galleria to be loaded only when a user decides to view the gallery and images to be shown when a user performs a specific action outside of the gallery.

To get us started, create a file named trigger-exampe.html in the development directory we've been working in with the following structure:

<!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 */
    </script>
  </head>
  <body>
    <div id="galleria"
         style="height: 500px; display: none">
      <!-- supply images here -->
    </div>
    <a id="show-gallery">Show Gallery</a> | 
    <a id="show-image">Show Image 2</a>
</body>
</html>

Make sure to fill in the image HTML structure to test with. We'll fill in the Galleria JavaScript initialization code in the following example.

To accomplish this, we'll add event handlers for click events on the anchor tags to "Show Gallery" and "Show Image 2".

<script>
  $(document).ready(function(){
    /* when the element with the id "show-gallery" is clicked,
       create the gallery. */
    $('#show-gallery').click(function(e){
      $(this).remove();
      $('#galleria').show();
      Galleria.loadTheme(
        '../themes/classic/galleria.classic.min.js');
      Galleria.run('#galleria');
      /* prevent the default link behaviour */
      e.preventDefault();
    });
    $('#show-image').click(function(e){
      var galleria = Galleria.get(0);
      if(galleria === undefined){
        alert('Galleria not initialized yet.');
      }else{
        galleria.show(1);
      }
      e.preventDefault();
    });
  });
</script>

Here, we register click event handlers for each of the anchor tags we added to the document. Rendering the gallery inside a click event is identical to registering as we have been doing throughout the book. Here, we're just doing the same inside the click event.

To show an image on a click event outside the gallery, we use Galleria.get to retrieve the current active Galleria instance active on the page. Then we use the galleria.show method to show the second image of the gallery.

Galleria initialization is done with JavaScript so that it can be initialized in any number of ways. In our example, it was just a simple click event; however, any number of scenarios can be devised to destroy existing gallery instances and recreate new instances with events.

To get us started, we create a new ga-example.html file inside our development directory. Include a couple of sample images so that we can inspect the Google Analytics tracking requests being sent.

The basic HTML structure will look like the following code snippet with the normal Google Analytics code at the bottom of the file:

<!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 */
    </script>
  </head>
  <body>
    <!-- Galleria HTML definition -->
    <div id="galleria" style="height: 500px;">
      <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>
      <a href="images/image2-1600px.jpg">
        <img data-title="Image 2"
             data-description="Image 2 description"
             src="images/image2-200px.jpg"
             data-link="images/image2-1600px.jpg" />
      </a>
    </div>
    <script>
  /* Standard analytic JavaScript source. Please replace 
     "<CODE>" with your GA code */
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '<CODE>']);
  _gaq.push(['_trackPageview']);
  (function() {
    var ga = document.createElement('script');
    ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 
                  'https://ssl' : 'http://www') + 
              '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0];  
    s.parentNode.insertBefore(ga, s);
  })();
    </script>
  </body>
</html>

The Google Analytics JavaScript includes an API to push page tracking manually to Google. In our case, we'll hook into a Galleria image view event and send out a Google Analytics page tracker request. The Google Analytics JavaScript API uses AJAX to send out the tracker request so a new page load isn't required.

<script>
  $(document).ready(function(){
    Galleria.loadTheme(
      '../themes/classic/galleria.classic.min.js');
    Galleria.run('#galleria');
    Galleria.ready(function(options) {
      var galleria = this;
      galleria.bind('loadstart', function(e) {
        var url = e.imageTarget.src;
        var host = window.location.hostname;
        _gaq.push(['_setCustomVar', 1,
                   "galleryView", "yes", 1]);
        _gaq.push(['_trackPageview', 
                  url.substring(url.indexOf(host) + 
                                host.length)]);
      });
    });
  });
</script>

The code pattern here follows much of what has been done throughout the book. We're registering an event handler that'll fire when a new image is shown in the gallery. Then, we're sending the tracker request to the Google Analytics API. We make sure to only get the full path of the image to track in Google Analytics. The host name is not allowed.

The Google Analytics API provides an API to push page tracking to it manually in JavaScript. We're just utilizing that API in this example with basic Galleria API programming.

Google Analytics has a robust JavaScript API if there is a need to do something more fancy. Check out their documentation available at https://developers.google.com/analytics/devguides/collection/gajs/methods/.

There are two types of Galleria errors, fatal, and warnings. Fatal errors will throw a JavaScript exception and stop all following JavaScript from running. Warnings will cause Galleria to not show an image and then present an error box to the user.

Fatal errors can result from the following reasons:

Warnings can result from the following:

We'll use two separate methods to handle each of these types of errors in Galleria to help handle them better.

To implement our error handlers, let's create a file named errors-example.html in the development directory. The contents can be a very basic Galleria setup as follows:

<!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>
      $(document).ready(function(){
        Galleria.loadTheme(
          '../themes/classic/galleria.classic.min.js');
        Galleria.run('#galleria');
      });
    </script>
  </head>
  <body>
    <div id="galleri1a" style="height: 500px;">
      <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>
      <!-- other images -->
    </div>
</body>
</html>

Since fatal errors prevent other JavaScript from executing on the page, it's especially important that we handle these errors. In addition, it's important to give the user an indication that the Galleria failed to load.

As for warnings, they'll most likely be caused by incorrect configuration but there are still ways to prevent them from being too much of a nuisance.

To override the default error handling strategy, let's work through the following code:

<script>
  $(document).ready(function(){
    Galleria.loadTheme(
      '../themes/classic/galleria.classic.min.js');
    Galleria.run('#galleria', {
      debug: false,
      dummy: 'images/dummy.jpg'
    });
  });
</script>

Setting debug to false prevents Galleria from throwing a JavaScript fatal error and stopping the execution of any additional JavaScript. In addition, setting a dummy image tells Galleria to use that image instead of showing an error message or failing when an image fails to load.

In the tests we're going to write, we'll be using the Selenium test framework with the Firefox web browser. The advantage of Selenium is that it comes with an IDE plugin so novices can even write tests. The difficultly level is ideal to cover in this book.

We'll be using Selenium to record user interactions with our Galleria customizations. Once these interactions are recorded, they can then be tested against any additional functionality or changes to ensure that everything is still working as expected.

Before we get started, please download the Firefox web browser if you have not already done so, available at http://www.mozilla.org/firefox. Follow the instructions to download and install.

Then, open Firefox and visit http://seleniumhq.org/download/ and follow the instructions to download and install the Firefox Selenium IDE plugin. Make sure to restart Firefox after the plugin is installed.

Finally, open up Selenium IDE by clicking on Tools in the menu bar and then selecting the Selenium IDE item in the menu. There should be a Selenium IDE window like the one in the following screenshot:

Once Selenium is set up, locate the myfirstgallery.html file that we created in the Setting up the development environment recipe. We'll be creating tests for that gallery.

In addition to the actions that were recorded, it would be beneficial to also include assert statements to make sure certain elements are present in the DOM as each action is performed. Inspect Selenium IDE for details on using more commands and tests.

Selenium IDE allows us to record all the actions being performed in the browser. Then the Selenium test driver plays the tests defined against a web browser, in our case Firefox.

Those tests can be run against a Selenium server that is set up to test against multiple browsers and operating systems.

For the sake of this example, we'll be introducing a new programming language and platform to work with. The purpose is to show how a possible web application integration would work. We'll be using the Python programming language and the Flask web application framework. Both are known for their ease of use so hopefully it'll be easy to understand for someone that has no experience with the technologies. It's fine to skip the following paragraphs if there is no interest in learning the Python tools used here.

Before we start, install Python. We'll be using Python 2.7 in this example. Please visit http://www.python.org/getit/ for information on installing. Command line examples will be given for both Unix Bash and Windows.

Once Python is installed, enter the following command in the cmd.exe application (Windows):

C:\Python27\Scripts\easy_install.exe Flask

Enter the following command for Unix:

sudo easy_install Flask

Next, create files named app.py and app.html in the development directory we've been working in. We'll use those files for the web application we'll write.

In our sample Flask web application, we're going to dynamically read images from the filesystem to create our gallery with and use a templating engine to generate the HTML markup required for the gallery. Here, we're using a templating engine to dynamically render HTML markup. Previously, the HTML markup we used was manually crafted.

Since the following code snippet is a bit longer, please read the inline comments. The contents of app.py will look like the following:

import os
from flask import Flask, render_template

# Create the application
app = Flask('Galleria', static_folder="../",
    static_url_path="/static", template_folder="./")

# Set the directory where images are stored
image_dir = os.path.join(os.path.dirname(__file__), 'images')


@app.route("/")
def index():
    """
    Run this function for the index page of the web application.

    Images on the filesystem are expected to be in the format forthumbnails:
        image#-200px.jpg

    And this format for large size:
        image#-1600px.jpg
    """
    images = {}
    for filename in os.listdir(image_dir):
        # if the filename does not start with image,
        # it's not a valid gallery image
        if not filename.startswith('image'):
            continue

        # let's find the scale size
        name, size = filename.split('-')
        if name not in images:
            images[name] = {}
        if size.startswith('200px'):
            # thumbnail
            images[name]['thumb'] = filename
        else:
            # full size
            images[name]['image'] = filename
    # render the app.html template with the image data we gathered
    return render_template('app.html', images=images.values())

if __name__ == "__main__":
    app.run()

Here we're setting up the Flask app and setting up one URL—the index page of the site. What the index page of the site shows depends on what is returned in the function we have defined. In our case, we're rendering a template with the values of the images we found on the filesystem.

The app.html file will then look like the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="http://code.jquery.com/jquery.min.js">
    </script>
    <script src="/static/galleria-1.2.8.min.js"></script>
    <script>
      $(document).ready(function(){
        Galleria.loadTheme(
          '/static/themes/classic/galleria.classic.min.js');
        Galleria.run('#galleria');
      });
    </script>
  </head>
<body>
  <div id="galleria" style="height: 500px;">
    {% for image in images %}
      <a href="/static/development/images/{{ image['image'] }}">
        <img src="/static/development/images/{{ image['thumb'] }}" />
      </a>
    {% endfor %}
  </div>
</body>
</html>

The important part of this HTML code is bolded. We're iterating over the set of images provided to the template and rendering the new image URL as the web application knows it.

Finally, to run the application, in the command line, move to the directory where the app.py file is located:

cd galleria/development

Then, run the following command to start up the web application (Windows):

C:\Python27\python.exe app.py

Run the following command to start up the web application (Unix):

python app.py

We should get the following output, letting us know that the Flask app is running correctly:

Finally, in a web browser, enter the address: http://127.0.0.1:5000/.

If all went well, we should see a gallery with the classic theme on the page.

This example works much like the rest of the Galleria example with the exception of the image HTML markup being generated by Python code and the JavaScript, CSS, and images resources being served by the web application.

The advantage of using a web application is that the images used can be dynamically generated. With our application, we could simply add photos to the images directory, also naming them according to the standard we're using, and the gallery will automatically begin using those images.