One of the most popular questions from Galleria users is: "How can I add a menu that loads different sets into my gallery when clicked?". This small guide/tutorial will explain step by step how this is done. At the same time we will create a nice looking gallery that you can use as a starting point when building your Galleria-powered portfolio site.

Before we begin, you might want to look at what we will be creating.

Let me also start by saying that everything in this tutorial is open sourced and MIT licensed so you can grab whatever you like and use it for anything you want. We will only use the free components and themes from Galleria.

In this example, we will pull two of my photo sets from my trip to South East Asia in 2006 that I have on Flickr. We will use the Galleria Flickr plugin to pull the sets, and some custom javascript and CSS to put everything together.

First: some markup

Let’s just start by creating some simple HTML markup:

<div id="container">
    <div id="menu">
        <a href="http://flickr.com/photos/davidhellsing/sets/72057594078378762/">Asia</a>
        <a href="http://flickr.com/photos/davidhellsing/sets/72057594102602315/">Asia 2</a>
    </div>
    <a id="fullscreen" href="#">Enter fullscreen</a>
    <div id="gallery">
        <div id="galleria"></div>
    </div>
</div>

The #menu div contains two links to my sets on Flickr. This will make the links “work” even if javascript should be turned off. The #gallery div is the gallery holder, and the #galleria div is a holder for the galleria instance. We also added a #fullscreen link that we will hook up with Galleria’s fullscreen functionality later on.

CSS

I made some styles for this as well, pretty straight forward:

html,
body { background:#111 url(broken_noise.png); font:13px/1.3 arial,sans-serif }
a { color:#823; text-decoration:none }
#container { width:960px; margin:20px auto; position:relative}
#gallery { width:780px; height:500px; float:right; position:relative; border:10px solid #141414 }
#galleria { width:100%; height:100%; background:#000 }
#loader { width:200px; height:100px; margin:-50px 0 0 -100px; position:absolute; left:50%; top:50%; color:#fff; text-align:center;
    z-index:4; display:none; background:#000 url('loader.gif') no-repeat 50% 25px; opacity:.8; line-height:150px; border-radius:6px }
#menu { width:140px; float:left; border-top:1px solid #2b2b2b }
#menu a { display:block; padding:10px 6px; border-bottom:1px solid #2b2b2b }
#menu a:hover { background:#151515; background:rgba(0,0,0,.1); }
#menu a.active { background:#111; background:rgba(0,0,0,.3); color:#fff }
#fullscreen { position:absolute; top:500px; left:0 }
#fullscreen:hover { color:#fff }

The important part here is that we provide a width & height for the #gallery div and then let the #galleria div stretch across the entire parent. This way, Galleria will know what size it should use when running the initialization.

We also added styles for the #loader, a small notification growl that let’s the user know when and what we are pulling from flickr.

This example uses a minimal interface with almost no graphics, I found the background pattern at the excellent subtlepatterns.com and the loader is a simple loader gif that can be generated on several sites for free.

Load javascript dependencies

We need to load some scripts here to get started with the functionality. For this demo we’ll load jQuery, Galleria and Galleria Flickr:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
<script src="galleria-1.2.6.min.js"></script>
<script src="plugins/flickr/galleria.flickr.min.js"></script>

Wrapping it up in a HTML5 template

Let’s just put this all in a simple HTML5 template and see how we are doing. Full code below, and here is a link to the demo at this stage, just before we get started with the actual scripting of the gallery.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Galleria – Photo categories</title>

    <!-- styles for this demo -->
    <style>
    html,
    body { background:#111 url(broken_noise.png); font:13px/1.3 arial,sans-serif }
    a { color:#823; text-decoration:none }
    #container { width:960px; margin:20px auto; position:relative}
    #gallery { width:780px; height:500px; float:right; position:relative; border:10px solid #141414 }
    #galleria { width:100%; height:100%; background:#000 }
    #loader { width:200px; height:100px; margin:-50px 0 0 -100px; position:absolute; left:50%; top:50%; color:#fff; text-align:center;
        z-index:4; display:none; background:#000 url('loader.gif') no-repeat 50% 25px; opacity:.8; line-height:150px; border-radius:6px }
    #menu { width:140px; float:left; border-top:1px solid #2b2b2b }
    #menu a { display:block; padding:10px 6px; border-bottom:1px solid #2b2b2b }
    #menu a:hover { background:#151515; background:rgba(0,0,0,.1); }
    #menu a.active { background:#111; background:rgba(0,0,0,.3); color:#fff }
    #fullscreen { position:absolute; top:500px; left:0 }
    #fullscreen:hover { color:#fff }
    </style>

    <!-- load jQuery -->
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>

    <!-- load Galleria -->
    <script src="galleria-1.2.6.min.js"></script>

    <!-- load flickr plugin -->
    <script src="plugins/flickr/galleria.flickr.min.js"></script>

</head>
<body>
    <div id="container">
        <div id="menu">
            <a href="http://www.flickr.com/photos/davidhellsing/sets/72057594078378762/">Asia</a>
            <a href="http://www.flickr.com/photos/davidhellsing/sets/72057594102602315/">Asia 2</a>
        </div>
        <a id="fullscreen" href="#">Enter fullscreen</a>
        <div id="gallery">
            <div id="galleria"></div>
        </div>
    </div>
</body>
</html>

There we go, a nice looking template. You could also put som stuff in the #galleria div if you want to provide more information for users without javascript turned on. Now, let’s get started with the javascript.

The javascript

The script needs to do several things:

  • Load the galleria theme (classic)
  • Create a Galleria.Flickr instance
  • Attach a click event listener on the menu links
  • Parse out the set ID from the link and use it to pull the images
  • Insert the loaded data into the Galleria gallery
  • Initially, just load the first photo set from the menu onload

Let’s start with the first two things:

// load the theme
Galleria.loadTheme('themes/classic/galleria.classic.min.js');

// create a flickr instance
var flickr = new Galleria.Flickr();

Next, let’s just cache some elements and create the loader growl:

// cache the gallery
var elem = $('#galleria');

// create and append the loader growl
var loader = $('<div>', {
    id: 'loader'
}).appendTo('#gallery');

// a local var used later
var set;

The loader will be used to notify the user what gallery is loading, and when it’s ready. Let’s move on to the flickr instance – we need to set some options, because I want more than the default 30 images, and I also want to pull the image description:

// set flickr to fetch description and increase the photo limit
flickr.setOptions({
    max: 100,
    description: true
});

There are more Flickr options available, and you can read them all in the Galleria docs.

Next up is the click handler. Thanks to jQuery, the complexity of javascript events has been greatly reduced and normalized. Let’s just start by attaching the event, then prevent the click from actually opening the Flickr URL and add an active class:

// attach event handler for the menu
$('#menu a').click(function(e) {

    e.preventDefault();

    // toggle active class
    $(this).addClass('active').siblings('.active').removeClass('active');

Now we need to extract the flickr ID from the link. The set ID is shown in bold here: http://flickr.com/photos/davidhellsing/sets/72057594078378762/

I’m doing this by splitting the string into an array on all slashes, then just pick out the next last entry in the array. But you could also do this using RegExp:

    // extract the set id from the link href
    set = this.href.split('/');
    set = set[set.length-2];

Next up is the growl, I’m going to extract the link text and place it inside the growl to let the user know what gallery is loading:

   // add loader text and show
    loader.text('Loading '+$(this).text()).show();

OK, so everything is prepared for the Galleria.Flickr instance to start pulling the set. We do this by using the .set() API call from the flickr instance. I’m going to paste more code here, but it’s all commented and I will walk you through it afterwards:

    // load the set
    flickr.set(set, function(data) {

        // hide the loader
        loader.fadeOut('fast');

        // check if galleria has been initialized
        if (elem.data('galleria')) {

            // load galleria with the new data
            elem.data('galleria').load( data );

        // else initialize galleria (1st time)
        } else {
            elem.galleria({

                // add the data as dataSource
                dataSource: data,

                // add a custom fullscreen button
                extend: function() {
                    $('#fullscreen').click(this.proxy(function(e) {
                        e.preventDefault();

                        // call the enterFullscreen() method from the galleria API
                        this.enterFullscreen();
                    }));
                }
            });
        }
    });

So, first we pass our set ID to the flickr.set function. That gives us a callback with the pulled image data array as the only argument. This data is already parsed and ready to be injected in a Galleria gallery. Next, we fade out the growl since the pull has been completed.

When this is done, we need to check if Galleria has been initialized before. When initializing Galleria, it will give you the instance inside the $.data object related to the element that the gallery was attached to. If the gallery was initialized already, we can just do the .load() call and be done with it:

// check if galleria has been initialized
if (elem.data('galleria')) {

    // load galleria with the new data
    elem.data('galleria').load( data );

If there is no instance, we need to initialize Galleria and pass the data as dataSource. We will also attach the fullscreen functionality to the #fullscreen link in our template:

elem.galleria({

    // add the data as dataSource
    dataSource: data,

    // add a custom fullscreen button
    extend: function() {
        $('#fullscreen').click(this.proxy(function(e) {
            e.preventDefault();

            // call the enterFullscreen() method from the galleria API
            this.enterFullscreen();
        }));
    }
});

When this is done, all we need to do is to trigger a click for the first menu item, so the users sees the first gallery when entering the demo:

// trigger a click onload so that the first gallery will be displayed when entering
$('#menu a:first-child').click();

Phew

OK, we are done with the scripting! I hope you where able to follow somewhat and that you learned something about how Galleria can be customized to be able to work as a main engine for a slick, nice looking portfolio site.

And of course, here is a full working demo to enjoy.

Happy holidays and good luck with your future Galleria projects!

The Galleria team