jQuery Social Stream Plugin Documentation

Twitter API

Starting with version 1.7 of the plugin the Twitter API now requires authentication.

To create your own Twitter API credentials

1. Browse to https://dev.twitter.com/ & login with your Twitter username
2. Browse to https://dev.twitter.com/apps/new

1. Complete name, description & website fields
2. Check the "Yes I agree" box for the Developer Rules of the Road
3. Enter the captcha & click "Create Your Twitter Application"

1. Click "Create My Access Token"
2. A success message will be displayed at the top of the page
3. Click the "Details" tab to refresh the page and display your access token

1. Open file twitter.php in your text editor
2. From your twitter application page copy the Consumer Key, Consumer Secret, Access Token and Access Token Secret values and enter into the twitter API details at the top of the twitter.php file, save the file and upload to your server.

Example

// SET YOUR TWITTER API DETAILS HERE
$consumer_key = "cUfx93n2NBU3J8VCZ1pQ"; 
$consumer_secret = "FvKP8uzrVhGAJ2ncuofsSTUsLV50H2KdW9CkNrhAENo";
$oauth_access_token = "261263099-mF9o2SrPe5vno5IcwzGE36a0L4MiGf86Ou6a0CJy"; 
$oauth_access_token_secret = "eqgxmDB7hsBoph18758dRmkzzb0E8emyZfIm8bD9pWg"; 

The plugin should now be able to access your Twitter feed.

Note that the above values are for demonstration only and will NOT work with your plugin.

Facebook API

Starting with version 1.5.8 of the plugin facebook feeds now require authentication.

To create your own Facebook App

1. Browse to https://developers.facebook.com/ & login - if you have not previously regsitered as a developer you will need to do this first before you can create your own facebook app
2. From the top menu go to "My Apps" and click "Add New App"

1. Click on the "Website" icon

1. Enter a name for your app - e.g Social Stream
2. Click "Create a New Facebook App ID"

1. Select a category for your app
2. Click the "Create App ID" button

1. On the following page you should see the box shown above - enter your website address
2. Click "Next"
3. Then go to the top of the page and click the "skip quick start" link

1. Make a note of your APP ID
2. Click the "show" button on the App Secret field. You may need to enter your password again to confirm this action
3. Make a note of your App Secret

Adding your APP ID, Secret & Access Token To Your Site

1. Open file facebook.php in your text editor and find the following code at the top of the page:



// SET YOUR FACEBOOK API DETAILS HERE
$app_id 	= 'INSERT APP ID HERE';
$app_secret = 'INSERT APP SECRET HERE';
			

2. Enter your APP ID & Secret into the facebook API details, save the file and upload to your server - e.g:

// SET YOUR FACEBOOK API DETAILS HERE
$app_id 	= '876112410078524';
$app_secret = 'd26b9883d63c8aeb753063aad93ce61d';

The plugin should now be able to access your Facebook feed.

Note that the above values are for demonstration only and will NOT work with your plugin.

Facebook Feed Not Working?

Make sure that you have set the facebook "url" option to point to the actual location of your facebook.php file. The default setting is:

url: 'facebook.php'

The google +1 feed requires an API key. Fortunately creating your own google API key is fairly quick and easy:

• Go to https://code.google.com/apis/console#access
• Login to your google account
• Click "Create Project"
• In the left-hand side menu click "APIs & auth" then "APIs"
• Find the "Google + API" listing and set to "on"

• In the left-hand side menu click "Credentials"
• Click "Create New Key"

• In the pop-up window select "Server key"

• Leave the "Accept requests from these server IP addresses" box blank
• Click "Create"
• Copy your API key and paste into the social stream settings

Youtube feeds now require a google API key:

• Go to https://code.google.com/apis/console#access
• Login to your google account
• Click "Create Project"
• In the left-hand side menu click "APIs & auth" then "APIs"
• Click the "Youtube Data API" listing

• Click the "Enable API" button at the top of the page
• Then click the "Credentials" option in the left hand menu

• Under the "Public API access" title click the "Create New Key" button

• In the pop-up window select "Server Key"



• Leave the "Accept requests from these server IP addresses" box blank
• Click "Create"
• Copy your API key and paste into the social stream settings

In order to use the Instagram feed you must first create your own "Client ID"

• Go to http://instagr.am/developer/.
• Click "Register Your Application"

• On the Developer signup page complete the form
• Read and accept the terms & conditions and then click "sign up"

• If the signup page is submitted successfully and has been accepted click the "manage clients" tab in the top-right of the header.
• Click the button - "Register A New Client.

• Complete the "Register new OAuth Client" form - e.g:
  Application name: social stream
  Description: create a social stream from multiple networks
  Website: enter your website URL - e.g. http://www.designchemical.com
  Valid Redirect URIs: set this field to http://localhost (*).
  Contact email: enter a valid email address
• Check on the "Secuity" tab that the "Disable implicit OAuth" box is unchecked.
• Enter the CAPTCHA and Click the "Register" button

• Copy your CLIENT ID and paste into the "clientId" option for Instagram

How to get your access token

• Paste the following url into your web browser.
  
  https://instagram.com/oauth/authorize/?client_id=XXXXXXXXXX&scope=basic+public_content&redirect_uri=http://localhost&response_type=token
  
  Swap the "XXXXXXXXXX" with your Client ID that you have just created.
• Hit enter.
• Instagram will ask you whether you want to grant the client access to your account. Click Authorize. Once your client has been granted access to your account, Instagram will redirect your browser to your localhost. Your newly generated access token will be appended in the address bar of your browser to the url after localhost/#access_token=.
• Copy the token code - e.g 186786085.f59def8.1d34b28a52e04d36ba1dc52ca98215dc
• Add the access token to your Instagram options using the "accessToken" option - you should now have your "accessToken", "redirectUrl" & "clientId" options completed - e.g:
  
  

  instagram: {
  				accessToken: 'YOUR ACCESS TOKEN',
  				clientId: 'YOUR CLIENT ID'
  			}

In order to use the Dribbble feed you must first create your own "Access Token"

• Go to http://developer.dribbble.com/.
• Click "Register An Application"

• Complete the "Register Application" form - e.g:
  Name: social stream
  Description: create a social stream from multiple networks
  Website URL: enter your website URL - e.g. http://www.designchemical.com
  Callback URL: enter the URL of a page where the social stream is installed
• Check the "I accept the Dribbble API Terms & Guidelines" box
• Click the "Register application" button
• If the application has been submitted successfully you will see at notification at the top of the screen.
• The "Client Access Token" will now be displayed at the bottom of the page. Copy/paste this token into your Dribbble "accessToken" option - e.g:
  
  

  dribbble: {
  				id: 'frogandcode',
  				accessToken: 'YOUR ACCESS TOKEN'
  			}

Google +1 API Key

The google +1 feed requires an API key in order to work. The API key provided in the plugin examples is for test purposes only.

Make sure you change the API key for your own - google limit the number of API calls per day for each API key. If you use the test value this may result in your google +1 feed not working correctly.

For information on how to create your own API key see the instructions.

Instagram Feeds

1. User Feed

The user feed will show the latest posts from a specific user ID. To create a user feed use "!" followed by the user ID - e.g.

id: '!123456'

The plugin includes 3 different style sheets, which can be used based on whether you are using the rotating feed or the dark/light skin.

Rotating List - Dark Skin

To use the dark skin include the dcsns_dark.css file in the head of your page:

<link rel="stylesheet" type="text/css" href="css/dcsns_dark.css" media="all" />

Rotating List - Light Skin

To use the light skin include the dcsns_light.css file in the head of your page:

<link rel="stylesheet" type="text/css" href="css/dcsns_light.css" media="all" />

Social Network Wall

For the social network wall include the dcsns_wall.css file in the head of your page:

<link rel="stylesheet" type="text/css" href="css/dcsns_wall.css" media="all" />

The plugin contains 2 styles of layout for the network wall - classic & modern. The modern layout also comes in 2 colours - light & dark

Social Network Wall - Classic Layout

The "classic" layout is the default option for the wall.

See demo - Example 6

Social Network Wall - Modern Layout (Light)

To set the modern light layout change the plugin's style options to the following:

style: {
	layout: 'modern',
	colour: 'light'
}

See demo - Example 7

Social Network Wall - Modern Layout (Dark)

To set the modern dark layout change the plugin's style options to the following:

style: {
	layout: 'modern',
	colour: 'dark'
}

See demo - Example 8

Quick start - no customized options! Only minimum settings for the social network user ID's are required - View Example 1

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: 'designchemical'
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			google: {
				id: '111470071138275408587',
				api_key: 'AIzaSyB1UZNnscjMDjjH-pi_XbnLRld2wAqi3Ek'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA',
				thumb: '0'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'isacg'
			},
			tumblr: {
				id: 'richters',
				thumb: 250
			}
		},
		twitterId: 'designchemical',
		iconPath: 'images/dcsns-dark/',
		imagePath: 'images/dcsns-dark/'
	});
});

There are no limits on the number of feeds that can be added to the social stream for each social network. To add multiple profiles include the relevant social network IDs as a comma-separated list.

View Example 2

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: 'designchemical,wordpress,jquery,/9927875,#designchemical'
			}
		}
		twitterId: 'designchemical'
	});
});

The plugin uses a basic template system, which offers some options to add/remove content from the stream items as well as change the order in which these content blocks appear. This can be modified using the "out" option.

View Example 3

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: 'designchemical',
				out: 'intro,text,user,share'
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical',
				out: 'intro,title,user,share'
			},
			stumbleupon: {
				id: 'remix4',
				out: 'intro,title,user,share'
			},
			facebook: {
				id: '157969574262873',
				out: 'intro,title,user,share'
			},
			google: {
				id: '111470071138275408587',
				out: 'intro,title,user,share'
			},
			delicious: {
				id: 'designchemical',
				out: 'intro,title,user,share'
			},
			vimeo: {
				id: 'brad',
				out: 'intro,title,user,share'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA',
				out: 'intro,title,user,share'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas',
				out: 'intro,title,user,share'
			},
			flickr: {
				id: '',
				out: 'intro,title,user,share'
			},
			lastfm: {
				id: 'lastfm',
				out: 'intro,title,user,share'
			},
			dribbble: {
				id: 'frogandcode',
				out: 'intro,title,user,share'
			},
			deviantart: {
				id: 'isacg',
				out: 'intro,title,user,share'
			}
		},
		twitterId: 'designchemical'
	});
});

The plugin's "wall" display feature uses jQuery isotope to create a filterable layout of all your stream items - View Example 4

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: '/9927875,#designchemical,designchemical',
				thumb: true
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical,http://feeds.feedburner.com/codecondo'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			google: {
				id: '111470071138275408587'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'isacg'
			},
			tumblr: {
				id: 'richters',
				thumb: 250
			}
		},
		rotate: {
			delay: 0
		},
		twitterId: 'designchemical',
		control: false,
		filter: true,
		wall: true,
		cache: false,
		max: 'limit',
		limit: 10,
		iconPath: 'images/dcsns-dark/',
		imagePath: 'images/dcsns-dark/'
	});
});

If you wish to display the wall feed randomly as opposed to date order just set the "order" option to "random" - View Example 5

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: '/9927875,#designchemical',
				thumb: true
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas',
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'isacg'
			},
			tumblr: {
				id: 'richters',
				thumb: 250
			}
		},
		rotate: {
			delay: 0
		},
		twitterId: 'designchemical',
		control: false,
		filter: true,
		wall: true,
		order: 'random',
		max: 'limit',
		iconPath: 'images/dcsns-dark/',
		imagePath: 'images/dcsns-dark/'
	});
});

The social network wall is automatically responsive and will adjust the number of columns based on your page width. Just insert the wall into a responsive page - View Example 6

To create a wall using show modern dark layout set the "style" options View Example 7

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: '/9927875,#designchemical,designchemical',
				thumb: true
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical,http://feeds.feedburner.com/codecondo'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			google: {
				id: '111470071138275408587'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'isacg'
			},
			tumblr: {
				id: 'richters',
				thumb: 250
			}
		},
		rotate: {
			delay: 0
		},
		style: {
					layout: 'modern',
					colour: 'dark'
				}
		twitterId: 'designchemical',
		control: false,
		filter: true,
		wall: true,
		cache: false,
		max: 'limit',
		limit: 10,
		iconPath: 'images/dcsns-dark/',
		imagePath: 'images/dcsns-dark/'
	});
});

To create a wall using show modern light layout set the "style" options View Example 8

$(document).ready(function($){
	$('#social-stream').dcSocialStream({
		feeds: {
			twitter: {
				id: '/9927875,#designchemical,designchemical',
				thumb: true
			},
			rss: {
				id: 'http://feeds.feedburner.com/DesignChemical,http://feeds.feedburner.com/codecondo'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			google: {
				id: '111470071138275408587'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'FilmTrailerZone/UUPPPrnT5080hPMxK1N4QSjA'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'isacg'
			},
			tumblr: {
				id: 'richters',
				thumb: 250
			}
		},
		rotate: {
			delay: 0
		},
		style: {
					layout: 'modern',
					colour: 'light'
				}
		twitterId: 'designchemical',
		control: false,
		filter: true,
		wall: true,
		cache: false,
		max: 'limit',
		limit: 10,
		iconPath: 'images/dcsns-dark/',
		imagePath: 'images/dcsns-dark/'
	});
});

If nothing is appearing on the screen check the following:

• Is the jQuery library included in the page and positioned BEFORE the social share plugin?
• Is the jquery social media tabs plugin file included in the page?
• Is the div tag with the correct ID included in the page between the "body" tags?
• Check the page using firebug for any other jquery/javascript errors that may be stopping the plugin from initialising

If the feed returns an error the plugin will insert the error text into the tab. If the feed cannot be found first check your user ID/username to make sure that this matches your profile.

If your twitter feed is not displaying make sure that you have set up your Twitter API Credentials. If these have been set up correctly then check that the correct path and filename are inserted into the twitter: url option. The default value is "twitter.php", which will be valid if the location of the twitter.php file is in the same directory as the page containing the tabs. If you are unsure then enter the absolute path & filename for this file - e.g

twitter: {
    url: 'http://www.yourdomain.com/social-stream-folder-name/twitter.php'
		}

If the twitter feeds are not showing and there are no errors this may be due to the limits imposed by Twitter on their API:

Searches - 180 calls per 15 mins.

Lists - 180 calls per 15 mins.

Users - 180 calls per 15 mins.

During this time other users will still be able to view your twitter feeds as limits are on a per user and per application basis.

There are 2 main reasons your facebook feed may not work:

1. You are trying to use a facebook profile instead of a page.

For more information on how to create a facebook page see - http://blog.hubspot.com/blog/tabid/6307/bid/5492/How-to-Create-a-Facebook-Business-Page-in-5-Simple-Steps-With-Video.aspx

2. Your facebook settings restrict the age of the user that may view your page - in order for the facebook feed to work you must remove any age restriction from your fan page.

To get your facebook gallery ID browse to your facebook gallery page - e.g:

https://www.facebook.com/195819930466243/photos/?tab=album&album_id=195824323799137

The ID for the gallery is shown at the end of the URL as the "album_id" parameter - in the example above this would be - 195824323799137

To get your google profile ID for the google +1 tab go to your google accounts page and click on the “edit profile” link.

Check the URL in the browser address bar – your profile ID is the number in the middle of the URL:

https://profiles.google.com/100058553707375301897/about/

The latest version of the Youtube API no longer recognises youtube usernames. We have created a quick online tool, which will allow you to get your list ID for your username

Browse to the following link - How to get your youtube ID

In the form with the heading "Input your Youtube Profile Name" enter your profile name into the "username" field and click "submit".

Your list ID will appear in the "List ID" field

Browse to the following URL - changing YOUR USER NAME & YOUR ACCESS TOKEN for your values:

https://api.instagram.com/v1/users/search?q=YOUR USER NAME&access_token=186786085.3a81a9f.a0716c493a5042fb8122151735e898e4

The Instagram API should then load a page containing text with your profile details similar to the format shown below:

{"meta":{"code":200},"data":[{"username":"YOUR USER NAME","bio":"","website":"","profile_picture":"","full_name":"","id":"YOUR USER ID"}]}

Search for the "id" parameter for your username.

You can use the twitter search function to show searches from specific usernames using the following format -

e.g. to search tweets containing "jquery" from user "designchemical"

#jquery+from:designchemical

To disable specific share links from the feeds add the following css:

Facebook:

.share-facebook {display: none;}

Twitter:

.share-twitter {display: none;}

Google +:

.share-google {display: none;}

LinkedIn:

.share-linkedin {display: none;}

To disable all share links from the feeds add the following css:

.section-share {display: none;}

If you wish to remove specific posts from a stream you can use the "remove" option

Enter the URL's of the posts you wish to remove separated by a comma

Example - to remove the following 2 posts:

https://twitter.com/designchemical/status/364012915533164544

http://www.facebook.com/DesignChemical/posts/575999262459900

Add the following option to your initialisation code:

remove: 'https://twitter.com/designchemical/status/364012915533164544,http://www.facebook.com/DesignChemical/posts/575999262459900'

Although the plugin does not include a lightbox, these can be included separately as a plugin to enhance the social stream. An example of using a lightbox with the stream to show inline youtube and vimeo videos can be found on our demo website - Adding a jQuery Lightbox.

In the demo example we have used the jQuery prettyPhoto lightbox. Below is an example of the additional code added to open the videos in the ligthbox popup:

jQuery(window).load(function(){
	jQuery(".dcsns-youtube .section-thumb a, .dcsns-vimeo .section-thumb a").prettyPhoto({
		autoplay_slideshow: false, overlay_gallery: false, social_tools:false, deeplinking: false, theme:'pp_default', show_title: false});
		
});

The actual code required would depend on which lightbox you wish to use and usually can be found in the lightbox documentation.

The only key requirement is that the jQuery code is initialised using the jQuery(window).load(function() as the feed must be fully loaded before the lightbox is added.

Each social network feed item has its own css class, which allows you to target specific feed - e.g. dcsns-youtube for youtube feeds, dcsns-vimeo for vimeo feeds, etc.

Lightbox Code If Using Fancybox

If you are using the jQuery Fancybox lightbox plugin you can use the following code for youtube videos:

jQuery(window).load(function(){
	jQuery(".dcsns-youtube .section-thumb a").click(function() {
    jQuery.fancybox({
            'padding'       : 0,
            'autoScale'     : false,
            'transitionIn'  : 'none',
            'transitionOut' : 'none',
            'title'         : this.title,
            'width'     : 680,
            'height'        : 495,
            'href'          : this.href.replace(new RegExp("watch\\?v=", "i"), 'v/'),
            'type'          : 'swf',
            'swf'           : {
                 'wmode'        : 'transparent',
                'allowfullscreen'   : 'true'
            }
        });

    return false;
	});
 });

• jQuery Social Stream: Design Chemical
• jQuery Isotope: http://isotope.metafizzy.co

• PHP Library to support OAuth for Twitter's REST API: Abraham Williams
• PHP OAuthToken Class