#157

Product support

Get help in the plugin support forum.

Categories

  • Social
  • Utility

The Instagram Toolkit is a simple way of obtaining media from Instagram, either as a single element, or a collection of images and videos from a specific user, or a specific tag. Just add one of three built-in components to your page, set the properties and away you go!

3 components for Instagram use.

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:

Method Returns
getData() All the data encapsulated in a plain stdClass object with simple properties.
getId() String ID of media
getType() String 'video' or 'image'
getThumbnail() Array of image details, with elements 'url', 'width' and 'height'
getStandardResVideo() Array of video details, with elements 'url', 'width' and 'height'
getLowResVideo() Array of video details, with elements 'url', 'width' and 'height'
getStandardResImage() Array of image details, with elements 'url', 'width' and 'height'
getLowResImage() Array of image details, with elements 'url', 'width' and 'height'
getStandardRes() Alias for getStandardResImage()
getLowRes() Alias for getLowResImage()
getCaption() Comment object, with properties 'id', 'created_time', 'text', 'from' (stdClass Object with user details)
getCreatedTime() Numeric timestamp
getUser() User object, with properties 'id', 'username', 'website', 'profile_picture', 'full_name', 'bio'
getComments() Collection of Comment objects (see getCaption)
getFilter() String filter name
getTags() Tag Collection. Tags have properties 'id', 'name'
getLink() String url
getLikesCount() Integer count
getLikes() Collection of User objects (see getUser)
hasLocation() Boolean
hasNamedLocation() Boolean
getLocation() Location object, with properties 'id', 'name', 'lat', 'lng'
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...

  • Found the plugin useful on 7 Jun, 2017

    plugins/metaphorceps/instagram/vendor/php-instagram-api/php-instagram-api/Instagram/Instagram.php:151

    getMediaShortcode should be getMediaByShortcode

  • Found the plugin not useful on 2 May, 2017

    This plugin does not work. The developer is not responding to support questions.

  • Found the plugin useful on 7 Jan, 2016

    Great plugin

  • Found the plugin useful on 1 Dec, 2015

    Great plugin! Thanks for the effort in making this!

  • Found the plugin useful on 9 Jan, 2015

    I use this plugin for http://www.instalife.cz/ page and it works perfectly :-)

  • Found the plugin useful on 1 Nov, 2014

    Great plugin that allows some awesome customization!

1.0.0

First version

Sep 01, 2014