logo

DOCUMENTATION

For Diamond Social Feed version 1.0

Summary

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

Installation

1. Download plugin, then upload "diamond" folder to your server.

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

<!-- Main Diamond Social Feed CSS stylesheet file --> <link rel="stylesheet" href="diamond/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 1.8+ so you should first include it. If you already have jQuery 1.8+ on your page, you shouldn't include it second time.

<!-- Plugin requires jQuery 1.8+ --> <!-- If you already have jQuery on your page, you shouldn't include it second time --> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script> <!-- Main Diamond Social Feed JS script file --> <script src="diamond/diamond.min.js"></script>

Basic Usage

Create a new <div> element with unique id and add it to 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).

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

Images

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

<!-- This is your gallery --> <div id="diamond-gallery"> <!-- Put your images here --> <div data-img="path-to-my-image/1.jpg"></div> <div data-img="path-to-my-image/2.jpg"></div> <div data-img="path-to-my-image/3.jpg"></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").diamond({ // options go here gridStyle: 'diamond', gridColumns: 5, youtubeQuery: 'Sydney Opera House', // and so on... }); }); </script>
Global settings
Variable Default Value Description
carouselWidth 100
Carousel width in % of parent container
gridStyle 'diamond'
There are two possible grid styles. Basic style is 'diamond' but if you prefer more classic design, you can always change it to 'tile'. The difference in styles is shown in the images below
'diamond'
'tile'
gridColumns 4
The number of columns in the carousel. Recommended range of values - from 2 to 6. Note that the carousel is responsive so you can change this value dynamically using 'breakpoints' option
slideDistance 'min'
Could be 'min' or 'max'. If this option set to 'min', every 'next' or 'previous' button click will slide the carousel at a distance of one column. Set it to 'max' and slide distance will be equal to gridColumns value
'min' 'max'
gridGlobalSpeed 250
Global speed of carousel animations and transitions in ms
gridScrollSpeed 300
Duration of carousel slide transition in ms
gridScrollTransitionStyle 'cubic-bezier(.5,.2,.5,.8)'
CSS easing function for carousel slide transition
fontFamily null
Plugin will set font-family value from page where it is located by default. You can set custom font to it by passing font-family name to this option. For example: 'Arial' or 'Roboto'. Note that the custom font must be installed on the page
Slide styling
Variable Default Value Description
itemSize 90
Slide size in % of the maximum possible size
itemBorderRadius 4
Slide border radius in px
itemColor '#000000'
Slide shadow, gradient and background color. Only HEX format is allowed
itemGradientOpacity 0.25
Opacity of slide gradient mask. Possible values - from 0 to 1
itemShadowSize 4
Slide shadow size in css 'vw'
itemShadowOpacity 0.25
Transparency of slide shadow. Possible values - from 0 to 1
itemHover true
Set to false if you want to disable slide hover effect
itemHoverOpacity 0.1
Level of slides background image transparency on hover. Range of values - from 0 to 1
itemHoverSpeed 250
Slide hover effect duration in ms
itemText 'View'
Slide hover text
itemTextColor '#ffffff'
Slide hover text and social network icon color. Only HEX format is allowed
itemFontSize 14
Slide hover text font size in % of slide width
itemHoverTextAnimation 'zoomIn'
Slide hover text transition effect. Could be: 'zoomIn', 'zoomOut', 'fromRight', 'fromLeft', 'fromTop', 'fromBottom'
itemAspectRatio [3,2]
Slide aspect ratio. Only for tile style grid. First value equals to width, second - to height
[3,2]
[16,9]
Navigation
Variable Default Value Description
controlPrevText 'Prev'
'Previous' navigation button text
controlNextText 'Next'
'Next' navigation button text
controlTextColor '#ffffff'
Carousel navigation buttons text color
controlDisableTextColor '#101010'
Disabled navigation button text color
controlFontSize 9
Carousel navigation buttons font size in % of button width
controlBgColor '#2f353a'
Background color of carousel navigation buttons. Only HEX format is allowed
controlGradientColor '#000000'
Carousel navigation buttons gradient color. Only HEX format is allowed
controlGradientOpacity 0.95
Opacity of carousel navigation buttons gradient mask. Possible values - from 0 to 1
controlArrowsSize 30
Sets the transparency point for navigation buttons arrows. Recommended max value - 30

Next

30

Next

0
Note that this value also sets the transparency point for lightbox control buttons arrows
keyboardControl true
Enables carousel and lightbox navigation using keyboard. Set to false to disable keyboard control
touchThreshold 10
Minimum distance that user has to swipe to fire carousel slide event. In % of slide width
Variable Default Value Description
lightBoxSpeed 250
Lightbox animations and transitions duration in ms
lightBoxTransitionStyle 'cubic-bezier(.5,.2,.5,.8)'
CSS easing function for lightbox transitions
lightBoxOverlayColor '#000000'
Lightbox overlay background color. Only HEX format is allowed
lightBoxOverlayOpacity 0.95
Lightbox overlay background transparency
lightBoxImageAspectRatio [0.8, 0.9]
Lightbox image maximum allowed size. First value equals to image width and second - to image height. It is calculated from viewport size, where 0 = 0% and 1 = 100%. For example: if value set to [0.8, 0.9], any image in lightbox won`t be wider than 80% and won`t be higher than 90% of viewport
80% of viewport
90% of viewport
Note, that lightbox navigation and close buttons also depend on this value. For example: if maximum allowed image width set to 0.8, that means image 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 image width set to 1, image can cover up to 100% of viewport width and there will be no space left to display the navigation buttons. Therefore recommended maximum value is [0.9, 0.9]
lightBoxImageFadeScale 0.9
Lightbox image, navigation buttons and close button scale size. This parameter will be animated to 1 ( actual elements size ) when you open lightbox and will be returned to initial size when you close it. If set to 0.9 - elements will scale up from 90% to 100% when you open lightbox and will scale down from 100% to 90% when you close it. If set to 1.2 - elements will scale down from 120% to 100% when you open lightbox and will scale up from 100% to 120% when you close it
lightBoxControlColor '#c2c2c2'
Lightbox navigation buttons, counter and close button color. Only HEX format is allowed
lightBoxControlSize 45
Lightbox navigation buttons size. As noted above, this parameter depends on 'lightBoxImageAspectRatio' option so calculation is based on available space. This value sets buttons size in % of maximum available space for them
lightBoxCloseSize 30
Lightbox close button size. This parameter also depends on 'lightBoxImageAspectRatio' option so calculation is based on available space. This value sets close button size in % of maximum available space for it
lightBoxControlWidth 3
Lightbox navigation buttons and close button arrows width in px. You can make them thinner or thicker
lightBoxCounter true
Lightbox counter. It shows current slide number and total number of slides. Set to false to disable counter
lightBoxCounterText ' of '
Lightbox counter text. It is located between slide number and total number of slides
lightboxCounterPlus true
If facebook option is set and single API call is not enough to show all your facebook data, you will see '+' sign at the end of lightbox counter until all facebook data is loaded. It happens because facebook does not provide the total amount of media with their APIs, and as a result, at the beginning of loading, we do not know how many photos and videos exist. Set this option to false to hide '+' sign
lightBoxTransitionDistance 10
Minimum distance that user has to swipe to fire lightbox slide event. In % of viewport width
lightBoxSocialLinkText 'View on'
Text that is displayed in links to social networks. It is located in top right angle of image or video caption. For example: 'View on Facebook' or 'View on Youtube'
Breakpoints
Variable Default Value Description
breakPoints object
Allows to set different parameters for different responsive breakpoints (screen sizes). Only 'gridColumns', 'lightBoxControlSize', 'lightBoxCloseSize', 'lightBoxControlWidth' parameters can be changed. Default breakpoints settings are:
// Default breakpoints settings breakPoints: { // when window width is <= 1024px 1024: { gridColumns: 4, lightBoxControlSize: 45, lightBoxCloseSize: 30, lightBoxControlWidth: 4 }, // when window width is <= 768px 768: { gridColumns: 3, lightBoxControlSize: 50, lightBoxCloseSize: 60, lightBoxControlWidth: 3 }, // when window width is <= 480px 480: { gridColumns: 2, lightBoxControlSize: 70, lightBoxCloseSize: 70, lightBoxControlWidth: 2 } }
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 options:
breakPoints: { 800: { gridColumns: 5 } }
Note that if you need a breakpoint higher than 1024px, you have to set all possible parameters. For exemple: we need 'lightBoxControlSize' with value 30 when window width will be less or equal to 1440px :
breakPoints: { 1440: { gridColumns: 4, lightBoxControlSize: 30, lightBoxCloseSize: 30, lightBoxControlWidth: 4 } }
Social Networks

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

One more thing - order. Images added as HTML markup (manually added images) will always be displayed first and then social networks data. That can't be changed. But you can set the sequence in which your social networks will be shown - they will be displayed in order in which they were set in options. In other words, if you want to show your Youtube videos first and then images from Facebook, you just have to set youtubeApiKey option above facebookAccessToken option.

Variable Default Value Description
facebookAccessToken null
To fetch data from Facebook you have to provide your Facebook Access Token. Set it in options in format:
$("#diamond-gallery").diamond({ facebookAccessToken: 'YourAccessToken' });
You can get photos and videos from your Facebook profile. Learn how to get Facebook Access Token in article Get Facebook Access Token
facebookPhotos true
Set it to false to disable loading photos from facebook:
$("#diamond-gallery").diamond({ facebookAccessToken: 'YourAccessToken', facebookPhotos: false });
hideFacebookCoverPic false
Set it to true to disable display of User Cover Picture:
$("#diamond-gallery").diamond({ facebookAccessToken: 'YourAccessToken', hideFacebookCoverPic: true });
hideFacebookProfilePic false
Set it to true to disable display of User Profile Picture:
$("#diamond-gallery").diamond({ facebookAccessToken: 'YourAccessToken', hideFacebookProfilePic: true });
facebookVideos true
Set it to false to disable loading videos from facebook:
$("#diamond-gallery").diamond({ facebookAccessToken: 'YourAccessToken', facebookVideos: false });
youtubeApiKey null
To fetch videos from YouTube you have to provide your YouTube Api Key. Set it in options in format:
$("#diamond-gallery").diamond({ youtubeApiKey: 'YourApiKey' });
You can query all public videos by keywords, videos from YouTube channels or playlists. Learn how to get YouTube Api Key in article Get Youtube Api Key
youtubeQuery null
Allows to query YouTube videos by keywords. Set your YouTube Api Key and your query in options. For example, we want to show all YouTube videos with keywords 'Where is the love?' :
$("#diamond-gallery").diamond({ youtubeApiKey: 'YourApiKey', youtubeQuery: 'Where is the love?' });
youtubeChannelId null
Allows to query videos from YouTube channel. Set your YouTube Api Key and Channel Id in options:
$("#diamond-gallery").diamond({ youtubeApiKey: 'YourApiKey', youtubeChannelId: 'ChannelId' });
Learn how to get YouTube Channel Id in article Get Youtube Channel ID
youtubeUserId null
Allows to query videos from YouTube user. Set your YouTube Api Key and User Id in options:
$("#diamond-gallery").diamond({ youtubeApiKey: 'YourApiKey', youtubeUserId: 'UserId' });
Learn how to get YouTube User Id in article Get Youtube User ID
youtubeListId null
Allows to query videos from YouTube playlist. Set your YouTube Api Key and ListId in options:
$("#diamond-gallery").diamond({ youtubeApiKey: 'YourApiKey', youtubeListId: 'ListId' });
Learn how to get YouTube PlayList Id in article Get Youtube Playlist ID
vimeoAccessToken null
To fetch videos from Vimeo you have to provide your Vimeo Access Token. Set it in options in format:
$("#diamond-gallery").diamond({ vimeoAccessToken: 'YourAccessToken' });
You can query all public videos by keywords, videos from Vimeo channels or all public videos from a specific user. Learn how to get Vimeo Access Token in article Get Vimeo Access Token
vimeoQuery null
Allows to query Vimeo videos by keywords. Set your Vimeo Access Token and your query in options. For example, we want to show all Vimeo videos with keywords 'Sydney Opera House' :
$("#diamond-gallery").diamond({ vimeoAccessToken: 'YourAccessToken', vimeoQuery: 'Sydney Opera House' });
vimeoChannelId null
Allows to query videos from Vimeo channel. Set your Vimeo Access Token and Channel Id in options:
$("#diamond-gallery").diamond({ vimeoAccessToken: 'YourAccessToken', vimeoChannelId: 'ChannelId' });
Learn how to get Vimeo Channel Id in article Get Vimeo Channel ID
vimeoUserId null
Allows to query videos from Vimeo specific user. Set your Vimeo Access Token and UserId in options:
$("#diamond-gallery").diamond({ vimeoAccessToken: 'YourAccessToken', vimeoUserId: 'UserId' });
Learn how to get Vimeo User Id in article Get Vimeo User ID
socialIcon true
Social networks icons. Set to false to hide icons
socialIconSize 5
Size of social networks icons in % of slide width
socialIconBottom 8
Distance between social network icon and slide bottom in % of slide height. In case if you use 'tile' style grid, distance from right side of slide will be calculated automatically
socialIconOpacity 0.6
Transparency level of social network icon where value 1 means no transparency and value 0 means transparent
socialControlColor '#ffffff'
Color of play video button. Only HEX format is allowed
socialControlOpacity 0.9
Transparency level of play video button. Range of values - from 0 to 1
playButtonSize 60
Size of play video button in % of video width
elapsedTimeFewSec 'FEW SECONDS AGO'
Text of time elapsed from the moment media was created. If only few seconds have passed
elapsedTimeLessThanMin 'LESS THAN ONE MIN'
Text of time elapsed from the moment media was created. If less than one minute has passed
elapsedTimeMinAgo 'MINUTES AGO'
Text of time elapsed from the moment media was created. If some minutes have passed
elapsedTimeHrsAgo 'HOURS AGO'
Text of time elapsed from the moment media was created. If some hours have passed
elapsedTimeDaysAgo 'DAYS AGO'
Text of time elapsed from the moment media was created. If some days have passed
elapsedTimeMnthAgo 'MONTHS AGO'
Text of time elapsed from the moment media was created. If some months have passed
elapsedTimeYrsAgo 'YEARS AGO'
Text of time elapsed from the moment media was created. If some years have passed

Public methods

Use this code structure if you need extra control over plugin:

// to use some method you have to apply it to some event. // for example: we need carousel to slide next on element with id 'next-slides' click. // Set this code after plugin initialization code $('#next-slides').on('click', function(){ $('#diamond-gallery').diamond('slide_next'); });

Following methods are available:

Method Description
'slide_prev'
Carousel slide previous
'slide_next'
Carousel slide next
'destroy'
Removes all events and clears all plugin data

Public properties

Use this code structure to get some important properties if you need it:

// set this code after plugin initialization code // to find out current index value var CurrentIndex = $('#diamond-gallery').diamond('current_index'); // display value in console console.log(CurrentIndex);

Following properties are available:

Propertie Description
'slider_width'
Carousel width in px
'slider_height'
Carousel height in px, including paddings
'total_slides'
Total number of carousel slides
'current_index'
Index of current carousel position. To understand this value:
- On plugin initialization index equals to 0 ;
- Each click on "Next" button increases index by 1 ;
- Each click on "Prev" button decreases index by 1 ;
- Swipe and drag events will also increase or decrease index (depends of direction)
'max_index'
Maximum possible index of carousel position