Originally published at: http://www.sitepoint.com/creating-image-gallery-using-flickr-api-requirements-markup/
Without any doubt, APIs play a very important role today. Web services from small to big are required to expose their data through an API that developers can use to create a new service on top of them. Think of big companies like Google, Yahoo!, Twitter and Microsoft: all of them offer APIs for their services. Example uses of the data provided by these APIs are SnapBird, a tool offering extended search options on Twitter, and JoindIn.js, a library I developed that creates widgets based on the data provided by JoindIn.
In this two-part article, I’ll show you how to use the Flickr API to develop a simple service that allows a user to enter text in a search field, and which then displays a gallery of images from Flickr whose title or description match that text. This will be a great chance both to play with a third-party API and to study some nice techniques along the way.
The source code of the project is accessible on my GitHub account in the repository named Flickr gallery demo.
The Requirements
Before we write any code, it’s important to understand how the service will be developed. First of all, our project will be made of a single HTML page comprising three main components: a header, a gallery, and a list of thumbnails.
The header will contain the page’s title and a search form that the user can employ to find the photos matching the given text.
The gallery will sit beneath the header and will show the image chosen in its natural size, up to a fixed width and height (we don’t want the image to overflow our layout, do we?). The gallery will also feature left and right buttons to show the previous and next images respectively.
Finally, we’ll have a list of thumbnails of the photos below the gallery. We don’t want the list to become too long, so we’ll paginate the photos matched and show up to 15 photos on each page, displayed in three rows. (In this project, clicking on the right arrow won’t cause the next page of thumbnails to load. However, after reading this series, you can update to code to trigger this action if you wish.)
The whole service will be developed paying attention to accessibility, so along the way we’ll employ the relevant role attribute where it makes sense and also ensure that it’s possible to navigate the website and trigger the various actions through the use of the TAB and ENTER keys.
The result of our efforts is shown in the image below:
Class Name Conventions
Although the project on its own isn’t complex, I’ll use the BEM methodology to name the classes used in addition to some helpers. Some might think that it’s overkill, but I think this is a nice opportunity to learn a new methodology you might not be familiar with. The class names used for styling purposes won’t be used as JavaScript hooks. So, if a piece of JavaScript needs to retrieve one or more elements, instead of using the existing class names, I’ll add a specific class name to the elements, prefixed with js-. This is a common technique used by many developers to separate class names and JavaScript hooks. To reinforce the concept, let’s briefly discuss an example.
Let’s say we have defined the gallery element as such:
<div class="gallery"><!-- other code goes here --></div>
The gallery class name is used to style the element, but the latter needs to be retrieved by a JavaScript function to perform some actions. Instead of retrieving the element using the gallery class name as shown below:
var gallery = document.getElementsByClassName('gallery')[0];
I’ll add another class named js-gallery:
<div class="js-gallery gallery"><!-- other code goes here --></div>
Then I’ll retrieve the elements like so:
var gallery = document.getElementsByClassName('js-gallery')[0];
Doing it this way ensures that, even if later in the project the gallery class name is renamed or removed, the JavaScript code will still work. In case you don’t like the js- prefix, I’ve read that some developers use the do- prefix to highlight the fact that the element is used to perform an action. Both conventions are equivalent and you can choose the one you like the most.
Having established the goals, components and conventions of our project, let’s start the fun!
The Markup
The first step in creating our service is to write the markup of the page, and we’ll start with the header.
The Header
The HTML needed for the header is very simple. We’ll wrap both the elements described in the previous section – the title and the form – with a header element. The title of the page is defined by an h1 element and the form by a form element. The form is made of a label, an input where the user can write the text to search, and a button to submit the request. The label is tied to the input by using the for attribute.
The form will also have a role="search" attribute, because we want to highlight that it’s a search form, and the type of the input will be search. Finally, we’ll add a class named form-search for styling purposes and a js-form-search class that will be used by JavaScript to retrieve the text entered by the user.
The full code of the header is presented below:
<header class="island"> # Flickr gallery <form class="js-form-search form-search" action="/search" method="get" role="search"><label for="query">Search:</label><input type="search" name="query" id="query" placeholder="Search" required=""/><input type="submit" value="Search"/></form></header>
Let’s now discuss the most important element of the markup – the gallery.
The Gallery
The gallery is composed of three different small elements: the img element used to show the selected image in its natural size, and the left and right arrows for changing the image displayed. Both arrows will be created using a button element. It’s the right choice because we want to perform an action when they are clicked. Visually, the buttons will look like arrows, but this is only meaningful for a sighted person. From the perspective of a visually impaired user, the arrows are completely useless. For this reason we have to enhance these buttons by providing an indication of their role. We’ll do that by adding text as the content of the buttons – text that is visually hidden but accessible to a screen reader. The technique employed below is taken from the HTML5 Boilerplate project and uses a class named visually-hidden.
The complete HTML code of the gallery is as follows:
<div class="island"><div class="js-gallery gallery">![]()<button class="js-gallery__arrow--left gallery__arrow gallery__arrow--left"><span class="visually-hidden">Previous photo</span></button><button class="js-gallery__arrow--right gallery__arrow gallery__arrow--right"><span class="visually-hidden">Next photo</span></button></div></div>
Before we’re done with the markup, there’s one last component to discuss – the thumbnails list.
The Thumbnail Images List
The last component is made of two very simple sub-components: the list of thumbnail images of the current page and the pager. Both are defined as a list, but the first is an unordered list while the second is an ordered list. Both these lists need to be generated on the fly using JavaScript, so we’ll add a js- prefixed class name on them.
The code of this last component is presented below:
<div class="island thumbnails"><ul class="js-thumbnails__list thumbnails__list"></ul><ol class="js-thumbnails__pager thumbnails__pager"></ol></div>
With this last snippet, we’ve completed our discussion of the markup of the page, so it’s time to give it some style.