Documentation for Pic Puller for Craft

How to install Pic Puller for Craft

Copy the “picpuller” directory that sits alongside this file to your Craft site in the plugins directory. The path to that direction should be “craft/plugins/”.

Log into your control panel of Craft and visit the Settings page. From here, select “Plugins”. You should see “Pic Puller” listed among your plugins. You will need to click the “Install” button to the right of the line. Once installed, Pic Puller’s status should be “Enabled” automatically.

Once PPfC is installed, you will see it added to the global navigation in your control panel. Select “Pic Puller for Craft” from the top-level navigation.

Setting up your own Instagram application

To authorize a Craft site to pull in Instagram media, a user must allow this access. After installing Pic Puller, the site will ask for authorization.

Once authorization has been granted, Pic Puller will display the authorized user's credentials.


Using Pic Puller with multiple users

Other users and Pic Puller for Craft

You are not limited to one user with Pic Puller. If you have purchased the "Craft Client" or "Craft Pro" package, i.e. the paid version of Craft, additional users can also authorize their Instagram accounts. Pic Puller works without a the paid Craft CMS version but is limited to the one user allowed by that version of the Craft software.

A multiuser site can have each user display their own personal media on the site. When using the Pic Puller Image Browser the user stream search will be from each authorized user's Instagram stream.

Any "Admin" level user can view the list of authorized Pic Puller users along with their Instagram oAuth key for the Pic Puller 2 application. Basically, you need to trust other Admins in your Craft site.

Users that have not been granted "Admin" rights within Craft can still access the Pic Puller plugin page as long as you have granted them access under the "Users" tab. Access can be granted on a one-by-one basis under the "Users" tab, or on a broader scale if you set up User Groups and provide the group access to Pic Puller.

These non-admin users will have the ability to authorize and de-authorize Pic Puller with an Instagram account. Non-admin users will not be able to see the list of authorized users across the entire Craft site.

Optional behavior for multiple users

As described above, the default behavior of Pic Puller for Craft is for each Craft user to authenticate their Craft account with their Instagram account.

You can override this default behavior and have a single oAuth authorization be shared amongst all users of the Craft site. The most likely scenario for this feature is of a company site that has many site editors, but only a single Instagram account across the organization. Choosing to use a single Instagram authorization requires that the site developer choose a single user as the master Instagram account holder on the site. This user must be an Admin. The selection of the master Instagram user is made from the Pic Puller settings panel.

Only the selected account holder will see the "Pic Puller for Craft" menu item in the global navigation. This is the menu that allows a user to create and manage the Instagram application and authorization.

Tip: If your Instagram account holder in your organization is not someone who would typically have an admin level account to the site, one suggestion is to create an admin level account to be used solely for authorization purposes. You can have the Instagram account holder log into this account once to have them authorize Pic Puller to access the corporate Instagram account. Under everyday circumstances you could have them use their regular "editor" account to contribute to the site.

Instagram browser fieldtype

The Pic Puller Image Browser field type lets an authorized user browse their Instagram media stream and select media for use in a Craft entry. When setting up a field select "Pic Puller Image Browser" from the Field Type dropdown.

When setting up a field select "Pic Puller Image Browser" from the Field Type dropdown.

The field type searches Instagram to retrieve a media ID for an image or video uploaded through Instagram. A small video icon in the upper lefthand corner designates that the piece of media is a video rather than an image.

The media ID is stored in the Craft database. The media file is not stored within your site as dictated by the Instagram API agreement.

The media ID is used in conjunction with the media by ID function in your templates to show media on your site. (See the Media by ID section of the documentation.)


User information

Get basic information about a user.

See the code example for this function in the code section of this site.

Instragram docs page for this function:

https://www.instagram.com/developer/endpoints/users/#get_users

Required parameters:

user_id: the Craft user id (not an Instagram user id)

Optional parameters:

use_stale_cache: BOOLEAN, either TRUE or FALSE (defaults to TRUE if undefined), to have Pic Puller use previously cached data returned in the event of an error in retrieving new data

Tags returned in a successful Craft loop:

status: a BOOLEAN of TRUE (1) is returned when Instagram media data is returned, even if it is cached data

username: the Instagram username

id: the Instagram user id

bio: biography information provided by the Instagram user

profile_picture: URL to the profile image of the user

website: the website URL provided by the user on Instagram

full_name: the full name provided by the user on Instagram

cacheddata: a BOOLEAN of TRUE (1) is returned when request is using cached data. 

counts_media: the number of images in this user’s Instagram feed in total

counts_followed_by: the number of users who follow this user on Instagram

counts_follows: the number of users this user follows on Instagram

error_type: a string of “NoError” to indicate a successful call to the Instagram API

resulting in valid data OR a string of “NoCodeReturned” indicating there was no data returned from Instagram

error_message: a string describing the error

Tags returned in an unsuccessful Craft loop:

status: a BOOLEAN of FALSE (0) is returned when no data is returned from Instagram or there is no cache data to return

error_type: a single code word indicating the type of error (NoInstagramApp, MissingReqParameter, UnauthorizedUser issued by Pic Puller. Other codes are passed through from Instagram.)

error_message: a string describing the error

Recent media

Get the most recent media published by a user.

See the code example for this function in the code section of this site.

This is the function most people use. It's the photos from the authorized user. 

Instragram docs page for this function: https://www.instagram.com/developer/endpoints/users/#get_users_media_recent

Required parameters:

user_id: This is the ID number of an Craft user. (It is not the Instagram user id number.)

Optional parameters:

limit: an integer for how many images to request from Instagram. Instagram may return fewer under some circumstances. Maximum of 32 allowed by Instagram.

use_stale_cache: BOOLEAN, either TRUE or FALSE (defaults to TRUE if undefined), to have Pic Puller use previously cached data returned in the event of an error in retrieving new data

max_id: an integer used to determine pagination of results. (See next_max_id in the ‘Tags returned’ below section for more information.)

Tags returned in a successful Craft loop:

status: a BOOLEAN of TRUE (1) is returned when Instagram media data is returned, even if it is cached data

type: returns a string “image” or “video”

media_id: the Instagram unique media ID for the image or video

created_time: time stamp of image creation time, Unix timestamp formatted

link: URL of the images homepage on Instagram

cacheddata: a BOOLEAN of TRUE (1) is returned when request is using cached data. 

caption: The caption provided by the author. Note, it may be left untitled which will return an empty string.

caption_only: the caption provided by the author minus any content starting with the first hashtag. For example, if the caption were "Digging into Craft CMS. #craftcms #code #fun", the caption_only function would return "Digging into Craft CMS."

comment_count: the number of comments a piece of media has received

likes: the number of likes a piece of media has received

tags: an array of the tags associated with the media

thumbnail: URL to image

thumbnail_width: width of image in pixels

thumbnail_height: height of image in pixels

low_resolution: URL to image

low_resolution_width: width of image in pixels

low_resolution_height: height of image in pixels

standard_resolution: URL to image

standard_resolution_width: width of image in pixels

standard_resolution_height: height of image in pixels

video_low_bandwidth: URL to video

video_low_bandwidth_width: width of video in pixels

video_low_bandwidth_height: height of video in pixels

video_low_resolution: URL to video

video_low_resolution_width: width of video in pixels

video_low_resolution_height: height of video in pixels

video_standard_resolution: URL to video

video_standard_resolution_width: width of video in pixels

video_standard_resolution_height: height of video in pixels

latitude: latitude data, if available

longitude: longitude data, if available

next_max_id: an integer, provided by Instagram, used to return the next set in the same series of images. Pass this value into the max_id parameter of the loop to get the next page of results.

error_type: a string of “NoError” to indicate a successful call to the Instagram API resulting in valid data OR a string of “NoCodeReturned” indicating there was no data returned from Instagram

error_message: a string describing the error

Tags returned in an unsuccessful Craft loop:

status: a BOOLEAN of FALSE (0) is returned when no data is returned from Instagram or there is no cache data to return

error_type: a single code word indicating the type of error (NoInstagramApp, MissingReqParameter, UnauthorizedUser issued by Pic Puller. Other codes are passed through from Instagram.)

error_message: a string describing the error

Media by ID

Get information about a single media object.

See the code example for this function in the code section of this site.

This function will most likely be used in conjunction with the Pic Puller Image Browser field type.

Instragram docs page for this function: http://instagram.com/developer/endpoints/media/#get_media

Required parameters:

user_id: This is the ID number of an Craft user. (It is not the Instagram user id number.)

media_id: this is the ID number that Instagram has assigned to an image or video

Optional parameters:

use_stale_cache: BOOLEAN, either TRUE or FALSE (defaults to TRUE if undefined), to have Pic Puller use previously cached data returned in the event of an error in retrieving new data

Tags returned in a successful Craft loop:

status: a BOOLEAN of TRUE (1) is returned when Instagram media data is returned, even if it is cached data

created_time: time stamp of image creation time, Unix timestamp formatted

link: URL of the images homepage on Instagram

cacheddata: a BOOLEAN of TRUE (1) is returned when request is using cached data.

caption: The caption provided by the author. Note, it may be left untitled which will return an empty string.

caption_only: the caption provided by the author minus any content starting with the first hashtag. For example, if the caption were "Digging into Craft CMS. #craftcms #code #fun", the caption_only function would return "Digging into Craft CMS."

tags: an array of the tags associated with the media

thumbnail: URL to image

thumbnail_width: width of image in pixels

thumbnail_height: height of image in pixels

low_resolution: URL to image

low_resolution_width: width of image in pixels

low_resolution_height: height of image in pixels

standard_resolution: URL to image

standard_resolution_width: width of image in pixels

standard_resolution_height: height of image in pixels

video_low_bandwidth: URL to video

video_low_bandwidth_width: width of video in pixels

video_low_bandwidth_height: height of video in pixels

video_low_resolution: URL to video

video_low_resolution_width: width of video in pixels

video_low_resolution_height: height of video in pixels

video_standard_resolution: URL to video

video_standard_resolution_width: width of video in pixels

video_standard_resolution_height: height of video in pixels

latitude: latitude data, if available

longitude: longitude data, if available

username: the Instagram username of the user whose account the image is from

user_id: the Instagram user id of the user whose account the image is from

full_name: the full name provided by the user whose account the image is from

profile_picture: URL to the profile image of the user

website: the website information whose account the image is from, if available

likes: number of likes for piece of media

error_type: a string of “NoError” to indicate a successful call to the Instagram API resulting in valid data OR a string of “NoCodeReturned” indicating there was no data returned from Instagram

error_message: a string describing the error

Tags returned in an unsuccessful Craft loop:

status: a BOOLEAN of FALSE (0) is returned when no data is returned from Instagram or there is no cache data to return

error_type: a single code word indicating the type of error (NoInstagramApp, MissingReqParameter, UnauthorizedUser issued by Pic Puller. Other codes are passed through from Instagram.)

error_message: a string describing the error