# Jribbble [](https://travis-ci.org/tylergaw/jribbble) A jQuery plugin to retrieve info from the [Dribbble API](http://developer.dribbble.com/v1/) Live demos available on [Codepen.io](http://codepen.io/collection/nWvjrg/) ## Dependencies * jQuery 1.8+ ## Getting Jribbble with Bower ``` bower install --save jribbble ``` or direct download: - [jribbble.min.js](https://github.com/tylergaw/jribbble/blob/master/dist/jribbble.min.js) - [jribbble.js](https://github.com/tylergaw/jribbble/blob/master/dist/jribbble.js) ## Using Jribbble Jribbble covers all non-authenticated methods of the [Dribbble API](http://developer.dribbble.com/v1/). 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. ```html <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](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:** ```javascript $.jribbble.setToken('123456789'); ``` ## Available methods #### Shots - [$.jribbble.shots](#jribbbleshotsid-options) - [$.jribbble.shots.attachments](#jribbbleshotsshotidattachmentsattachmentid-options) - [$.jribbble.shots.buckets](#jribbbleshotsshotidbucketsoptions) - [$.jribbble.shots.comments](#jribbbleshotsshotidcommentscommentid-options) - [$.jribbble.shots.comments.likes](#jribbbleshotsshotidcommentscommentidlikesoptions) - [$.jribbble.shots.likes](#jribbbleshotsshotidlikesoptions) - [$.jribbble.shots.projects](#jribbbleshotsshotidprojectsoptions) - [$.jribbble.shots.rebounds](#jribbbleshotsshotidreboundsoptions) #### Users - [$.jribbble.users](#jribbbleusersuserid) - [$.jribbble.users.shots](#jribbbleusersuseridshotsoptions) - [$.jribbble.users.buckets](#jribbbleusersuseridbucketsoptions) - [$.jribbble.users.projects](#jribbbleusersuseridprojectsoptions) - [$.jribbble.users.teams](#jribbbleusersuseridteamsoptions) - [$.jribbble.users.likes](#jribbbleusersuseridlikesoptions) - [$.jribbble.users.followers](#jribbbleusersuseridfollowersoptions) - [$.jribbble.users.following](#jribbbleusersuseridfollowingoptions) - [$.jribbble.users.isFollowing](#jribbbleusersuseridisfollowingtargetuserid) #### Teams - [$.jribbble.teams.members](#jribbbleteamsteamidmembersoptions) - [$.jribbble.teams.shots](#jribbbleteamsteamidshotsoptions) #### Buckets - [$.jribbble.buckets](#jribbblebucketsbucketid) - [$.jribbble.buckets.shots](#jribbblebucketsbucketidshotsoptions) #### Projects - [$.jribbble.projects](#jribbbleprojectsprojectid) - [$.jribbble.projects.shots](#jribbbleprojectsprojectidshotsoptions) ### 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](http://developer.dribbble.com/v1/shots/#list-shots) for list names. - options - *optional* `Object` Key:value pairs of options that will be included in the request as query parameters. See [API Docs](http://developer.dribbble.com/v1/shots/#list-shots) for a full list. **Example usage:** ```javascript // Get a single shot $.jribbble.shots(2055068).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/KpMmjZ?editors=101). ```javascript // 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](http://codepen.io/tylergaw/pen/RPRVew/?editors=101). #### `$.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:** ```javascript // Get all attachments for a shot $.jribbble.shots(2066347).attachments().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/XbKgJy/?editors=101). ```javascript // 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](http://codepen.io/tylergaw/pen/ZGOyGM/?editors=101). #### `$.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:** ```javascript // 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](http://codepen.io/tylergaw/pen/ZGOayV/?editors=101). #### `$.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:** ```javascript // Get all comments for a shot $.jribbble.shots(2067969).comments().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/LVZrBq/?editors=101). ```javascript // 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](http://codepen.io/tylergaw/pen/yNJERz/?editors=101). #### `$.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:** ```javascript // 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](http://codepen.io/tylergaw/pen/LVZwQL/?editors=101). #### `$.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:** ```javascript // Get the likes for a shot. $.jribbble.shots(2058881).likes().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/jPVVZb/?editors=101). #### `$.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:** ```javascript // Get the projects for a shot. $.jribbble.shots(2077496).projects().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/qdqqYo/?editors=101). #### `$.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:** ```javascript // Get the rebounds for a shot. $.jribbble.shots(2046896).rebounds().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/XbNpqx/?editors=101). ### Users #### `$.jribbble.users(userId)` **Description:** Gets a single user **Parameters:** - userId - *required* `String or Int` The username or id for the user. **Example usage:** ```javascript $.jribbble.users('tylergaw').then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/bdBrYK/?editors=101). #### `$.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:** ```javascript $.jribbble.users('tylergaw').shots().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/NqpzvE/?editors=101). #### `$.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:** ```javascript $.jribbble.users('markbult').buckets().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/bdBrXz/?editors=101). #### `$.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:** ```javascript $.jribbble.users('creativemints').projects().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/xGqzjR/?editors=101). #### `$.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:** ```javascript $.jribbble.users('veerlepieters').teams().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/RPpJJQ/?editors=101). #### `$.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:** ```javascript $.jribbble.users('op45').likes().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/WvpyKm/?editors=101). #### `$.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:** ```javascript $.jribbble.users('tylergaw').followers().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/ZGBJdY/?editors=101). #### `$.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:** ```javascript $.jribbble.users('tylergaw').following().then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/jPVLdR/?editors=101). #### `$.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:** ```javascript $.jribbble.users('tylergaw').isFollowing('jimniels').then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/bdBrjx/?editors=101). ### 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:** ```javascript $.jribbble.teams('eight2eight').members(options).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/bdBrgv/?editors=101). #### `$.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:** ```javascript $.jribbble.teams('eight2eight').shots(options).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/bdBrWM/?editors=101). ### Buckets #### `$.jribbble.buckets(bucketId)` **Description:** Gets a single bucket **Parameters:** - bucketId - *required* `String or Int` **Example usage:** ```javascript $.jribbble.buckets(114550).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/mJORor/?editors=101). #### `$.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:** ```javascript // Get the shots for a bucket. $.jribbble.buckets(114550).shots(options).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/ZGBLPq/?editors=101). ### Projects #### `$.jribbble.projects(projectId)` **Description:** Gets a single project **Parameters:** - projectId - *required* `String or Int` **Example usage:** ```javascript $.jribbble.projects(267945).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/MwbJPB/?editors=101). #### `$.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:** ```javascript // Get the shots for a project. $.jribbble.projects(267945).shots(options).then(function(res) { // Do cool stuff with response }); ``` Live example [on Codepen.io](http://codepen.io/tylergaw/pen/mJORaE/?editors=101). --------------------------------------------------------------------------- ## Contributing Jribbble is open source. [Issues](https://github.com/tylergaw/jribbble/issues) and [pull requests](https://github.com/tylergaw/jribbble/pulls) 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](https://travis-ci.org/tylergaw/jribbble) 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