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.

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 below.

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="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 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: 'wired',
				thumb: '0'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'wyv1'
			},
			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: 'wired',
				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: 'wyv1',
				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/designmodo'
			},
			stumbleupon: {
				id: 'remix4'
			},
			facebook: {
				id: '157969574262873,Facebook Timeline/376995711728'
			},
			google: {
				id: '111470071138275408587'
			},
			delicious: {
				id: 'designchemical'
			},
			vimeo: {
				id: 'brad'
			},
			youtube: {
				id: 'wired'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas'
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'wyv1'
			},
			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: 'wired'
			},
			pinterest: {
				id: 'jaffrey,designchemical/design-ideas',
			},
			flickr: {
				id: ''
			},
			lastfm: {
				id: 'lastfm'
			},
			dribbble: {
				id: 'frogandcode'
			},
			deviantart: {
				id: 'wyv1'
			},
			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/'
	});
});

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/

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;}

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