This toolkit provides 3 components to display Instagram media (images and video) - by id, by tag, or by user.

Setup

Once you have installed the plugin you will need to set it up to interact with Instagram. Go to the Settings section of October and find the Instagram settings in the left-hand navigation pane.

Client ID

This is a required setting. To get a Client ID see the Instagram developer site.

Access Token

This setting is required if you intend to obtain media from a private user. This will need to be the access token for that user.

Access tokens for Instagram are obtained using the OAuth 2.0 protocol, but that authorization flow makes more sense for generic apps that are built to manipulate any user's Instagram account. Since that is not the way this toolkit is built to work, if you want to display media for a private user, you will want to login to that user's account and then follow these instructions to obtain an access code.

Keep in mind that an access token should be treated like a password - having it gives complete control over the associated Instagram account (though the toolkit does not provide such complete control).

The components

showSingle

Displays a single Instagram post.

• URL: Required. An Instagram URL, like http://instagram.com/p/sWtig6oVYM.
• Cache: Specifies how long, in minutes, the media data (the tags, comments, urls, likes, etc) will be stored locally before having to be retrieved from Instagram again. Unless you are interested in frequently changing data (comments or tags for example), you can keep this value quite high, thus saving frequent (slow) communication with the Instagram API.

NOTE: If you want to retrieve a single post of a private user, you must specify that users access token in the settings.

tagFeed

Shows recent posts for a specified tag.

• Tag: Required. Hopefully self-explanatory.
• Limit: The number of posts to return. It can be anywhere from 1 to 20.
• Cache: Specifies how long, in minutes, the media data (the tags, comments, urls, likes, etc) will be stored locally before having to be retrieved from Instagram again. Keep this short if using a popular tag so that you get fresh posts. If the tag you choose is fairly static, then a longer cache can be used.

NOTE: If you supply an access token for a private user account in settings, that users posts may appear in the tag feed if they are recent enough, and contain the specified tag.

userFeed

Shows recent posts for a specified user.

• User Name: Required. An Instagram username, like 'natgeo'.
• Limit: The number of posts to return. It can be anywhere from 1 to 20.
• Cache: Specifies how long, in minutes, the media data (the tags, comments, urls, likes, etc) will be stored locally before having to be retrieved from Instagram again. Keep this short if the user frequently posts.

NOTE: If you want to retrieve posts of a private user, you must specify that users access token in the settings.

Simple rendering

Rendering the components can be accomplished by using their component alias.

{% component 'tagFeed' %}
{% component 'userFeed' %}
{% component 'showSingle' %}

This will result in the media being output as an unadorned image or video. To layout the media to conform to your site, we suggest using the custom rendering method below.

Custom rendering

If you would like more control over the rendering of media you can directly retrieve the content of any of the components. The tagFeed and userFeed components provide a media property (a collection of Media objects), and the showSingle component provides a single property (a single Media object).

As an example, consider a tagFeed component that has been added to a page. Instead of using the component tag in the page you could write:

{% for m in tagFeed.media %}
    <div class="instagram-image">
        <img src="{{ m.getLowResImage().url }}">
    </div>
{% endfor %}

Or for a showSingle component:

<img src="{{ showSingle.single.getLowResImage().url }}" class="instagram-image">

Working with Media objects

As noted above, the components return Media objects. These objects are part of the PHP Instagram API package. You can have a look at the package documentation and source code for a more direct understanding of its structures, but the basic properties and functions available for a Media object are as follows:

Use

These methods allow us to create rather rich Instagram galleries. Extending on the example in the "Custom rendering" section, we could do this:

<div class="instagram-object">
  <h3>{{ showSingle.single.getCaption().text }}</h3>
  <div class="likes">{{ showSingle.single.getLikesCount() }} likes</div>
  {% if showSingle.single.getType() == 'image' %}
    <img src="{{ showSingle.single.getStandardResImage().url }}" >
  {% elseif showSingle.single.getType() == 'video' %}
    <video width="{{ showSingle.single.getStandardResVideo().width }}" height="{{ showSingle.single.getStandardResVideo().width }}" controls>
      <source src="{{ showSingle.single.getStandardResVideo().url }}" 
      type="video/mp4"/>
    </video>
  {% endif %}
</div>

Avoiding more API calls

Generally, getting the url of an Instagram object, and maybe the caption associated with it, will be enough to create a rich gallery. However, if you are using some of the other methods of the Media object, you may need to keep in mind a potential drawback: more API calls.

Some of the Media methods - getLikes() as an example - will call the Instagram API again, since the initial call will not have returned the full dataset. To avoid these excessive calls these functions can often be passed a boolean false (obviously restricting you to the limited dataset). Or you can use the getData() function to ensure that you are only using the raw data that has come from the initial Instagram API call. For a full understanding of Media, User, Tag, Location and Comment objects, we suggest you look at the PHP Instagram API package source. I wish there were some docs somewhere too...