Skip to content
Browse files

Add PDoc documentation for Flickr API classes.

  • Loading branch information...
1 parent ecb1fe0 commit cb215466d3abe55fa702b9f8b76ad7b8ca5f6166 @jcoglan jcoglan committed Sep 23, 2009
Showing with 203 additions and 1 deletion.
  1. +1 −0 .gitignore
  2. +24 −0 README.markdown
  3. +91 −0 source/flickr.js
  4. +42 −0 source/jsonp.js
  5. +42 −0 source/photo.js
  6. +3 −1 test/index.html
View
1 .gitignore
@@ -1,4 +1,5 @@
build
+pdoc
test/lib
test/packages.js
View
24 README.markdown
@@ -0,0 +1,24 @@
+Flickr
+======
+
+A simple wrapper around the [Flickr JSONP API](http://www.flickr.com/services/api/response.json.html).
+No scripts from Flickr are required in advance since they provide a raw JSONP
+service; it is up to clients how they want to consume it.
+
+
+Usage
+-----
+
+Instantiate a client using your Flickr API key:
+
+ client = new Flickr.Client('63bb4efae64c3c04510c484dcdaef263');
+
+The client provides convenience methods for calling various feeds, for example:
+
+ client.getGroupPhotos('52240328087@N01', function(feed) {
+ for (var i = 0, n = feed.length; i < n; i++)
+ alert(feed[i].getTitle());
+ });
+
+See the `Flickr.Client` and `Flickr.Photo` classes for more information.
+
View
91 source/flickr.js
@@ -1,9 +1,37 @@
+/**
+ * == flickr ==
+ **/
+
+/** section: flickr
+ * Flickr
+ **/
Flickr = {
+ /**
+ * class Flickr.Client
+ * Provides a JavaScript API to methods in the Flickr web service API.
+ **/
Client: new JS.Class({
+ /**
+ * new Flickr.Client(key)
+ * - key (String): Your site's Flickr API key
+ * Clients are instantiated using a Flickr API key. If none is provided, the
+ * value of `Flickr.API_KEY` is used instead.
+ **/
initialize: function(key) {
this._key = key || Flickr.API_KEY;
},
+ /**
+ * Flickr.Client#call(method, params, callback, scope) -> undefined
+ * - method (String)
+ * - params (Object)
+ * - callback (Function)
+ * - scope (Object)
+ *
+ * Calls the named `method` in the Flickr JSONP API, with the given set
+ * of `params`. The `callback` is called in the given `scope` with the
+ * response from the JSONP service.
+ **/
call: function(method, params, callback, scope) {
method = /^flickr\./.test(method) ? method : 'flickr.' + method;
params = JS.extend({
@@ -13,45 +41,108 @@ Flickr = {
Flickr.JSONP.request(Flickr.REST_ENDPOINT, params, callback, scope);
},
+ /**
+ * Flickr.Client#feed(path, params, callback, scope) -> undefined
+ * - path (String)
+ * - params (Object)
+ * - callback (Function)
+ * - scope (Object)
+ *
+ * Fetches the named feed and calls `callback` in the given `scope` with
+ * the response from the JSONP feed service.
+ **/
feed: function(path, params, callback, scope) {
path = /\.gne$/.test(path) ? path : path + '.gne';
Flickr.JSONP.request(Flickr.FEED_ENDPOINT + path, params, callback, scope);
},
+ /**
+ * Flickr.Client#groupBrowse(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ **/
groupBrowse: function(id, callback, scope) {
this.call('groups.browse', {cat_id: id}, callback, scope);
},
+ /**
+ * Flickr.Client#groupInfo(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ **/
groupInfo: function(id, callback, scope) {
this.call('groups.getInfo', {group_id: id}, callback, scope);
},
+ /**
+ * Flickr.Client#groupDiscuss(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ **/
groupDiscuss: function(id, callback, scope) {
this.feed('groups_discuss', {id: id}, callback, scope);
},
+ /**
+ * Flickr.Client#groupPool(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ **/
groupPool: function(id, callback, scope) {
this.feed('groups_pool', {id: id}, callback, scope);
},
+ /**
+ * Flickr.Client#photoFavourites(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ **/
photoFavourites: function(id, callback, scope) {
this.feed('photos_faves', {id: id}, callback, scope);
},
+ /**
+ * Flickr.Client#getGroupPhotos(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ *
+ * Feed items are wrapped as `Flickr.Photo` objects.
+ **/
getGroupPhotos: function(id, callback, scope) {
var wrap = this._wrapPhotos;
this.groupPool(id, function(data) {
callback.call(scope, wrap(data));
});
},
+ /**
+ * Flickr.Client#getFavourites(id, callback, scope) -> undefined
+ * - id (String)
+ * - callback (Function)
+ * - scope (Object)
+ *
+ * Feed items are wrapped as `Flickr.Photo` objects.
+ **/
getFavourites: function(id, callback, scope) {
var wrap = this._wrapPhotos;
this.photoFavourites(id, function(data) {
callback.call(scope, wrap(data));
});
},
+ /**
+ * Flickr.Client#_wrapPhotos(data) -> Array
+ * - data (Array)
+ *
+ * Takes a list of feed items from the Flickr API and wraps them up as
+ * instances of `Flickr.Photo`.
+ **/
_wrapPhotos: function(data) {
var photos = [];
for (var i = 0, n = data.items.length; i < n; i++)
View
42 source/jsonp.js
@@ -1,15 +1,46 @@
+/**
+ * Flickr.JSONP
+ *
+ * Provides a simple API for making JSONP requests. Contains some
+ * Flickr-specific code so clients can avoid entering required
+ * fields with every request.
+ *
+ * JSONP works by generating a global function to receive data from
+ * the third party server, then injecting a `script` element into
+ * the DOM to make the request. The service will call the generated
+ * handler, which itself calls the user's callback function and removes
+ * itself from the global namespace.
+ **/
Flickr.JSONP = {
_counter: 0,
CALLBACK_BASE: '__jsonpcb__',
+ /**
+ * Flickr.JSONP.getCallbackName() -> String
+ * Returns a unique generated name to use for a callback function.
+ **/
getCallbackName: function() {
return this.CALLBACK_BASE + (this._counter++);
},
+ /**
+ * Flickr.JSONP.encode(string) -> String
+ * - string (String)
+ *
+ * Returns a URL-encoded copy of `string`.
+ **/
encode: function(string) {
return encodeURIComponent(decodeURIComponent(string));
},
+ /**
+ * Flickr.JSONP.buildURL(path, params) -> String
+ * - path (String)
+ * - params (Object)
+ *
+ * Constructs a URL using the given `path` and set of `params`, which
+ * are serialized as a query string.
+ **/
buildURL: function(path, params) {
if (params === undefined) return path;
for (var key in params) {
@@ -20,6 +51,17 @@ Flickr.JSONP = {
return path;
},
+ /**
+ * Flickr.JSONP.request(path, params, callback, scope) -> undefined
+ * - path (String)
+ * - params (Object)
+ * - callback (Function)
+ * - scope (Object)
+ *
+ * Makes a request to a JSONP service with the given `path` and `params`,
+ * and calls `callback` in the given `scope` with the return value from
+ * the JSONP service.
+ **/
request: function(path, params, callback, scope) {
var callbackName = this.getCallbackName();
View
42 source/photo.js
@@ -1,17 +1,58 @@
+/**
+ * class Flickr.Photo
+ * Provides a wrapper object for items from Flickr photo feeds.
+ **/
Flickr.Photo = new JS.Class({
+ /**
+ * new Flickr.Photo(feedData)
+ **/
initialize: function(feedData) {
this._data = feedData;
},
+ /**
+ * Flickr.Photo#getTags() -> Array
+ **/
getTags: function() {
var tags = this._data.tags;
return (tags === '') ? [] : tags.split(/\s+/);
},
+ /**
+ * Flickr.Photo#getThumbnail() -> String
+ **/
getThumbnail: function() {
return this._data.media.m;
},
+ /**
+ * Flickr.Photo#getAuthor() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getAuthorId() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getDateTaken() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getDescription() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getLink() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getPublished() -> String
+ **/
+
+ /**
+ * Flickr.Photo#getTitle() -> String
+ **/
+
extend: {
METHOD_MAPPINGS: {
Author: 'author',
@@ -26,6 +67,7 @@ Flickr.Photo = new JS.Class({
});
(function() {
+ // Generate accessor methods for fields in Flickr API objects
var map = Flickr.Photo.METHOD_MAPPINGS;
for (var key in map) (function(method, property) {
Flickr.Photo.define('get' + method, function() {
View
4 test/index.html
@@ -24,7 +24,9 @@
require('Flickr', function() {
Client = new Flickr.Client('63bb4efae64c3c04510c484dcdaef263');
- window.console && console.log(Client);
+ Client.getGroupPhotos('52240328087@N01', function(r) {
+ window.console && console.log(r[0].getTitle());
+ });
});
</script>

0 comments on commit cb21546

Please sign in to comment.
Something went wrong with that request. Please try again.