Skip to content

Latest commit

 

History

History
229 lines (173 loc) · 9.78 KB

README.md

File metadata and controls

229 lines (173 loc) · 9.78 KB
Raw

instafeed.js

Build Status

Instafeed is a dead-simple way to add Instagram photos to your website. No jQuery required, just good 'ol plain javascript.

Examples:

Buy me a coffee:

If you enjoy using Instafeed.js and want to say thanks, you can leave me a small tip using Gittip.

Installation

Setting up Instafeed is pretty straight-forward. Just download the script and include it in your HTML:

<script type="text/javascript" src="path/to/instafeed.min.js"></script>

Basic Usage

Here's how easy it is to get all images tagged with #awesome:

<script type="text/javascript">
    var feed = new Instafeed({
        get: 'tagged',
        tagName: 'awesome',
        clientId: 'YOUR_CLIENT_ID'
    });
    feed.run();
</script>

Instafeed with automatically look for a <div id="instafeed"></div> and fill it with linked thumbnails. Of course, you can easily change this behavior using standard options. Also check out the advanced options for some advanced ways of customizing Instafeed.js.

Requirements

The only thing you'll need to get going is a valid client id from Instagram's API. You can easily register for one on Instagram's website.

If you want to get images from a specific user, you will need a valid oAuth token. Using an oAuth token has security risks. See the section on "Security Considerations"

Standard Options

  • clientId (string) - Your API client id from Instagram. Required.
  • accessToken (string) - A valid oAuth token. Required to use get: 'user'.
  • target (string) - The ID of a DOM element you want to add the images to.
  • template (string) - Custom HTML template to use for images. See templating.
  • get (string) - Customize what Instafeed fetches. Available options are:
    • popular (default) - Images from the popular page
    • tagged - Images with a specific tag. Use tagName to specify the tag.
    • location - Images from a location. Use locationId to specify the location
    • user - Images from a user. Use userId to specify the user.
  • tagName (string) - Name of the tag to get. Use with get: 'tagged'.
  • locationId (number) - Unique id of a location to get. Use with get: 'location'.
  • userId (number) - Unique id of a user to get. Use with get: 'user'.
  • sortBy (string) - Sort the images in a set order. Available options are:
    • none (default) - As they come from Instagram.
    • most-recent - Newest to oldest.
    • least-recent - Oldest to newest.
    • most-liked - Highest # of likes to lowest.
    • least-liked - Lowest # likes to highest.
    • most-commented - Highest # of comments to lowest.
    • least-commented - Lowest # of comments to highest.
    • random - Random order.
  • links (bool) - Wrap the images with a link to the photo on Instagram.
  • limit (number) - Maximum number of Images to add. Max of 60.
  • useHttp (bool) - By default, image urls are protocol-relative. Set to true to use the standard http://.
  • resolution (string) - Size of the images to get. Available options are:
    • thumbnail (default) - 150x150
    • low_resolution - 306x306
    • standard_resolution - 612x612

Advanced Options

  • before (function) - A callback function called before fetching images from Instagram.
  • after (function) - A callback function called when images have been added to the page.
  • success (function) - A callback function called when Instagram returns valid data. (argument -> json object)
  • error (function) - A callback function called when there is an error fetching images. (argument -> string message)
  • mock (bool) - Set to true fetch data without inserting images into DOM. Use with success callback.
  • filter (function) - A function used to exclude images from your results. The function will be given the image data as an argument, and expects the function to return a boolean. See the example below for more information.

Example Filter (get username + tagged):

var feed = new Instafeed({
  get: 'user',
  userId: USER_ID,
  filter: function(image) {
    return image.tags.indexOf('TAG_NAME') >= 0;
  }
});
feed.run();

To see a full list of properties that image has, see issue #21.

Templating

The easiest way to control the way Instafeed.js looks on your website is to use the template option. You can write your own HTML markup and it will be used for every image that Instafeed.js fetches.

Here's a quick example:

<script type="text/javascript">
    var feed = new Instafeed({
        get: 'popular',
        tagName: 'awesome',
        clientId: 'YOUR_CLIENT_ID',
        template: '<a class="animation" href="{{link}}"><img src="{{image}}" /></a>'
    });
    feed.run();
</script>

Notice the {{link}} and {{image}}? The templating option provides several tags for you to use to control where variables are inserted into your HTML markup. Available keywors are:

  • {{link}} - URL to view the image on Instagram's website.
  • {{image}} - URL of the image source. The size is inherited from the resolution option.
  • {{id}} - Unique ID of the image. Useful if you want to use iPhone hooks to open the images directly in the Instagram app.
  • {{caption}} - Image's caption text. Defaults to empty string if there isn't one.
  • {{likes}} - Number of likes the image has.
  • {{comments}} - Number of comments the image has.
  • {{location}} - Name of the location associated with the image. Defaults to empty string if there isn't one.
  • {{model}} - Full JSON object of the image. If you want to get a property of the image that isn't listed above you access it using dot-notation. (ex: {{model.filter}} would get the filter used.)

Pagination

As of v1.3, Instafeed.js has a .next() method you can call to load more images from Instagram. Under the hood, this uses the pagination data from the API. Additionall, there is a helper .hasNext() method that you can use to check if pagination data is available.

Together these options can be used to create a "Load More" button:

// grab out load more button
var loadButton = document.getElementById('load-more'),

    feed = new Instafeed({
      // every time we load more, run this function
      after: function() {
        // disable button if no more results to load
        if (!this.hasNext()) {
          loadButton.setAttribute('disabled', 'disabled');
        }
      },
    });

// bind the load more button
loadButton.addEventListener('click', function() {
  feed.next();
});

// run our feed!
feed.run();

Security Considerations

With Instafeed, it is possible to get images from a specific user id:

<script type="text/javascript">
    var userFeed = new Instafeed({
        get: 'user',
        userId: YOUR_USER_ID,
        accessToken: 'YOUR_ACCESS_TOKEN'
    });
    userFeed.run();
</script>

This setup requires an accessToken. Normally, using tokens like this in javascript would be very bad. However, since Instagram provides scoping in their API, you can limit the risk of user impersonation.

Just always make sure your token is set to basic authorization, which only allows 'GET' requests. If you aren't sure what scope your token has, check under your account page.

Contributing to Development

This isn't a large project by any means, but I'm definitely welcome to any pull requests and contributions. Everything is written and tested in CoffeeScript.

You can get your copy up and running for development quickly by cloning the repo and running npm:

$ npm install

This will install all the necessary test tools for testing. There is also a Makefile in the repo to make your tests quick and easy:

  • make test will run all the tests using Mocha + Chai + CoffeeLint
  • make min will create the minified version
  • make will run both the previous steps and compile everything

Change Log

1.3.0

  • Image URLs are now protocol-relative by default. Use the new useHttp option to disable.
  • Added the ability to filter out images using the filter option.
  • Added pagination support using .next() and .hasNext() methods.
  • Removed the default limit of 15 images. The option is still supported, but by default no limit is sent to the API.

1.2.1

  • Fixed IE8 error "Object doesn't support this action".

1.2.0

  • Added the ability to sort images! Use the sortBy option.
  • Added {{likes}}, {{comments}}, {{id}}, {{caption}}, {{location}}, and {{model}}, tags to the template option.

1.1.0

  • Added option to use a custom html template with the template option.
  • Added ability to fetch several feeds at the same time (create separate instances).
  • Added before, success, after, and error callback options.
  • Added mock option to only fetch data. Use with success option for custom DOM manipulation.

1.0.0

  • Initial release