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.
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.
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.
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.
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.)
Instragram docs page for this function:
https://www.instagram.com/developer/endpoints/users/#get_users
user_id: the Craft user id (not an Instagram user id)
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
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
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
user_id: This is the ID number of an Craft user. (It is not the Instagram user id number.)
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
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
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
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
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
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