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 green 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
  OAuth redirect_uri: enter the URL of a page where the social stream is installed - this is required to get your access token, which you can then insert into the instagram options. Once you have the access token you can use this on all pages, which use the social stream plugin on the website listed above.
• Click the "Register" button

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

How to get your access token

• Browse to the page on your website used for the "redirect_uri" in the Instagram client ID setup (note this page must have the social stream installed - using either the network wall or the rotating feed.
• You will then be redirected to the Instagram login screen (if not already logged in) and then a confirmation screen where you approve your app's access to your Instagram data.
• Instagram will then automatically redirect you back to your website page given in the "redirect_uri" setting
• When the page loads check the URL in the browser - you should see the following URL format:
  
  http://your-redirect-uri#access_token=186786085.f59def8.1d34b28a52e04d36ba1dc52ca98215dc
• Copy the token code after the "http://your-redirect-uri#access_token=" - 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: {
  				id: '!186786085,#husky,@1394578',
  				accessToken: 'YOUR ACCESS TOKEN',
  				redirectUrl: 'http://your-redirect-uri',
  				clientId: 'YOUR CLIENT ID',
  				comments: 3,
  				likes: 10
  			}

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

There are 4 different types of feed that can be included from Instagram:

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'

2. Location Feed

To display the latest posts for a specific location enter a "@" followed by the instagram location ID - e.g.

id: '@123456'

3. Search Based On Tags

To display the latest posts for a specific tag enter a "#" followed by the tag text - e.g. to search for images tagged with "london"

id: '#london'

4. Search Based On Geographical Location

To display the latest posts for a geographical location you need 3 parameters - latitude, longitude and distance(in meters up to 5000m). Enter these values starting with a "?" followed by the lat, long and distance separated by a "/" e.g.

id: '?55.123/-1.345/1000'

Using Multiple Feeds

As with all of the other networks you can add multiple instagram feeds of any type by separating each ID with a comma - e.g.

id: '!123456,@123456,?55.123/-1.345/1000,#london,#newyork'

Displaying Comments & Likes

The instagram feed also includes the option to display the latest comments for each post plus thumbnails of users who liked the post. To add either comments or likes enter the number that you wish to display using the "comments" and "likes" option in the initialisation code - .e.g to display the last 5 comments + 10 liked thumbnails:

comments: 5,
likes: 10

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="/API/jquery-social-stream/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="/API/jquery-social-stream/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="/API/jquery-social-stream/css/dcsns_wall.css" media="all" />

The plugin uses several key images, including the icons for both the stream list as well as the filter/control navigation. If moving the files to a new location with a different directory structure make sure that you update the image paths in the CSS rules.

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

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.

For facebook page posts the ID of your facebook page must be used - this should be a numerical value, not the actual name of your facebook page - e.g. 157969574262873

To get the ID from your username you can use the following tool from facebook - replace "username" with the name of your facebook page profile:

https://graph.facebook.com/username

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

http://www.facebook.com/media/set/?set=a.110070145819348.18558.110041542488875&type=3

The ID for the gallery is the first set of numbers - in the example above this would be - 110070145819348

http://www.facebook.com/media/set/?set=a.110070145819348.18558.110041542488875&type=3

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

To get your instagram user ID first get your access token - see section above "Plugin Options -> Creating Your Own Instagram API Client ID & Access Token".

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=YOUR ACCESS TOKEN

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 usually located at the end of the text.

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