Plugin

Introduction

Flickr is an image hosting and video hosting website, web services suite, and online community that was created by Ludicorp in 2004 and acquired by Yahoo! in 2005. Flickr offers a fairly comprehensive web-service API that enables programmers to create applications that can perform almost any function that a user on the Flickr site can do. The Glickr plugin aims to provide (as time passes) a feature complete implementation of the Flickr API by providing a Grails service and native Groovy classes that wrap the API. So rather than having to deal with individual and Flickr specific API methods, the Glickr Plugin wraps API calls in native classes and provides typical Grails methods like '.getByUsername()' or '.findAll()'

Installation

Installation is pretty straight-forward, since the plugin currently has no further dependencies, you start the command prompt and type:

grails install-plugin glickr

Alternatively, you can download the Glickr Plugin manually from the Grails website

Configuration

To work with the Flickr API, you need an API Key that can be requested at Flickr website. Put the information provided by Flickr in the following entries in your Grails configuration file (e.g. Config.groovy):

grails.plugins.glickr.apiKey    = 'YOUR_FLICKR_API_KEY'
grails.plugins.glickr.apiSecret = 'YOUR_FLICKR_API_SECRET'

After succesfully installing the Glickr Plugin in your Grails project, you'll have a service available to interact with the Flickr API:

flickrService

Getting Started

The examples below might be a bit verbose (un-Groovy) but it'll help to understand what the service does for you and what Groovy classes are available.

FlickrPeople people = flickrService.getPeopleById('86869926@N02')

The will result in one of 3 scenarios:

• A user (called People in Flickr API jargon) with provided ID is found and returned as an instantiated object of class FlickrPeople
• A NULL object is returned when no user with the provided ID is found
• In any other scenario, something is wrong with the configuration, the syntax or even the actual Flickr server. In that case an exception of type FlickrServiceException will be thrown. For more information on possible exceptions and how to deal with them; please read this blogpost.

Several other methods of getting a FlickrPeople object are:

FlickrPeople people = flickrService.getPeopleByUsername('glickr.org')
FlickrPeople people = flickrService.getPeopleByEmail('edwin@glickr.org')

But the most important thing on Flickr are of course images, so let's look at a couple of example how to find and deal with photos.

FlickrPhoto photo = flickrService.getPhotoById(7955082398)

Well, you'll get the picture (pun intended), or a NULL object, or a flavor of FlickrServiceException. While the previous examples returns an object of the class FlickrPhoto, it is a pretty empty object to begin with, just some basic metadata and URL to link back to Flickr.

A photo hosted on Flickr can have lots of additional information, metadata, or geo-data and can be retrieved in multiple sizes (depending on what the was uploaded and provided by the owner of the photo). In order to 'decorate' a FlickrPhoto with more data you can call 'getPhotoDetails' to have fill all attributes:

FlickrPhoto photo = flickrService.getPhotoById(7955082398)
photo = flickrService.getPhotoDetails(photo)
println photo.shortUrl
println photo.title
println photo.sourceWidth
println photo.sourceHeight
println photo.sourceUrl

Clearly, the former method 'getPhotoById' is much faster, specially since the latter 'getPhotoDetails' will execute multiple individual calls to the Flickr API in order to collect all metadata. There's also a tag for easier HTML rendering of a FlickrPhoto object:

Just like there is a tag for easier rendering of a FlickrPeople object: There's also a tag for easier rendering of a FlickrPhoto object to HTML

From a FlickrPeople object you can also get a set of public FlickrImage objects that are published by this 'user':

FlickrPeople people = flickrService.getPeopleByUsername('glickr.org')
FlickrPhotoSet photos = flickrService.getPeoplePublicPhotos(people)

Several different signatures for the same functionality:

def photos = flickrService.getPeoplePublicPhotosById('86869926@N02')
def photos = flickrService.getPeoplePublicPhotosByUsername('glickr.org')
def photos = flickrService.getPeoplePublicPhotosByEmail('edwin@glickr.org')

The most versatile function to retrieve images is the Search function of the Flickr API, implemented in the flickService as 'findAll()'. For the initial release of the Glickr Plugin, we implemented about 50% of the possibilities of this method. First, a straightforward find all images that are associated with a text (i.e. the text appears in the title or description of the image).

FlickrPhotoSet photos = flickrService.findAll([text='sp91052'])

Or provide some additional parameters, to browse to bigger result sets:

FlickrPhotoSet photos = flickrService.findAll([text='PCD0992', page=1, perPage=10])

The Glickr Plugin also provides for a couple of Enums to handle additional options for the search function. Different scenarios are show in the example below while searching in the 'tags' of images on Flickr:

// example
def params
FlickrPhotoSet photos

// search on one tag
params = [tags:'GlickrTest']
photos = flickrService.findAll(params)

// search on multiple tags, defaults to 'Any' match
params = [tags:'GlickrTest,Horizontal']
photos = flickrService.findAll(params)

// search on multiple tags, make 'Any' explicit by using the TagMode Enum
params = [tags:'GlickrTest,Horizontal',tagMode:TagMode.Any]
photos = flickrService.findAll(params)

// search on multiple tags, result meets all tags
params = [tags:'GlickrTest,Horizontal',tagMode:TagMode.All]
photos = flickrService.findAll(params)

Similarly, there is an Enum to specify the types of content to return

// example
def params
FlickrPhotoSet photos

// ContentType.All is the default value
params = [text:'PCD0992',contentType: ContentType.All]  // default
photos = flickrService.findAll(params)

// or
params = [text:'PCD0992',contentType: ContentType.Photos]
params = [text:'PCD0992',contentType: ContentType.Screenshots]
params = [text:'PCD0992',contentType: ContentType.Other]
params = [text:'PCD0992',contentType: ContentType.PhotosAndScreenshots]
params = [text:'PCD0992',contentType: ContentType.ScreenshotsAndOther]
params = [text:'PCD0992',contentType: ContentType.PhotosAndOther]