Having a small rotation of background images is a fun and simple way to keep your landing page fresh, but comes with a challenge of attributing the creators of the images displayed on your site. Our JavaScript library gally.js helps to solve this problem, and won’t have you starting a whole new pile of no-attribution-required background images.

While working on our acorn30 subsidiary site, Neighbourhood Domains, I created a simple JavaScript library which dynamically displays the attribution information of the randomly selected background image’s owner, complete with a link to their site. The library is free to use, nicknamed internally as “gally” as it is effectively a lightweight gallery management tool, and can be downloaded from Github or dropped right into projects via RawGit. It’s all commented and you can browse the JSDoc documentation here.

An example site is provided on Github, but you’ll need to understand how your specific needs and preferences will affect the way images need to be organized on your site. gally.js is all client-side code, and is therefore dependent on you explicitly outlining the way your site’s images are organized in order to be utilised.

What follows is a detailed example case for gally.js setup and usage.

Image Files

gally.js obtains a set of background images based off the file hierarchy of your site as specified. Be familliar with where on the site your images are located, as well as their filenames and filetypes. Here is an example of a simple landing page not using gally.js, which has a static background and image attribution link:

By adding the following line to the head of your HTML, you will have access to gally.js JavaScript functions, and can use them to set the background of your page to a random image from a pool of images, among other things.

<script type="text/javascript" src="https://cdn.rawgit.com/acorn30/gally/4544c9a8/a30gally.js"></script>

Let’s say the site has the following directories:

/images/backgrounds/

/philip/ contains:

/philip/

/hubert/ contains:

/hubert/

/hermes/ contains:

/hermes/

The owner of the /philip/ images is known professionally as Philip J. Fry, and had a website at http://philip.acorn30.com. As you can see, Philip has his own directory, /philip/, within the site’s image directory /backgrounds/. It contains his image files with numerically assigned names starting from 1, a requirement for gally.js to work.

Though this file naming convention is somewhat laborious when adding and removing background images from your site, with this organization structure the JavaScript library will accomplish your needs without the use of server-side code. If you need to attribute a large number of background images it would be more effective to look into alternative solutions which utilise server-side code.

Hubert and Hermes also have their own subdirectories in the site’s directory of background images, and follow the same naming conventions as Philip’s directory. What follows is how you would add the Philip, Hubert, and Hermes directories to the pool of images that will be randomly selected as landing page backgrounds for site visitors.

In the HTML body:

<script type="text/javascript">

// Set the path to the parent directory
setParentDirectory(“/images/backgrounds”);
// Add Authours to the page
addAuthour("philip", 2, "http://philip.example", "Philip J. Fry");
addAuthour("hubert", 3, "http://hubert.example", "Hubert Farnsworth");
addAuthour("hermes", 4, "http://hermes.example", "Hermes Conrad");

</script>

gally.js’s setParentDirectory function tells gally.js the location of the directory on your site containing your pool of image authours, in this case /images/backgrounds/.
gally.js’s addAuthour function requires the following parameters:
1 – The name of the directory, for example /philip/
2 – The number of labelled image in this directory, in Philip’s case: 2.
3 – The site of the image authour which will be linked to, in this case “http://philip.example”
4 – The full professional name of the owner of this image, here Philip J. Fry.

addAuthour("philip", 2, "http://philip.example", "Philip J. Fry");

So, now that gally.js has the information about which images are available to select the setBackgroundImage function can be used to randomly set a background for the page:

<script type="text/javascript">

// Set the path to the parent directory
setParentDirectory(“/images/backgrounds”);
// Add Authours to the page
addAuthour("philip", 2, "http://philip.example", "Philip J. Fry");
addAuthour("hubert", 3, "http://hubert.example", "Hubert Farnsworth");
addAuthour("hermes", 4, "http://hermes.example", "Hermes Conrad");
// Randomly select one of the images and set as page background
setBackgroundImage();

</script>

File Extensions

There’s a problem. Let’s look back at the example directories.

/images/backgrounds/

/philip/ contains:

/philip/

/hubert/ contains:

/hubert/

/hermes/ contains:

/hermes/

Because gally.js is entirely JavaScript and client-side, if it gets the file extension for an image incorrect the result will be a blank background. If all your background images are the same file type, PNG for example, gally.js has a very simple solution. If all your images are jpegs (.jpg) there is no need for worry, as jpeg is the default for gally.js unless specified as otherwise using the setDefaultFileTypefunction.

For example:
setDefaultFileType(“png”); if all your images are PNGs
setDefaultFileType(“gif”); if all your images are gifs

Usage would look something like this:

<script type="text/javascript">

// All background images are PNGs, set png as default file extension
setDefaultFileType(“png”);
// Set the path to the parent directory
setParentDirectory(“/images/backgrounds”);
// Add Authours to the page (only Hernes in this case)
addAuthour("hermes", 4, "http://hermes.example", "Hermes Conrad");
// Randomly select one of the images and set as page background
setBackgroundImage();

</script>

If you have a mix of filetypes, such as some JPEGs and some PNGs like in our example, the gally.js function addImageSpecialCase and possibly addAuthourSpecialCase should be used.
Consider the following:

/philip/ contains only JPEGs (.jpg)

/hubert/ contains 2 JPEGs and 1 PNG (.png)

/hermes/ contains only PNGs

For /hubert/ only one image is a PNG.

So, a special case for specifically Hubert’s third image will be added via addImageSpecialCase.

addImageSpecialCase(“hubert”, 3, “png”);

For /hermes/, every image in the directory is a PNG.

So, we will use addAuthourSpecialCase to note that all of his images use .png as their file extension.

addAuthourSpecialCase(“hermes”, “png”);

Here’s how our script in the html is looking:

<script type="text/javascript">

// Set the path to the parent directory
setParentDirectory(“/images/backgrounds”);
// Add Authours to the page
addAuthour("philip", 2, "http://philip.example", "Philip J. Fry");
addAuthour("hubert", 3, "http://hubert.example", "Hubert Farnsworth");
addAuthour("hermes", 4, "http://hermes.example", "Hermes Conrad");
// Note special cases
addImageSpecialCase("hubert", 3, "png");
addAuthourSpecialCase("hermes", "png");
// Randomly select one of the images and set as page background
setBackgroundImage();

</script>
The following are among the results we get:

Attribution

Great! Both our JPEGs and our PNGs are working fine, however we haven’t given gally.js a place to attribute the images! To utilise the attribution features, we need an element in the HTML to display the information. For example:

Background photo by: <a id="credit" class="active" href="#" target="_blank"></a>

Which appears as:

We have an element to provide the background attribution, but we still need to tell gally.js where to put the information. By giving the link the id “credit” adding image credits it’s just a matter of placing that id as a parameter for the setBackgroundImage function:

setBackgroundImage(“credit”);

So, with that change in place you will see the following results:

The link is automatically set to the appropriate site!

You may wish to adapt the code in gally.js to your own needs, in which case you are welcome to do so!
You can check out gally.js in action on http://neighbourhooddomains.com/ or on the example site hosted on Github.

Thanks for reading!

Elisha Sarkis
Junior Web Developer