DIAMOND SOCIAL FEEDDocumentation for version 2.2

Summary Installation Basic usage Initializing Images Videos Story albums Modal caption Options Easing functions
Diamond Social Feed jQuery

DIAMOND SOCIAL FEED

jQuery documentation for version 2.2

SUMMARY

Diamond Social Feed is a canvas based jQuery plugin for creating advanced media gallery with social networks support. It can be used as a regular media gallery, social stream or can be combined. This API provides a number of useful options that allow you to control the settings of the plugin.

As a media gallery the plugin supports both images and videos, and can display it in a modal window in three different layouts: image, video and story album. Modal window caption could also be added. More details can be found below.

As a social stream, the plugin supports following: Instagram, Facebook, Youtube and Vimeo. The plugin uses only official APIs with all their features and limitations. Social networks can be displayed in any desired order.

Most of the gallery's parts and elements are built to use HTML5 canvas technology, which means smooth animations, a clean look, cross-browser support, and cool geometric layouts.

The plugin was designed keeping true smart lazy loading in mind. Data will only be loaded when it is needed. This saves internet traffic for your users and makes Google Page Speed ​​happy.

Diamond Social Feed is fully responsive, touch friendly, contains a modal window for displaying media details and has over 160 customization options.

INSTALLATION

1. Download plugin, then upload "diamond.min.css" file from "diamond" folder to your server.

2. Include diamond.min.css file in your page (usually in the head section). Make sure the include paths point to the locations where the files have been uploaded.

<!-- Main Diamond Social Feed CSS stylesheet file --> <link rel="stylesheet" href="path-to-file/diamond.min.css" type="text/css">

3. Include diamond.min.js file from "diamond" folder in your page right below jQuery. Note that this plugin requires jQuery 3.0+ so you should first include it. If you already have jQuery 3.0+ on your page, you shouldn't include it again. Note that it is always a good idea to use latest version of jQuery whenever possible.

<!-- Plugin requires jQuery 3.0+ --> <!-- If you already have jQuery on your page, you shouldn't include it again --> <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script> <!-- Main Diamond Social Feed JS script file --> <script src="path-to-file/diamond.min.js"></script>

BASIC USAGE

Create a new <div> tag with unique id and add it to the body section of your page.

<!-- This is your gallery --> <div id="diamond-gallery"></div>

INITIALIZING

To init the plugin, include this script below in your page (usually at the bottom of the <body> tag, under jQuery and source script included previously).

<script> jQuery(document).ready(function($){ $("#diamond-gallery").diamondSocialFeed(); }); </script>

IMAGES

You can use Diamond Social Feed as a regular media carousel. To add an image, just add HTML markup to your gallery. Create a <div> element and specify the path to your image using the data-img-dsf attribute.

<!-- This is your gallery --> <div id="diamond-gallery"> <!-- Put your images here --> <div data-img-dsf="path-to-image/1.jpg"></div> <div data-img-dsf="path-to-image/2.jpg"></div> <div data-img-dsf="path-to-image/3.jpg"></div> </div>

VIDEOS

In order to add a video, create a <div> element and use the data-video-dsf attribute to pass data about the video in JSON format. The following data is required:
- video`s thumbnail image source;
- video source itself;
- video width (in px);
- video height (in px);
Video icon will also appear on the gallery carousel item.

<!-- This is your gallery --> <div id="diamond-gallery"> <!-- Your video with data in JSON format --> <div data-video-dsf='{ "thumb": "path-to-thumbnail-img/1.jpg", "video": { "src": "path-to-video/1.mp4", "width": "400", "height": "800" } }'> </div> <!-- Or the same but more compact --> <div data-video-dsf='{ "thumb": "path-to-thumbnail-img/1.jpg", "video": {"src": "path-to-video/1.mp4", "width": "400", "height": "800"} }'> </div> </div>

STORY ALBUMS

Story album allows you to add multiple photos and videos to the album. The contents of the album will appear in the modal window along with the story navigation buttons.

To add a story album, create a <div> element and use the data-story-dsf attribute. Now pass the following data in JSON format inside:
- story`s thumbnail image source;
- slide list: image source if it is image or video`s thumbnail, source, width and height if it is a video;
Story icon will also appear on the gallery carousel item.

<!-- This is your gallery --> <div id="diamond-gallery"> <!-- Your story album with JSON formatted data --> <div data-story-dsf='{ "thumb": "path-to-story-thumbnail-img/1.jpg", "slides": [ "path-to-image/1.jpg", { "thumb": "path-to-video-thumbnail-img/1.jpg", "video": {"src": "path-to-video/1.mp4", "width": "1920", "height": "1080"} } ] }'> </div> <!-- Example story with two images and two videos --> <div data-story-dsf='{ "thumb": "path-to-story-thumbnail-img/1.jpg", "slides": [ "path-to-image/1.jpg", { "thumb": "path-to-video-thumbnail-img/1.jpg", "video": {"src": "path-to-video/1.mp4", "width": "1920", "height": "1080"} }, "path-to-image/2.jpg", { "thumb": "path-to-video-thumbnail-img/2.jpg", "video": {"src": "path-to-video/2.mp4", "width": "640", "height": "640"} } ] }'> </div> </div>

OPTIONS

Use options to configure the plugin. Options should be passed to the initialization code and separated by comma. As an example, set some options as shown in the code below.

<script> jQuery(document).ready(function($){ $("#diamond-gallery").diamondSocialFeed({ // options go here crslStyle: 'diamond', crslColumns: 5, itemSize: 96, // and so on... }); }); </script>

In the tables below you can find a complete list of existing options, their default settings and descriptions. The list is separated into the logical blocks to become more informative.

PLUGIN GLOBAL

Option Default Value Description
initWhenInVieweport true Allows to initialize the plugin only when it appears in the user`s viewport. Useful for increasing page load speed.
Set it to false for immediate initialization
fontFamily null

Allows to set a specific font to the gallery carousel and modal window. By default, the plugin applies the font settings from the parent tag <div> to which it is attached.

To apply custom font it must be installed on the page. Option must be passed as string: 'My-font-name'

transitionSpeed 200 Global transitions speed. Value is in ms
transitionTimingFunction 'linear'

The type of the easing function for transition events.

The easing functions specify the rate of change of a parameter over time. More information can be found in the easing functions section of the current documentation

allowHover true Allows hover events. Set it to false to disable hover
hoverSpeed 200 Global hover speed. Value is in ms
hoverTimingFunction 'linear'

The type of the easing function for hover events.

The easing functions specify the rate of change of a parameter over time. More information can be found in the easing functions section of the current documentation

touchThreshold 40 Minimum distance that user has to swipe to trigger carousel or modal window slide event. Value is in px
keyboardControl true Enables carousel and modal window navigation using the keyboard. Set to false to disable keyboard control
Option Default Value Description
crslPosition 'inline'

There are two possible values: 'inline' and 'outline'.

By default, the gallery will fit all the available width of the element to which the plugin is attached. In other words, you can adjust the width of the gallery by setting the CSS "width" property for the gallery tag ( in the examples above - <div id="diamond-gallery"> tag )

But in case you need a gallery to fit the width of the viewport and your layout cannot be outlined ( for example, the gallery is located within an article with a fixed width ) set the value to 'outline' and the gallery will fit all the available viewport width no matter what. In case some other elements on the page overlapping outline gallery, additional z-index adjustments will be required.

crslStyle 'diamond' Carousel grid style. There are four available values:
'diamond'
'tile'
'ellipse'
'hexagon'
crslColumns 5

The number of columns in the carousel.
Recommended range of values - from 2 to 12.

Note that the carousel is responsive, so this value could be changed dynamically using breakpoints option

crslAutoSlide 0

Time interval in ms for automatic carousel sliding.

If set to 0, auto sliding is disabled. Set to 1000 and the carousel will slide automatically every second, up to 5000 - every 5 seconds respectively.

The interval will be broken after the user interacts: tap, click or swipe

crslBgColor null Carousel background color.
Only HEX format is allowed ( for example: '#000000' )
Option Default Value Description
navTextColor '#e2e2e2'

Carousel navigation buttons text color. This color will also be applied to the navigation arrows.

Only HEX format is allowed

navDisableTextColor '#080808'

Disabled navigation button text color. This color will also be applied to the navigation arrows.

Only HEX format is allowed

navArrowHeight 2

This value sets the line height for navigation button arrows, in px.
Range of values - from 0 to 10.

If set to 0, the navigation arrows will be completely removed and the navigation texts will be centered

navArrowGradientPoint 30 This value sets the transparency point for navigation button arrows gradient in %. Range of values - from 0 to 100
navBgColor '#2f353a' Background color of the carousel navigation buttons.
Only HEX format is allowed
navGradientColor '#000000' Carousel navigation buttons gradient color.
Only HEX format is allowed
navGradientOpacity 95 The level of opacity of the carousel navigation buttons gradient layer. Value is in %. Range of values - from 0 to 100
Option Default Value Description
itemSize 96

Slide size, in % of the maximum available size.
Range of values - from 0 to 100.

This option allows to control margins between slides. The less the value, the larger margin will be.

This value will also be applied to the carousel navigation buttons and could be dynamically changed using breakpoints option

itemAspectRatio 1

Slide aspect ratio.

Value set to 1 means that the width and height of the slide will be equal. Value less than 1 means that the slide will be stretched vertically, more than 1 - horizontally. Minimum value is 0.1.

1
0.5
1.5

This value will also be applied to the carousel navigation buttons

itemBorderRadius 4

Slide border radius, in px.

This value will also be applied to the carousel navigation buttons and could be dynamically changed using breakpoints option

itemGradientColor '#000000' Slide gradient color. Only HEX format is allowed
itemGradientPoint 50

The point where the gradient should stop. Will be calculated as a percentage of the slide height.
Range of values - from 0 to 100.

If set to 50, the gradient layer will start at the bottom of the slide and stop in the middle. Set it to 100 and the gradient layer will cover all the slide height and will stop at the top of the slide

itemGradientOpacity 50 Opacity level of the slide gradient layer, in %.
Range of values - from 0 to 100
itemGrayscaleLevel 0

Grayscale level of the slide image, in %.
Range of values - from 0 to 100

A value of 0 leaves the image full color saturated. Set it to 100 and the image will be black and white

itemMediaIconColor '#e2e2e2'

Color of the media icon that appears on the video, carousel album or social media slides.

Only HEX format is allowed

itemMediaIconOpacity 50 Opacity level of the media icon, in %.
Range of values - from 0 to 100
itemPreloaderColor '#2f353a' Color of the preloader that appears before the slide is loaded. Only HEX format is allowed
itemHoverTextColor '#e2e2e2' Color of the slide hover text. Only HEX format is allowed
itemHoverTextOpacity 80 Opacity level of the slide hover text, in %.
Range of values - from 0 to 100
itemHoverFontSize 40

Font size of the slide hover text, in px

This value also could be dynamically changed using breakpoints option

itemHoverTextScale 10

Initial scale level of the hover text, in %.
Range of values - from -100 to 100.

If the value is less than 0, the text size will decrease, more than 0 - will increase.

If set to -100, then the text will be enlarged from half the original size to full size on hover. Set it to 100 and the text will be reduced from double the size to the original on hover

itemHoverImageScale 10

Initial scale level of the slide image, in %.
Range of values - from -100 to 100.

If the value is less than 0, the initial image size will be enlarged and reduced to the original size while hovering. If set to more than 0, image size will remain original and will be enlarged on hover

itemHoverGrayscaleLevel 100

Grayscale level for slide image while hovering, in %.
Range of values - from 0 to 100.

A value of 0 leaves the image full color saturated. Set it to 100 and the image will be black and white

itemHoverMediaIconOpacity 100 Opacity level of the media icon while hovering, in %.
Range of values - from 0 to 100
itemHoverOverlayColor '#000000' The color of the slide hover overlay layer.
Only HEX format is allowed
itemHoverOverlayOpacity 50 Opacity level of the slide hover overlay layer, in %.
Range of values - from 0 to 100
itemShadowColor '#000000' The color of the slide shadow layer.
Only HEX format is allowed
itemShadowOpacity 60 Opacity level of the slide shadow layer, in %.
Range of values - from 0 to 100
itemShadowSize 20

Size of the slide shadow, in px

This value also could be dynamically changed using breakpoints option

itemShadowOffsetX 0

Horizontal offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow on the right side of the slide, negative value puts the shadow on the left side of the slide

itemShadowOffsetY 20

Vertical offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow below the slide, negative value puts the shadow above the slide

Option Default Value Description
modalClass null This option will add an additional class to the modal window.
Must be passed as string: 'my-modal-window'
modalZindex 9000 css z-index for the modal window
modalBgColor '#000000' Color of the modal window background layer.
Only HEX format is allowed
modalBgOpacity 90 The level of opacity of the modal window background layer, in %. Range of values - from 0 to 100
modalContentScale 5

Modal window content block scale level, in %.
Range of values - from -100 to 100.

If the value is less than 0, the size of the modal window content block will be increased from the set value to the original size during the opening animation and vice versa if the value is greater than 0

modalContentMaxWidth 80

The maximum allowed modal window content block width is a percentage of the viewport width.
Range of values - from 65 to 90.

If value is set to 80, any modal window content ( image, video or story album including caption ) won`t be wider than 80% of viewport.

Note, that modal window navigation and close buttons also depend on this value. For example: if maximum allowed content width set to 80, that means content can cover up to 80% of viewport width and 20% is left for navigation buttons ( 10% for 'previous' and 10% for 'next' button ). Otherway, if maximum allowed content width set to 100, content can cover up to 100% of viewport width and there will be no space left to display the navigation buttons

modalContentMaxHeight 90

The maximum allowed modal window content block height is a percentage of the viewport height.
Range of values - from 0 to 100.

If value is set to 90, any modal window content ( image, video or story album ) won`t be higher than 90% of viewport

modalControlSize 35

The size of the navigation and close buttons of the modal window. Range of values - from 0 to 100

As noted above, this parameter depends on 'modalContentMaxWidth' option so calculation is based on available space. This value sets buttons size in % of maximum available space for them.

This value also could be dynamically changed using breakpoints option

modalControlColor '#e2e2e2' Color of the navigation and close buttons of the modal window. Only HEX format is allowed
modalControlLineWidth 2 This value sets the line thickness for navigation and close buttons of the modal window in px. Range of values - from 1 to 20
modalControlGradientPoint 90 This value sets the transparency point for gradient of navigation and close buttons of the modal window, in %.
Range of values - 0 to 100
modalControlNavAngle 70 This value sets the angle of the modal window navigation buttons in degrees. Range of values - 20 to 80
modalMobileViewPoint 768

The size of the viewport in px when the modal window should be switched to the mobile layout.

For the adaptation ability there are two layouts of a modal window: 'desktop' and 'mobile'. For example, if the value is set to 800, screens are larger than 800px will display a 'desktop' layout of the modal window and smaller than 800px - 'mobile' layout

modalCaptionBgColor '#ffffff' Background color of the modal window content caption.
Only HEX format is allowed
modalCaptionTextColor null

Text color of the modal window content caption. By default, text color settings of the <body> tag will be applied.

Only HEX format is allowed

modalCaptionWidth 360

Width of the modal window content caption, in px.

In the 'mobile' layout of the modal window the width of the caption is automatically adjusted according to the media content

modalCaptionMinHeight 360 Minimum height of the modal window content caption, in px.
Will be applied on 'desktop' modal window layout
modalCaptionMinWidth 360 Minimum width of the modal window content caption, in px.
Will be applied on 'mobile' modal window layout
modalShadowColor '#000000' Color of the modal window content block shadow.
Only HEX format is allowed
modalShadowOpacity 60 Opacity level of the modal window content block shadow, in %. Range of values - from 0 to 100
modalShadowSize 20

Size of the modal window content block shadow, in px

This value also could be dynamically changed using breakpoints option

modalShadowOffsetX 0

Horizontal offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow on the right side of the modal window content block, negative value puts the shadow on the left side of the modal window content block.

modalShadowOffsetY 20

Vertical offset of the shadow, in %.
Range of values - from -100 to 100

Positive value puts the shadow below the modal window content block, negative value puts the shadow above the modal window content block

BREAKPOINTS

Option Default Value Description
breakPoints breakPoints: { // when window width is <= 1024px 1024: { crslColumns: 4, navFontSize: 18, itemHoverFontSize: 30, itemShadowSize: 18 }, // when window width is <= 768px 768: { crslColumns: 3, navFontSize: 16, itemHoverFontSize: 20, itemShadowSize: 14 modalControlSize: 45 }, // when window width is <= 480px 480: { crslColumns: 2, navFontSize: 14, itemHoverFontSize: 16, itemShadowSize: 10 modalControlSize: 60 modalShadowSize: 10 } } This option allows to set different parameters for different responsive breakpoints (screen sizes). Following options can be changed: Feel free to change values or to add your own breakpoint. Let's say you need 5 columns in your gallery when window width will be less or equal to 800px. Add this code to the options: breakPoints: { 800: { crslColumns: 5 } }

SOCIAL NETWORKS

Diamond Social Feed supports following: Instagram, Facebook, Youtube and Vimeo. The plugin uses only official APIs with all their features and limitations.

Access. First of all, it is necessary to understand that every social network API requires an Access Token or Api Key to fetch data. That's why you have to provide your Access Tokens and Api Keys to display social media data in your gallery.

Display order. Images, video and story albums added as HTML markup (manually added data) will always be displayed first and then social media data. That can't be changed. But you can set the sequence in which your social media feeds will be shown - they will be displayed in the order in which they were set in options. In other words, if you want to show your Youtube videos first and then images from Instagram, you just have to set Youtube queries above Instagram queries.

Queries. You can make multiple queries from every listed social network. For example, you can display videos from Youtube channel and Youtube playlist at the same time. And of course, you can set the sequence in which queries will be shown by setting them in required order.

Setting. To fetch data from social network you have to set an Access Token or Api Key and query in the options. The initialization code should be like this:

<script> jQuery(document).ready(function($){ $("#diamond-gallery").diamondSocialFeed({ // options go here crslStyle: 'diamond', crslColumns: 5, // instagram settings instagramAccessToken: 'your-access-token', instagramMedia: true, // youtube settings youtubeApiKey: 'your-api-key', youtubeSearch: 'Fly Me to the Moon' // and so on... }); }); </script>

Modal caption for social networks in general has a unified structure but there are some differences in displaying modal caption depending on network source. For example, Instagram does not have a banner option in modal captions, and Facebook does not display a comment block due to API restrictions. In addition, the set of statistics counters (number of "likes", "dislikes", etc.) will be different.

INSTAGRAM

There are three types of Instagram profiles: Personal, Creator and Business and there are two official APIs exist to get data from them: Instagram Basic Display API for personal profiles and Instagram Graph API for creator and business profiles. Those APIs have different requirements, restrictions and abilities.
Diamond Social Feed supports both APIs and can display all types of Instagram accounts.

The table below shows what queries can be made for each profile type, what data will be displayed in the modal caption and what is required:

Profile Type Requests Modal caption data Requirements
Personal
  • User Name
  • Media Link
  • Title
  • Elapsed Time

Instagram Basic Display API will be used to request data.

Instagram User Access Token with the following permissions is required:
  • instagram_graph_user_profile
  • instagram_graph_user_media
Creator
Business
All Requests:
  • User Name
  • Media Link
  • Statistic Block
  • Title
  • Elapsed Time
User Media
in addition:
  • User Picture
  • Comments Block
Business Discovery
in addition:
  • User Picture

* in a Hashtag Search, the hashtag itself is displayed instead of the username

Instagram Graph API will be used to request data.

According to the Instagram Graph API documentation: Instagram Professional accounts are accessed indirectly through Facebook accounts and the Facebook account must be able to perform admin-equivalent Tasks on a Facebook Page that has been connected to the Instagram account.

So, first of all, you will need a Creator or Business Instagram account that has been connected to a Facebook page, and your Facebook user account must have an admin role on that page.

Next, to access the data of these account types, you will need to obtain a Facebook User Access Token with the following permissions:
  • pages_show_list
  • pages_read_engagement
  • instagram_basic
  • instagram_manage_insights
  • instagram_manage_comments
Finally, along with the Access Token, Instagram Id must be also provided in the plugin options

Instagram Options List. Note that you can make multiple queries on behalf of a Creator or Business account at the same time: profile media and hashtag media, etc. You can also set the sequence in which responses will be shown by setting requests in required order in the options.

Option Default Value Description
instagramAccessToken null Depending on your profile type:
Instagram User Access Token for Personal profile
Facebook User Access Token for Creator or Business profiles
instagramId null

Instagram User ID.

This option is required only for Creator or Business Instagram profile types to make API calls.

Instagram User ID could be found on business.facebook.com > More Tools > Business Settings > Accounts > Instagram Accounts.

instagramMedia false

This option allows to display your profile media objects: photos, videos and albums. Set it to true to display data.

Requirements for Personal type profile:
  • Instagram User Access Token
Requirements for Creator or Business profile types:
  • Facebook User Access Token
  • instagramId option must be set
instagramStories false

This option allows to query a list of story objects on your profile.

Limitations:
  • Avaiable for Creator and Business profile types only
  • Responses will not include Live Video stories
  • Stories are only available for 24 hours
  • New stories created when a user reshares a story will not be returned
Requirements:
  • Facebook User Access Token
  • instagramId option must be set
instagramTags false

This option allows to query media objects in which your profile has been tagged by another Instagram user.

Limitations:
  • Avaiable for Creator and Business profile types only
  • Private media objects will not be returned
Requirements:
  • Facebook User Access Token
  • instagramId option must be set
instagramHashtag null

This option allows to query public photos and videos that have been tagged with specific hashtag. Value should be passed as a string without the hash symbol, for example: 'starship'

Limitations:
  • Avaiable for Creator and Business profile types only
  • You can query a maximum of 30 unique hashtags within a 7 day period
  • Personally identifiable information will not be included in responses
  • Hashtags on Stories are not supported
  • Emojis in hashtag queries are not supported
Requirements:
  • Facebook User Access Token
  • instagramId option must be set
instagramHashtagOrder 'top'

This option allows to sort the media requested by the hashtag. There are two possible values:

'top' - returns the most popular media objects that have been tagged with the hashtag

'recent' - returns the most recently published media objects published with a specific hashtag

instagramUserName null

Business Discovery. This option allows to get media objects from other Instagram Business and Creator profiles. Value must be the username of the Business or Creator profile that you are attempting to get data about and must be passed as a string.

For example, if you're going to display data from Margot Robbie`s Instagram business account in your gallery, you need to set this option to 'margotrobbie'

Limitations:
  • Avaiable for Creator and Business profile types only
  • Data about age-gated Instagram Business profiles will not be returned
Requirements:
  • Facebook User Access Token
  • instagramId option must be set
instagramIncludeIGTV true

Whether to display Instagram IGTV objects of Professional accounts. Set value to false to hide IGTV

Limitations:
  • Avaiable for Creator and Business profile types only
  • IGTV is not available for instagramHashtag query
instagramShowCaption true Whether to display the caption in the modal window.
Set value to false to hide caption
instagramShowMediaLink true Whether to display a link to the media in the caption of the modal window. Set value to false to hide it
instagramShowStatistic true

Whether to display a block of media statistics in the caption of the modal window. Set value to false to hide the block.

The following statistics are available:
  • Comments count
  • Likes count
instagramShowTitle true Whether to display the media title in the caption of the modal window. Set value to false to hide it
instagramShowElapsedTime true Whether to display the elapsed time since the media was created in the caption of the modal window. Set value to false to hide it
instagramShowComments true Whether to display a comments block in the caption of the modal window. Set value to false to hide the block

Instagram Rate Limits. Depending on the API used to request Instagram data:

FACEBOOK

Diamond Social Feed uses Facebook's official Graph API to request media data. The plugin is able to display photos and videos from a Facebook User and a Facebook Page.

The table below shows what queries can be made for each endpoint, what data will be displayed in the modal caption and what is required:

Endpoint Requests Modal caption data Requirements
User
  • Banner Image
  • User Picture
  • User Name
  • Media Link
  • Statistic Block
  • Title
  • Elapsed Time
  • Description Block
Facebook User Access Token with the following permissions is required:
  • user_link
  • user_photos
  • user_videos
Page
  • Banner Image
  • User Picture
  • User Name
  • Media Link
  • Statistic Block
  • Title
  • Elapsed Time
  • Description Block
Facebook User Access Token with the following permissions is required:
  • pages_read_engagement
  • pages_read_user_content

Your Facebook User account must have an admin role on that Facebook Page.

Along with the Access Token Facebook Page Id must be also provided in the plugin options

Facebook Options List. Note that you can make multiple queries at the same time: user profile videos and page album photos, etc. You can also set the sequence in which responses will be shown by setting requests in required order in the options.

Option Default Value Description
facebookAccessToken null Facebook User Access Token with required permissions
facebookUserPhotos false This option allows to display photos uploaded to your User account.
Set it to true to display data
facebookUserVideos false This option allows to display videos uploaded to your User account.
Set it to true to display data
facebookUserAlbum null This option allows to display a specific album from your User account.
Value must be an album ID and passed as a string
facebookUserPhotosList null

This option allows to display a list of specific photos of your User account.

Value must be a comma-separated list of photo IDs and passed as a string

facebookUserVideosList null

This option allows to display a list of specific videos of your User account.

Value must be a comma-separated list of video IDs and passed as a string

facebookPageId null

Facebook Page ID you are going to request data from.

Facebook Page ID could be found on business.facebook.com > More Tools > Business Settings > Accounts > Pages.

facebookPagePhotos false

This option allows to display photos uploaded to your Facebook Page.
Set value to true to display data.

Requirements:
facebookPageVideos false

This option allows to display videos uploaded to your Facebook Page.
Set value to true to display data.

Requirements:
facebookPageAlbum null

This option allows to display a specific album from your Facebook Page.
Value must be an album ID and passed as a string.

Requirements:
facebookPagePhotosList null

This option allows to display a list of specific photos of your Facebook Page.

Value must be a comma-separated list of photo IDs and passed as a string.

Requirements:
facebookPageVideosList null

This option allows to display a list of specific videos of your Facebook Page.

Value must be a comma-separated list of video IDs and passed as a string.

Requirements:
facebookShowCaption true Whether to display the caption in the modal window.
Set value to false to hide caption
facebookShowBanner true

Whether to display a media banner in the caption of the modal window. Set value to false to hide it

Facebook Graph API doesn't allow to query UserCoverPhoto directly to display it as a banner image in the caption of the modal window. Instead, the cover photo of the profile`s 'Cover Photos' album will be used as a banner image

facebookShowMediaLink true Whether to display a link to the media in the caption of the modal window. Set value to false to hide it
facebookShowStatistic true

Whether to display a block of media statistics in the caption of the modal window. Set value to false to hide the block.

The following statistics are available:
  • Comments count
  • Likes count
facebookShowTitle true Whether to display the media title in the caption of the modal window. Set value to false to hide it
facebookShowElapsedTime true Whether to display the elapsed time since the media was created in the caption of the modal window. Set value to false to hide it
facebookShowDescription true Whether to display the media description in the caption of the modal window. Set value to false to hide it

Facebook Rate Limits. Learn more about Graph API Rate Limits.

YOUTUBE

Diamond Social Feed uses official YouTube Data API to request and display YouTube videos. The table below shows what queries can be made, what data will be displayed in the modal caption and what is required:

Requests Modal caption data Requires
  • User Picture
  • User Name
  • Media Link
  • Statistic Block
  • Title
  • Elapsed Time
  • Description Block
  • Comments Block
YouTube API key

YouTube Options List. Note that you can make multiple queries at the same time: Channel videos and Playlist videos, etc. You can also set the sequence in which responses will be displayed by setting requests in required order in the options.

Option Default Value Description
youtubeApiKey null Your YouTube API key
youtubeChannel null

This option allows to display videos from the YouTube Channel.

Value must be an Channel ID and passed as a string. For example: to display videos from the NASA channel, set value to 'UCLA_DiR1FfKNvjuUpBHmylQ'

youtubePlaylist null This option allows to display videos from the YouTube Playlist.
Value must be an Playlist ID and passed as a string
youtubeVideos null

This option allows to display a list of specific YouTube videos.

Value must be a comma-separated list of video IDs and passed as a string

youtubeKeyword null

This option allows to search and display YouTube videos by keyword. For example: 'Fly Me to the Moon'

The request can also use the NOT ( - ) and OR ( | ) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the value to 'boating|sailing'. Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the value to 'boating|sailing -fishing'

The following search filters can also be used with this option:
youtubeRelatedToVideoId null

This option allows to search and display a list of YouTube videos that are related to a specific video.

Value must be an YouTube video ID and passed as a string

The following search filters can also be used with this option:
youtubeLocation null

This option, in conjunction with the youtubeLocationRadius option, defines a circular geographic area to search and display videos that specify, in their metadata, a geographic location that falls within that area.

Value must be set as a comma-separated string inside square brackets that specifies latitude/longitude coordinates e.g. '[21.5922529,-158.1147114]'

  • The value of youtubeLocation option identifies the point at the center of the area
  • The value of youtubeLocationRadius option specifies the maximum distance that the location associated with a video can be from that point for the video to still be included in the search results
The following search filters can also be used with this option:
youtubeLocationRadius null

This option, in conjunction with the youtubeLocations option, defines a circular geographic area.

Value must be a string, consisting of a floating point number followed by a measurement unit. Valid measurement units are m, km, ft, and mi. For example, valid values include '1500m', '5km', '10000ft', and '0.75mi'

The maximum allowed value is 1000 kilometers

youtubeLocationQuery null

This option, in conjunction with the youtubeLocations and the youtubeLocationRadius options allows to filter videos by keyword within defined area.

Value must be passed as a string e.g. 'surfing'

youtubeFilterOrder null

This option specifies the method to order search results.

Can be applied to the following requests: Acceptable values are:
  • 'date' – Videos will be sorted in reverse chronological order based on the date they were created
  • 'rating' – Videos will be sorted from highest to lowest rating
  • 'title' – Videos will be sorted alphabetically by title
  • 'viewCount' – Videos will be sorted from highest to lowest number of views. For live broadcasts, videos will be sorted by number of concurrent viewers while the broadcasts are ongoing
youtubeFilterDuration null

This option filters video search results based on their duration.

Can be applied to the following requests: Acceptable values are:
  • 'long' – Only include videos longer than 20 minutes
  • 'medium' – Only include videos that are between 4 and 20 minutes long (inclusive)
  • 'short' – Only include videos that are less than 4 minutes long
youtubeFilterDefinition null

This option allows to restrict a search to only include either high definition (HD) or standard definition (SD) videos. HD videos are available for playback in at least 720p, though higher resolutions, like 1080p, might also be available.

Can be applied to the following requests: Acceptable values are:
  • 'high' – Only retrieve HD videos
  • 'standard' – Only retrieve videos in standard definition
youtubeFilterEventType null

This option restricts a search results to broadcast events.

Can be applied to the following requests: Acceptable values are:
  • 'completed' – Only include completed broadcasts
  • 'live' – Only include active broadcasts
  • 'upcoming' – Only include upcoming broadcasts
youtubeFilterSafeSearch null

This option indicates whether the search results should include restricted content as well as standard content.

Can be applied to the following requests: Acceptable values are:
  • 'moderate' – YouTube will filter some content from search results and, at the least, will filter content that is restricted in your locale. Based on their content, search results could be removed from search results or demoted in search results
  • 'strict' – YouTube will try to exclude all restricted content from the search result set. Based on their content, search results could be removed from search results or demoted in search results
youtubeFilterLanguage null

This option instructs the API to return search results that are most relevant to the specified language.

Value must be a ISO 639-1 two-letter language code passed as string e.g. 'en'

The results in other languages will still be returned if they are highly relevant to the search query term.

Can be applied to the following requests:
youtubeFilterRegion null

This option instructs the API to return search results for videos that can be viewed in the specified country.

Value must be a ISO 3166-1 alpha-2 country code passed as string e.g. 'US'

Can be applied to the following requests:
youtubeShowCaption true Whether to display the caption in the modal window.
Set value to false to hide caption
youtubeShowMediaLink true Whether to display a link to the video in the caption of the modal window. Set value to false to hide it
youtubeShowStatistic true

Whether to display a block of video statistics in the caption of the modal window. Set value to false to hide the block.

The following statistics are available:
  • Views count
  • Comments count
  • Likes count
  • Dislikes count
youtubeShowTitle true Whether to display the video title in the caption of the modal window. Set value to false to hide it
youtubeShowElapsedTime true Whether to display the elapsed time since the video was created in the caption of the modal window. Set value to false to hide it
youtubeShowDescription true Whether to display the video description in the caption of the modal window. Set value to false to hide it
youtubeShowComments true Whether to display a comments block in the caption of the modal window. Set value to false to hide it

Youtube Rate Limits. Learn more about Youtube API Quota usage.

VIMEO

Diamond Social Feed uses official Vimeo API to request and display Vimeo videos. The table below shows what queries can be made, what data will be displayed in the modal caption and what is required:

Requests Modal caption data Requires
  • Banner Image
  • User Picture
  • User Name
  • Media Link
  • Statistic Block
  • Title
  • Elapsed Time
  • Description Block
  • Comments Block
Vimeo Access Token

Vimeo Options List. Note that you can make multiple queries at the same time: Group videos and videos by keyword, etc. You can also set the sequence in which responses will be displayed by setting requests in required order in the options.

Option Default Value Description
vimeoAccessToken null Your Vimeo Access Token
vimeoChannel null

This option allows to display videos from the Vimeo Channel.
Value must be a Channel ID and passed as a string

The following search filters can also be used with this option:
vimeoUser null

This option allows to display videos from the Vimeo User.
Value must be a User ID and passed as a string

The following search filters can also be used with this option:
vimeoGroup null

This option allows to display videos from the Vimeo Group.
Value must be a Group ID and passed as a string

The following search filters can also be used with this option:
vimeoVideos null

This option allows to display a list of specific Vimeo videos.

Value must be a comma-separated list of Vimeo video URLs and passed as a string

vimeoSearch null

This option allows to search and display Vimeo videos by keyword.
For example: 'Apple pie'

The following search filters can also be used with this option:
vimeoFilterSort null

This option specifies the method to order Vimeo videos.

Can be applied to the following requests: Acceptable values are:
  • 'alphabetical' - Videos will be sorted alphabetically
  • 'date' - Videos will be sorted by creation date
  • 'duration' - Videos will be sorted by duration
  • 'likes' - Videos will be sorted by number of likes
  • 'plays' - Videos will be sorted by number of plays
vimeoFilterQuery null

This option allows to filter Vimeo videos by keyword

Can be applied to the following requests: Value must be passed as a string e.g. 'beautiful'
vimeoShowCaption true Whether to display the caption in the modal window.
Set value to false to hide caption
vimeoShowBanner true

Whether to display a banner in the caption of the modal window. Set value to false to hide it.

If the returned video data contains a set of categories, the banner image will be the image that represents the first category in that set. Otherwise, the video thumbnail will be set as a banner image

vimeoShowMediaLink true Whether to display a link to the video in the caption of the modal window. Set value to false to hide it
vimeoShowStatistic true

Whether to display a block of video statistics in the caption of the modal window. Set value to false to hide the block.

The following statistics are available:
  • Comments count
  • Credits count
  • Likes count
vimeoShowTitle true Whether to display the video title in the caption of the modal window. Set value to false to hide it
vimeoShowElapsedTime true Whether to display the elapsed time since the video was created in the caption of the modal window. Set value to false to hide it
vimeoShowDescription true Whether to display the video description in the caption of the modal window. Set value to false to hide it
vimeoShowComments true Whether to display a comments block in the caption of the modal window. Set value to false to hide it

Vimeo Rate Limits. Learn more about Vimeo API Rate Limits.

DICTIONARY

The text of the plugin interface can be changed. For instance, this is useful for translation.

Option Default Value Description
navPrevText 'Prev' The text of the carousel "Previous" navigation button
navNextText 'Next' The text of the carousel "Next" navigation button
itemHoverText 'View' Carousel slide hover text
imgLoadErrorText '404 ERROR' This text will appear on the carousel slide if the slide image has not been loaded
instagramMediaLinkText 'Instagram' Text that is displayed in source links to Instagram media. It is located in the top right corner of modal caption
facebookMediaLinkText 'Facebook' Text that is displayed in source links to Facebook media. It is located in the top right corner of modal caption
youtubeMediaLinkText 'Youtube' Text that is displayed in source links to Youtube media. It is located in the top right corner of modal caption
vimeoMediaLinkText 'Vimeo' Text that is displayed in source links to Vimeo media. It is located in the top right corner of modal caption
elapsedTimeFewSec 'few seconds ago' Text of time elapsed from the moment media was created. If only a few seconds have passed. Text is displayed in modal caption
elapsedTimeLessThanMin 'less than one min' Text of time elapsed from the moment media was created. If less than one minute has passed. Text is displayed in modal caption
elapsedTimeMinAgo 'minutes ago' Text of time elapsed from the moment media was created. If some minutes have passed. Text is displayed in modal caption
elapsedTimeHourAgo 'a hour ago' Text of time elapsed from the moment media was created. If one hour has passed. Text is displayed in modal caption
elapsedTimeHrsAgo 'hours ago' Text of time elapsed from the moment media was created. If some hours have passed. Text is displayed in modal caption
elapsedTimeDayAgo 'a day ago' Text of time elapsed from the moment media was created. If one day has passed. Text is displayed in modal caption
elapsedTimeDaysAgo 'days ago' Text of time elapsed from the moment media was created. If some days have passed. Text is displayed in modal caption
elapsedTimeMonthAgo 'a month ago' Text of time elapsed from the moment media was created. If one month has passed. Text is displayed in modal caption
elapsedTimeMnthsAgo 'months ago' Text of time elapsed from the moment media was created. If some months have passed. Text is displayed in modal caption
elapsedTimeYearAgo 'a year ago' Text of time elapsed from the moment media was created. If one year has passed. Text is displayed in modal caption
elapsedTimeYrsAgo 'years ago' Text of time elapsed from the moment media was created. If some years have passed. Text is displayed in modal caption
loadMoreComments 'Load more comments' "Load more comments" button appears in the bottom of the comments block of modal window caption
statCmntsText 'comments: ' The text is displayed as a tooltip with a numeric value and appears when the cursor is hovered over the comments icon in the modal window caption
statLksText 'likes: ' The text is displayed as a tooltip with a numeric value and appears when the cursor is hovered over the likes icon in the modal window caption
statDislksText 'dislikes: ' The text is displayed as a tooltip with a numeric value and appears when the cursor is hovered over the dislikes icon in the modal window caption
statViewsText 'views: ' The text is displayed as a tooltip with a numeric value and appears when the cursor is hovered over the views icon in the modal window caption
statCreditsText 'credits: ' The text is displayed as a tooltip with a numeric value and appears when the cursor is hovered over the credits icon in the modal window caption

EASING FUNCTIONS

The easing functions denotes a mathematical function that describes how fast one-dimensional values change during animations. This lets you vary the animation's speed over the course of its duration. They can be used to smooth down the start and end of the animation.

For a better understanding, let's look at three different functions: linear, easeInSine and easeInOutSine to compare and describe them. In the graphs, the X axis represents the time and the Y axis - the output value:

linear

In the 'linear' function, the animation moves from the beginning to the end at a constant rate which means that the value will increase by an equal amount. In other words, if you need to move an object 10 pixels in 10 seconds and you use a linear function, that object will move 1 pixel every second.

easeInSine

In the 'easeInSine' function, the animation starts slowly, and then progressively speeds up until the end.

easeInOutSine

In the 'easeInOutSine' function, the animation starts slowly, accelerates sharply, and then slows gradually towards the end.

Here is a complete list of easing functions (except basic one - linear) that you can use in the Diamond Social Feed. Note that you can also use a Demo page to choose the right easing function.

easeInSine
easeOutSine
easeInOutSine
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeInExpo
easeOutExpo
easeInOutExpo
easeInCirc
easeOutCirc
easeInOutCirc
easeInBack
easeOutBack
easeInOutBack
easeInElastic
easeOutElastic
easeInOutElastic
easeInBounce
easeOutBounce
easeInOutBounce

NOTES

  • You will need to obtain your own Api Keys and Access Tokens to fetch social media data.
  • The social network APIs are constantly changing, so keep in mind that some social media display data issues may appear from time to time.
  • Each social networking API anticipate to have some kind of Rate Limits. Since the plugin is built to use official APIs, it potentially could affect your project.
  • The plugin wasn`t designed to be located inside a modal or popup window so it could affect some issues with initialization