/jribbble

jQuery plugin for the Dribbble API

Primary LanguageJavaScriptISC LicenseISC

Jribbble Build Status

A jQuery plugin to retrieve info from the Dribbble API

Live demos available on Codepen.io

Dependencies

  • jQuery 1.8+

Getting Jribbble

with Bower

bower install --save jribbble

or direct download:

Using Jribbble

Jribbble covers all non-authenticated methods of the Dribbble API. All available methods are accessed from the jribbble object which is a member of the jQuery or $ object.

Note: If you need access to Dribbble methods using POST or PUT you will need to access the API using OAuth. Jribbble only supports unauthenticated GET methods.

<body>
  <script src="https://code.jquery.com/jquery-2.1.3.min.js"></script>
  <script src="jribbble.min.js"></script>

  <script>
    function success(apiResponse) {
      // do cool stuff with apiResponse
    };

    function error(jqxhr) {
      // Handle errors
    };
    // To use Jribbble you will need to register an application at:
    // https://dribbble.com/account/applications/new
    // Before calling any methods of jribbble you must set your
    // dribbble client access token
    $.jribbble.setToken('<your_dribbble_client_access_token>');

    // Jribbble methods return a promise
    $.jribbble.shots().then(success, error);
  </script>
</body>

Setting your app's client access token

Before you can use any of Jribbble's methods, you must set your Dribbble app's client access token. If you do not have a token, create a new app at https://dribbble.com/account/applications/new

$.jribbble.setToken(token)

Description: Sets the required Dribbble application client access token.

Parameters:

  • token - required String or Int Your Dribbble App client access token

Example usage:

$.jribbble.setToken('123456789');

Available methods

Shots

Users

Teams

Buckets

Projects

Shots

$.jribbble.shots(id, options)

Description: Gets a list of shots.

Parameters:

  • id - optional String or Int A shot id or a shot list name. See API Docs for list names.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. See API Docs for a full list.

Example usage:

// Get a single shot
$.jribbble.shots(2055068).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

// Get the second page of debut shots from the past month sorted by number of
// views at 35 per page.
$.jribbble.shots('debuts', {
  'sort': 'views',
  'timeframe': 'month',
  'per_page': 35
}).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).attachments(attachmentId, options)

Description: Gets the attachments or single attachment for a shot.

Parameters:

  • shotId - required String or Int
  • attachmentId - optional String or Int Only required if you want a single attachment. options are not rejected, but will have no effect when attachmentId is used.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Attachments only support paging options. per_page and page.

Example usage:

// Get all attachments for a shot
$.jribbble.shots(2066347).attachments().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

// Get a single attachment for a shot
$.jribbble.shots(2066347).attachments(370029).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).buckets(options)

Description: Gets the buckets for a shot.

Parameters:

  • shotId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Buckets only support paging options. per_page and page.

Example usage:

// Get all buckets for a shot at 36 per page
$.jribbble.shots(2067006).buckets({'per_page': 36}).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).comments(commentId, options)

Description: Gets the comments or single comment for a shot.

Parameters:

  • shotId - required String or Int
  • commentId - optional String or Int Only required if you want a single comment. options are not rejected, but will have no effect when commentId is used.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Comments only support paging options. per_page and page.

Example usage:

// Get all comments for a shot
$.jribbble.shots(2067969).comments().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

// Get a single comment for a shot
$.jribbble.shots(2067969).comments(4448286).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).comments(commentId).likes(options)

Description: Gets the likes for a comment.

Parameters:

  • shotId - required String or Int
  • commentId - required String or Int The id of the comment
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Likes only support paging options. per_page and page.

Example usage:

// Get the likes for a comment.
$.jribbble.shots(2069352).comments(4450321).likes().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).likes(options)

Description: Gets the likes for a shot.

Parameters:

  • shotId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Likes only support paging options. per_page and page.

Example usage:

// Get the likes for a shot.
$.jribbble.shots(2058881).likes().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).projects(options)

Description: Gets the projects for a shot.

Parameters:

  • shotId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Projects only support paging options. per_page and page.

Example usage:

// Get the projects for a shot.
$.jribbble.shots(2077496).projects().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.shots(shotId).rebounds(options)

Description: Gets the rebounds for a shot.

Parameters:

  • shotId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Rebounds only support paging options. per_page and page.

Example usage:

// Get the rebounds for a shot.
$.jribbble.shots(2046896).rebounds().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

Users

$.jribbble.users(userId)

Description: Gets a single user

Parameters:

  • userId - required String or Int The username or id for the user.

Example usage:

$.jribbble.users('tylergaw').then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).shots(options)

Description: Get a user's shots

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. User's shots only support paging options. per_page and page.

Example usage:

$.jribbble.users('tylergaw').shots().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).buckets(options)

Description: Gets a user's buckets

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Buckets only support paging options. per_page and page.

Example usage:

$.jribbble.users('markbult').buckets().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).projects(options)

Description: Gets a user's projects

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. User projects only support paging options. per_page and page.

Example usage:

$.jribbble.users('creativemints').projects().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).teams(options)

Description: Gets the teams a user belongs to

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. User teams only support paging options. per_page and page.

Example usage:

$.jribbble.users('veerlepieters').teams().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).likes(options)

Description: Gets the shots a user likes

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. User likes only support paging options. per_page and page.

Example usage:

$.jribbble.users('op45').likes().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).followers(options)

Description: Gets a user's followers

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Followers only support paging options. per_page and page.

Example usage:

$.jribbble.users('tylergaw').followers().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).following(options)

Description: Gets the users a user is following

Parameters:

  • userId - required String or Int The username or id for the user.
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Following only support paging options. per_page and page.

Example usage:

$.jribbble.users('tylergaw').following().then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.users(userId).isFollowing(targetUserId)

Description: Check to see if a user is following another user.

Parameters:

  • userId - required String or Int The username or id for the user.
  • targetUserId - required String or Int The username or id for the other user.

Example usage:

$.jribbble.users('tylergaw').isFollowing('jimniels').then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

Teams

$.jribbble.teams(teamId).members(options)

Description: Gets the members of a team.

Parameters:

  • teamId - required String
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Teams only support paging options. per_page and page.

Example usage:

$.jribbble.teams('eight2eight').members(options).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.teams(teamId).shots(options)

Description: Gets the shots for a team.

Parameters:

  • teamId - required String
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Shots only support paging options. per_page and page.

Example usage:

$.jribbble.teams('eight2eight').shots(options).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

Buckets

$.jribbble.buckets(bucketId)

Description: Gets a single bucket

Parameters:

  • bucketId - required String or Int

Example usage:

$.jribbble.buckets(114550).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.buckets(bucketId).shots(options)

Description: Gets the shots for a project

Parameters:

  • bucketId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Shots only support paging options. per_page and page.

Example usage:

// Get the shots for a bucket.
$.jribbble.buckets(114550).shots(options).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

Projects

$.jribbble.projects(projectId)

Description: Gets a single project

Parameters:

  • projectId - required String or Int

Example usage:

$.jribbble.projects(267945).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

$.jribbble.projects(projectId).shots(options)

Description: Gets the shots for a project

Parameters:

  • projectId - required String or Int
  • options - optional Object Key:value pairs of options that will be included in the request as query parameters. Shots only support paging options. per_page and page.

Example usage:

// Get the shots for a project.
$.jribbble.projects(267945).shots(options).then(function(res) {
  // Do cool stuff with response
});

Live example on Codepen.io.

Contributing

Jribbble is open source. Issues and pull requests gladly accepted.

Tests

Jribbble uses Qunit and PhantomJS for tests. If you submit a pull request, you should most likely write a new test or modify an existing test. All tests must pass for a pull request to be accepted.

Installing test dependencies:

npm install && npm install -g node-qunit-phantomjs

running the tests:

make test

The tests will also run when pull requests are submitted. See Travis for build status.

Building Jribbble

Jribbble includes a small Makefile that includes a build task. The task copies the jribbble.js source to the /dist directory–adding the version number and build date–and creates a minified version of it using UglifyJS2.

To build Jribbble you'll need UglifyJS2:

npm install uglify-js -g

then run

make

from the root directory