Documentation

WP Social Media Slider is an awesome and easy plugin for displaying your Facebook, Twitter, and Instagram posts on your WordPress website. This documentation will help you get up and running in no time. If you there is a topic that you would like to have added to this documentation, feel free to contact us with your suggestion.

Installation Guide

The easiest way to install WP Social Media Slider is to upload the plugin ZIP file via the WordPress dashboard. Here’s a step by step guide to completing that process.

Installing via the WordPress Dashboard

Open the e-mail that contains your license key and download link. Click on the download link that says “wp-social-media-slider.zip”. Be sure to keep track of the location to which is was downloaded; you’ll be using that ZIP file in a moment.
Navigate to your website and log in to your WordPress admin panel.
Hover your mouse over “Plugins” and click on the “Add New” link.
Click on “Upload Plugin” (it’s at the top, next to the “Add Plugin heading”)
Click “Choose File” and use the file dialog box to select the ZIP file that you downloaded in step 1
Click “Install Now.” If it installs correctly you’ll see several lines of text and the words “Successfully installed the plugin WP Social Media Slider.”
Click “Activate Plugin”

That’s it! Your plugin is now installed.

How to Activate Your License Key

Now that you have installed the plugin, it’s important to activate your license key. You can do this at the plugin’s settings page.

To get to the WP Social Media Slider settings page, move your mouse over “Settings” in the sidebar and click on “Social Media Slider.” When the page loads, you’ll see a notification at the top that says that you haven’t activated your license yet. Enter your license key into the text box and click “Activate.” Viola, it’s activated!

If you ever decided to switch websites that you are using WP Social Media Slider on, you can simply click the “Deactivate License” at the top of the Settings page.

Basic Usage

Once you’ve installed WP Social Media Slider, there are a couple different ways to display it.

Including it via shortcode

The most common way of using it is as simple as including the following shortcode into your page:

[wp-social-media-slider]

The shortcode will be replaced with the social media slider.

For the most part, all of the slider customization can be handled via the WP Social Media Slider settings page, which is described in depth in the sections that follow.

If, however, you have multiple sliders on your website and want to use different social media accounts on each page, you can override the account settings defined on the main settings page by using shortcode parameters (as of version 1.1.3). Any setting that you do not specifically override will default to the value set on your settings page.

[wp-social-media-slider facebook_enable="1" facebook_page="http://facebook.com/laternastudio" twitter_enable="1" twitter_username="laternastudio" instagram_enable="1" instagram_user_id="263973657"]

Of course, you can disable the different social networks by using ‘0’ instead of ‘1’.

Including it in a PHP template

In some cases you may want to include the WP Social Media Slider in a PHP template file. In those cases, including it is as simple as using the following php code:

echo do_shortcode( '[wp-social-media-slider]' );

If you’re in an HTML section of the PHP template, don’t forget to use the opening and closing php tags:

<?php echo do_shortcode( '[wp-social-media-slider]' ); ?>

General Settings

The general settings section of the plugins page is fairly straight-forward, but here is some more specific details regarding how each of the settings works.

Display Type

Display type allows you to customize the methodology that the plugin uses to select posts for display. There are two options, described below. Regardless of your selection, your posts will always be organized chronologically in the slider.

Display posts by most recent (regardless of social media network).

Displaying by most recent means that the plugin will search for posts across all of your enabled social media networks (Facebook, Instagram, and/or Twitter), and select, for example, the 10 most recent posts (assuming 10 is the number you’ve set in the Total Posts setting). That means that if you have 10 tweets that are more recent than any of your Facebook or Instagram posts, it will only display those 10 tweets.

Displaying by most recent is a great way to make sure that your freshest social media content is being shown to users.

Display an equal number of posts from each social network.

If you’re not very good about staying up to date on all of your social networks, you may prefer to choose the second option, which is to display an equal number of posts from each social network. This means that if you choose to display 9 total posts on your site, it will display 3 Facebook posts, 3 Instagram posts, and 3 Tweets–the three most recent from each network. Of course, if you only had Facebook and Instagram enabled, it would display 5 of one and 4 of the other.

An exception to this rule is when you do not have enough posts on a social network to meet the criteria. For example, if you set your total posts to 15, you would expect to see 5 posts from each of the social networks. But what if you only have 3 tweets total on your Twitter account? In this case, WP Social Media Slider will simply use all 3 of those tweets, and for the 2 more that you didn’t have, it will simply grab one more of each Facebook and Instagram–insuring that you still get 15 posts in all.

Total Number of Posts

As you might expect, this setting allows you to choose the total number of posts that your plugin will display from your social media networks. Due to API limitations, this should be under 100.

Note: there’s a limit on the number of posts that you can pull in from some of the networks. For example, Instagram can only retrieve the 20 most recent posts when it’s in Sandbox Mode—which is what you’ll have unless you get special approval from Instagram for your API access (which is not covered here). Facebook, on the other hand, has a limit of 100 posts. If you set your total number of posts to over 100, Facebook will cause an error which will crash WP Social Media Slider.

Cache Duration (in sec.)

One of the great features about WP Social Media Slider is the fact that it caches the posts that it pulls from the social media networks. In layman’s terms, this means that when WP Social Media Slider retrieves posts from Facebook, Twitter, and Instagram, it will save the posts on your site. This makes for faster page load times and (for you technical people) will make sure that WP Social Media Slider does not exceed the API Request Limit’s put in place by Facebook, Instagram, and Twitter.

The Cache Duration setting allows you to customize how long the site will wait before communicating with the social media networks and re-retrieving the posts. So, for example, if you set this setting to 60 (which means 60 seconds), the site will re-query the social media networks for posts once every minute. This is on-demand, though, so it won’t happen when you don’t have visitors to your site; it only happens when a visitor is accessing your page.

AJAX Cache Refresh

This setting is a bit more confusing, but is worth understanding because it gives you the opportunity to improve the speed of WP Social Media Slider even more! In order to understand, you need to understand Lazy Loading, which WP Social Media Slider uses.

Lazy Loading essentially means that your site won’t wait for WP Social Media Slider to be ready before displaying your page. Rather, your site will display the page first, then finish loading the social media slider. This is good because sometimes Facebook, Twitter, and Instagram can take a little while to provide the posts that the slider is requesting. If they take 2 seconds to respond, for example, it’s good to make sure that the site doesn’t freeze during that time. Instead, the site loads while WP Social Media Slider unobtrusively gathers your posts and displays them when they’re ready. That’s lazy loading.

Now as you might expect, things are a lot quicker when we can just pull the posts from the cache (read the “Cache Duration” setting for more info on the cache). While Facebook, Twitter, and Instagram make us wait sometimes, our own handy dandy cache is pretty fast. That means that all the times that the social media slider is loading from the cache, it will load quickly, whereas when it is it is time to refresh the cache (that is, re-gathering posts from Facebook, Twitter, and Instagram), it will take a little longer.

The AJAX Cache Refresh circumvents the slow load time of the cache refresh by only ever loading posts via the cache. That means that each and every time you load your page, it will load the posts from the cache. When it is time to refresh the cache, WP Social Media Slider will still display the current posts from the cache, but will initiate a request in the background to update the cache. Then, next time the page is loaded, it will display the new post results.

At this point you may be thinking “Well if it’s so great, why do we have the ability to turn it off?” Well, there is a drawback, but it pretty much only affects low traffic sites. Here’s an example: let’s say that you have a site that only gets one visitor a day. Most likely, 24 hours is way longer than the Cache Duration that you’ve set, meaning that it’s way past time to refresh the cache when a visitor visits. If AJAX Cache Refresh is turned on, however, it will simply display the post results that were pulled in yesterday (while initiating a cache refresh in the background). That means that the visitor won’t be shown any of the posts that you’ve posted since yesterday. Of course, next time the page loads it will display the updated post results…but that doesn’t help your current visitor very much. The solution in this situation would be to disable Ajax Cache Refresh, therefore causing the site to wait for the cache refresh to finish before displaying the posts–meaning that the visitor would always see the latest posts if the cache duration has passed.

I have no clue what you’re talking about…

The AJAX Cache Refresh setting can be a bit confusing, so if you don’t get it, don’t worry. A good rule of thumb is that if you get at least several visits an hour (or if you aren’t very active on social media) make sure that AJAX Cache Refresh is enabled. If you get fewer visitors than that, make sure that it is disabled.

Display Color

Allows you to easily control the accent color that is used for WP Social Media Slider.

Auto-Play Slider

Determines whether or not the slider will cycle through posts automatically. This will be overridden if you are using custom JS initialization.

Omit Posts Shorter Than (Number of Characters)

Sometimes you may post a photo and include absolutely no text with it. That’s great within the context of Twitter, Facebook, and Instagram themselves–but it doesn’t work very well within the default design of the slider (though you could customize the templates to fix that!).

This setting addresses that issue. By default, it won’t display any posts that contain fewer than 40 characters. You can adjust as desired. To disable completely, set to 0.

Limit Total Post Length to (Number of Characters)

Sometimes your Facebook posts may be long and mess up the formatting of the slider. This setting allows you to automatically shorten the text and display a “Read More” link.

Custom JS Initialization

WP Social Media Slider uses Owl Carousel 2, which means that there are a lot of built-in JavaScript settings that you can take advantage of. Of course, you’ll have to have at least a rudimentary understanding of JavaScript to take advantage of them. If you do, you can completely customize the initialization settings that WP Social Media Slider uses. Custom JS Initialization is described in more depth in the Advanced Customization section.

Setting up Facebook

Note: As of May 2018, Facebook now requires you to have SSL (https://) on your site in order to interact with their API. Many hosts offer SSL for free, now, so be sure to check with your host about getting that set up if you need to. Or, if you run your own server, Digital Ocean has a great tutorial about the setup process. Ultimately, they usually tend to rely on the free Let’s Encrypt certificates. Also, if you don’t have host picked out yet, consider Flywheel. They’re the best WordPress host I’ve found, and they offer free and easy SSL setup.

Admittedly, the whole “API” thing might be scary if you’re not a very technical person. If that’s the case, have no fear. We’ll make this as painless as possible.

Step One: Create an App on Facebook

It’s not a literal “app,” like the kind that you install on your phone. It’s just a simple tool that will give your site permission to access the posts on Facebook. Here are the steps to create it.

Log in to your Facebook account.
Navigate to https://developers.facebook.com/apps/
Move your mouse over your picture in the top right corner, and select “Create App” from the dropdown that appears.
Enter a Display Name and Contact Email. The Display Name can just be something like “WP Social Media Slider”–it’s just to help you remember what the app is for. Click ‘Create App ID’ when done.
If a security captcha pops up (that thing where you have to prove you’re not a robot), complete it and click submit.
It will now show you a page where you are supposed to select the type of app you want to create (Marketing API, Pages API, etc.). Ignore that; do not make a selection.
Click the “Settings” tab in the left sidebar and choose the “Basic” submenu item
Scroll to the bottom and click “Add Platform”
Choose “Website”
Enter your site’s web address, including https:// (As noted above, HTTPS is required now). This does not need to be the exact page that you will be displaying the slider on; it just needs to be the domain. For example: https://www.example.com
Click “Save Changes” at the bottom.

Note: Do not click the ON/OFF switch at the top of your app settings page. It should remain OFF at all times. If you turn it ON, the app will not work with WP Social Media Slider.

Note #2: Do not try to manually enable manage_pages permissons somehow. That will be taken care of automatically when you use the “Get Access Token” button.

And there you go! Your app is created! You may as well keep that page open, though, because you’ll need the App ID and App Secret for WP Social Media Slider.

Step Two: Enter the App ID and App Secret in to the WP Social Media Slider settings page

Go ahead and navigate to the settings page for the social media slider. Scroll down to the Facebook Settings section. There are four fields, but let’s just worry about the last two for now: Facebook App ID and Facebook App Secret. Next, open the window containing the information about the Facebook App you created (you know, the window that was open at the end of step one?). If you accidentally closed that window, you can access it again by navigating to the Facebook developers apps page and clicking on the link for the app you created. You’ll notice that on this page there is an App ID at the top. Go ahead an copy it, then copy and paste it back in to the “Facebook App ID” field for the WP Social Media Slider Facebok Settings. Now, on the Facebook app page, click “Show” next to the dots that indicate the App Secret. It may prompt you to re-enter your password. Copy and paste the App Secret into the “Facebook App Secret” field on the WP Social Media Slider settings page.

Step Three: Enter your Facebook Page URL

Simply navigate to your Facebook page and copy and paste it’s URL into the “Facebook Page URL” setting field. Also, as mentioned on the home page of wpsocialmediaslider.com, this will not work with Facebook timelines (personal walls, that is). It will only work with actual pages–like, a page that you manage (although it will work with pages that you don’t manage, as long as they are public).

Step Four: Enable Facebook

This one’s easy. Simply turn the “Enable Facebook” option on!

Step Five: Get your Access Token

In order to get the most reliable steps, I recommend that you go to Facebook and log out before following the steps below.

If you haven’t yet saved your WP Social Media Slider settings page, do that now.
Scroll to the Facebook section and click “Get Access Token.”
Enter the username and password of a user that has admin access to the Facebook page you want to show in the slider, and click Log In.
Click “Continue as [Your name]”
Click the checkbox next to the page you plan to show in the slider (or just check “All Pages”), then click “Next”
Verify that “Read content posted on the page” is set to “Yes”, and click Done (other permissions are not needed.)
Click “Ok” on the confirmation screen.
Save your WP Social Media Slider Settings page, which will cause the page access token to be retrieved

That’s it! you’re all set up! Note: If you still get a Facebook error that says “SSL certificate problem: unable to get local issuer certificate” it means that your SSL certificate is set up incorrectly. 99% of the time, this is because you’re working on a local environment and just haven’t set up your SSL yet. There are a few good StackOverflow discussions of this issue, and how you can resolve it. You won’t ever encounter an issue like that with Flywheel or another host that sets up your SSL for you.

Setting up Instagram

Over the years it’s gotten progressively more complicated to set up Instagram. Nevertheless, if you stick to it and closely follow the steps below, you’ll be set up in no time.

Step One: Set up a Facebook App (Instagram Now Uses a Facebook App)

If you’ve already set up an app to use with Facebook, you can actually use that same app for Instagram by just adding the Instagram “product” to that app. Once you’ve done that you can continue below at step 7.

But if you’re starting from scratch, or even if you just want a full walkthrough from scratch, use the steps below.

Log in to your Facebook account.
Navigate to https://developers.facebook.com/apps/
Move your mouse over your picture in the top right corner, and select “Create App” from the dropdown that appears.
Enter a Display Name and Contact Email. The Display Name can just be something like “WP Social Media Slider”–it’s just to help you remember what the app is for. Click ‘Create App ID’ when done.
If a security captcha pops up (that thing where you have to prove you’re not a robot), complete it and click submit.
It will now show you a page where you are supposed to select the type of app you want to create (Marketing API, Pages API, etc.). Find “Instagram” and click “Set Up.”
Now we’re going to get sidetracked for a moment. Click the “Settings” tab near the top of the left sidebar and choose the “Basic” submenu item
Scroll to the bottom and click “Add Platform”
Choose “Website”
Enter your site’s web address, including https:// (HTTPS is required). This does not need to be the exact page that you will be displaying the slider on; it just needs to be the domain. For example: https://www.example.com
Click “Save Changes” at the bottom.
Click “Instagram” in the left sidebar, then click on “Basic Display” underneath it.
Click “Create New App”
Leave the Display Name as it is and click “Create App”
Find the “Valid OAuth Redirect URIs” setting. It is critical that you enter the correct value here. It should be https://yourwebsite.com/wp-content/plugins/wp-social-media-slider/includes/networks/instagram/auth.php,where you replace yourwebsite.com with your actual domain.
Enter the same url into the fields called “Deauthorize Callback URL” and “Data Deletion Request URL”
Click “Save Changes” at the bottom
Click the blue button that says “Add or Remove Instagram Testers”
Scroll to the bottom of the new page and click “Add Instagram Testers”
Type in the username that you’d like to use for Instagram and click “Submit”
In a separate tab (keep your Facebook tab open, you’ll need it), go to instagram.com and log in to the Instagram account you just invited
Go to your profile page and click the settings button (it looks like a gear), then click “Apps and Websites”
Click the tab that says “TESTER INVITES”
Click “Accept” on the invitation that matches your app’s name.
Return to the Facebook tab
In the sidebar click “Instagram”, then “Basic Display”
Notice the “Instagram App ID” and “Instagram App Secret”. You’ll need those in a moment.

Great! You have successfully created your client. Keep this window open, though, since we’ll need to use those credentials.

Step Two: Connect your Instagram client to the plugin

Navigate to the settings page for WP Social Media Slider and scroll down to the Instagram section.

Copy the Instagram App ID from the Instagram client page and paste it into the Client ID field in the WP Social Media Slider settings page, then do the same for the Instagram App Secret. Now click Get Access Token. If you entered everything correctly, it should pop up with a window that asks for you to authorize the connection between the plugin and your client. Authorize it, and it will retrieve the access token.

Step Four: Enable Instagram

Now you can simply turn Instagram on and enjoy!

Optional Step: Displaying Additional Sliders of Other Instagram Users

Due to changes in the Instagram API, this doesn’t work very well anymore. Access Tokens you get via this method will expire after 60 days. Nevertheless, if you don’t mind manually refreshing every 60 days it can be accomplished with the method described below.

If you’d like to have different sliders that show different Instagram accounts, you can do so by using the instagram_access_token shortcode attribute. Something like this:

[wp-social-media-slider instagram_enable="1" instagram_access_token="4103124397.eff855f.2eafe29d637548da8e27e5d60a12b233"]

Of course, in order for this to work, you must use a valid access token. Remember, as described above, any account that you’d like display in the slider must be authorized with your app.

There are two things that you’ll need to do in order to get an access token for another account.

Step 1: Add the additional account as an Instagram Tester

Refer back to the steps above and complete steps 18-27 for another account.

Step 2: Get the access token for the account

We’ll now use the Access Token finder to authorize your desired account with your app. You can do that like so:

Go to instagram.com and make sure you’re not logged into any account
Go back to the WPSMS settings page and find the Instagram Access Token Finder setting
Enter your Instagram app’s client ID in the client ID field
Click ‘Get Access Token’
Log in with the account you want to get the access token for (the account you want to show in the slider).
When you authorize, your access token will appear in the Instagram Access Token Finder text box.
Copy the new access token and enter it as the instagram_access_token shortcode attribute in your slider

Setting up Twitter

Step One: Enable Twitter and enter your Twitter handle.

You may as well enable Twitter right off the bat; it won’t go into effect until you save anyways. Next, enter your Twitter username (AKA “handle”) into the “Twitter Username” field. Don’t include the @ symbol.

Step Two: Set up a Twitter App and connect it to WP Social Media Slider

By now you probably know the drill; you need to create an “app” in order for Twitter to let you retrieve posts from its website. Thankfully creating an app isn’t too difficult. Here are the steps.

Creating a Twitter Developer Account

Twitter requires a special type of account—a “developer” account—in order to create an app. To do that follow these steps:

Go to https://developer.twitter.com/en/apps
Log into your regular Twitter account
Click “Create New App” in the upper right side of the screen. A popup will appear saying you need a developer account in order to create new apps. Click “Apply”.
A page will appear asking your primary reason for needing a developer account. It doesn’t matter too much what you choose, but I recommend “Doing something else” for simplicity’s sake. Then click “Next.”
A page will appear asking you to confirm/enter a few more personal details. Enter and verify your phone number if you haven’t done so already. Choose your country and enter a name for them to call you. When done, click “Next”.
A page will appear asking how you’ll use the Twitter API. In the description field, enter: “I am using a WordPress plugin called “WP Social Media Slider” to display Tweets on my website. That plugin needs to interact with the Twitter APIs in order to function. The plugin ONLY gets tweets and displays them on my site. It displays them grouped together horizontally in a carousel. It does not tweet, retweet, or share tweets.
You’ll now see multiple checkboxes where you select how you’ll be using API access. Choose “No” for all checkboxes except choose “Yes” next to “Do you plan to display Tweets or aggregate data about Twitter content outside of Twitter?” In the description for that field, enter the same description as before: “I am using a WordPress plugin called “WP Social Media Slider” to display Tweets on my website. That plugin needs to interact with the Twitter APIs in order to function. The plugin ONLY gets tweets and displays them on my site. It displays them grouped together horizontally in a carousel. It does not tweet, retweet, or share tweets.” Then click “Next”.
Make sure your information looks correct, then click “Looks Good!”
Read the Developer Agreement, check the box, and click “Submit Application”
Go to your email account (the one you signed up with) and click the confirmation link.
Great! Now your developer account is under review. It should be reviewed and confirmed within a couple hours. Once confirmed, you can continue with the steps below.

Creating the App

Go to https://apps.twitter.com/
Log in
Click “Create New App” in the upper right side of the screen
Enter a name for your application. It has to be unique (not used by anyone else). A good bet is to do “WP Social Media Slider” followed by your twitter handle. Like “WP Social Media Slider laternastudio”. This application name won’t be visible anywhere, though, so it doesn’t really matter.
Enter a description for your application, such as “WP Social Media Slider plugin for WordPress.”
Enter your website’s url.
Ignore the Callback URL field
Review the terms if you’d like, and check “Yes, I agree”
Click “Create your Twitter Application”
On the page that appears, select the “Keys and Access Tokens” tab
Scroll down to the button on the bottom, which says “Create my access token”

Now that your app is created, all you need to do is copy and paste the Consumer Key, Consumer Secret, Access Token, and Access Token Secret into their corresponding fields in the Twitter Settings section of the WP Social Media Slider settings page. Take care of that now.

That’s it! You’re all set up! Don’t forget to save your changes to put them into effect.

Advanced Customization

There are a couple ways that you can take customization a step further than simply editing the settings on the settings page. We’ve broken these into functionality customization and style customization, though in some cases there is overlap.

Customizing Functionality

One of the primary methods for advanced customization is to use the Custom JS Initialization setting. This setting is described in depth in the General Settings documentation above.

All you need to do is use the same syntax shown in the code examples on the Owl Carousel 2 website. There’s just one important thing to remember: you need to make sure that you change the jQuery selector from .owl-carousel to .wp-social-media-slider.

For example, in order to customize your responsive breakpoints, you could follow the instructions on Owl Carousel 2’s responsive demo page and set up the Custom JS Initialization setting like this:

$(".wpsms").owlCarousel({
    loop:true,
    margin:10,
    responsiveClass:true,
    navText: ['',''],
    stagePadding: 1,
    responsive:{
        0:{
            items:1,
            nav:true
        },
        1000:{
            items:2,
            nav:true,
            loop:false
        }
    }
});

There are all kinds of options; take a look at the Owl Carousel 2 documentation and demos to get the full scoop. Not all of the option combinations have been tested with WP Social Media Slider, so it’s possible that you may run into a situation where the CSS for your social media slider may need some tweaking; you can just add those tweaks to your theme’s CSS.

Customizing Styles (CSS)

For the most part, you can simply re-define WP Social Media Slider css rules in your themes style.css file. If there’s a ton of customization that you’d like to do, though, you may like to completely replace the WP Social Media Slider stylesheet rather than simply overwriting the CSS rules.

In order to do that, all you need to do is dequeue the default plugin stylesheet and enqueue a copy of it that you have saved in your theme folder. You can then edit the copy to your heart’s content!

First, copy the stylesheet in /wp-content/plugins/wp-social-media-slider/public/css/wp-social-media-slider.css and put the copy inside your themes root folder. Make sure you give the copied file the same filename as your PHP code expects. For example, the code below assumes that you name the copy ‘custom-wp-social-media-slider‘.

Simply drop this code in to your functions.php to take care of the css replacement!

add_action( 'wp_enqueue_scripts', 'wpsms_replace_stylesheet', 20 );

function wpsms_replace_stylesheet() {

    wp_dequeue_style( 'wp-social-media-slider' );
    wp_enqueue_style( 'custom-wp-social-media-slider', get_stylesheet_directory_uri() . '/custom-wp-social-media-slider.css'  );

}

Customizing the Views (HTML/PHP)

If desired, it’s possible to entirely overhaul the posts blocks that are output by the slider. This allows you to achieve almost any desired result. The accomplish this, all you need to do is copy the post type’s view from its current location to a wp-social-media-slider folder in your theme directory. For example, to edit the Twitter post view, you’d copy the file from:

wp-content/plugins/wp-social-media-slider/includes/networks/twitter/wpsms-twitter-public-view.php

to:

wp-content/themes/your-theme/wp-social-media-slider/wpsms-twitter-public-view.php

Of course, instead of your-theme, you’d want to use your actual theme folder. You can do this for each of the different networks: Facebook, Twitter, and Instagram.

Once you’ve copied it over, you can make any modifications that you’d like to to the view file, and it will stay put even when you update the plugin.

Understanding the Cache

The caches improves performance by making it so that your site doesn’t have to get in touch with Facebook, Twitter, and Instagram every time your slider loads. Instead, WP Social Media Slider collects the posts from Facebook, Twitter, and Instagram, and saves them on your site. Then, every time the slider needs the posts in the future, it can just use the version saved on your site—which is much faster than querying Facebook, Twitter, and/or Instagram.

Of course, eventually you’ll need reload the version saved on your site (called ‘refreshing the cache’) and update it with new posts from your social media networks. How often that “refresh” happens is controlled by the Cache Duration setting. For example, if you set your cache duration to 60 seconds, WP Social Media Slider will only refresh the cache if it’s been at least 60 seconds since the cache was last refreshed.

Multiple Caches for Multiple Sliders

If you set up your site with multiple WPSMS sliders (e.g. using shortcode attributes to make multiple sliders with different Twitter handles), WPSMS will maintain a separate cache for each unique slider. For example, if your homepage had two sliders, each showing a different Twitter account, a separate cache will be maintained for each of them. Conversely, if you show the same slider twice on a page, it will use the same cache—after all, it’s the same slider!

Examining and Clearing your Cache

If you’d like to see information about your current cache or clear you current cache, navigate to your WP Social Media Slider settings page and click on the “Cache Info” link at the top.

Filter Reference

If there are filters that you’d like to have added to the plugin, don’t hesitate to ask! If your request is feasible, we’ll do our best to add it to the plugin on the double!

wpsms-post-html

This filter allows you to change the body text of the social media posts. A post object is passed with it so that you can determine whether the post you’re dealing with is a Twitter, Facebook, or Instagram post.

Example Usage (in your functions.php file):

/**
 * You can easily adjust the html of a post.
 */

add_filter( 'wpsms-post-html', 'wpsms_custom_html', 10, 2 );

function wpsms_custom_html( $html, $post ) {
	$html .= " That's all, folks!";
	return $html;
}

/**
 * In some cases you may want to perform different tweaks depending
 * on whether the post is Facebook, Instagram, or Twitter.
 */

add_filter( 'wpsms-post-html', 'wpsms_custom_html', 10, 2 );

function wpsms_custom_html( $html, $post ) {
	if ( $post->type == 'twitter' ) {
		$html .= '<p><a href="#">Retweet</a>';
	}

	return $html;
}

wpsms-post-date

This filter allows you to change the date formatting. A post object is passed with it so that you can determine whether the post you’re dealing with is a Twitter, Facebook, or Instagram post.

Example Usage:

/**
 * By default, the currently used text for the date is passed
 * though. Edit it and return your results.
 */

add_filter( 'wpsms-post-date', 'wpsms_custom_date', 10, 2 );

function wpsms_custom_date( $date, $post ) {
	$date .= ' or so.';
	return $date;
}

/**
 * Use the Unix Timestamp of the post, stored in $post->unix_timestamp
 * to display an entirely different format for the date.
 */

add_filter( 'wpsms-post-date', 'wpsms_custom_date', 10, 2 );

function wpsms_custom_date( $date, $post ) {
	$new_date = 'Posted on' . date( 'm-d-Y', $post->unix_timestamp );
	return $new_date;
}

/**
 * In some cases you may want to display a different format depending
 * on whether the post is Facebook, Instagram, or Twitter.
 */

add_filter( 'wpsms-post-date', 'wpsms_custom_date', 10, 2 );

function wpsms_custom_date( $date, $post ) {

	if ( $post->type == 'twitter' ) {
		$new_date = 'Tweeted on' . date( 'm-d-Y', $post->unix_timestamp );
	}
	else {
		$new_date = 'Posted on' . date( 'm-d-Y', $post->unix_timestamp );
	}
	
	return $new_date;
}

wpsms-all-posts

This filter allows you to modify the list of social media posts (e.g. remove/change text/etc.). The variable provided to it is an array of post objects and the key for each element (post object) is the unix timestamp that it was posted at.

Example Usage (in your functions.php file):

/**
 * You can order the posts randomly like this
 */

add_filter( 'wpsms-all-posts', 'wpsms_randomize_posts', 10, 1 );

function wpsms_randomize_posts( $posts ) {
    shuffle( $posts );
    return $posts;
}

Understanding the Post Object

As you can see from the above examples, there are two arguments passed into the filters. The first is the content to be filtered (the date or the html). The second is just an object containing information about the post. You can use that second argument–the post object–to find out information about the post you are editing.

Here’s the format of the $post object:

WP_Social_Media_Slider_Post Object
(
    [type]           => facebook      // Could be "facebook", "instagram", or "twitter"
    [unix_timestamp] => 1424278572    // The Unix timestamp of time when the post was posted
    [username]       => laternastudio // The username associated with the social media account
)

If it is an instagram post it will actually have another property as well: images. The images property contains useful information about three different sizes of the image. The format of that will be something like this:

// An instagram post object
WP_Social_Media_Slider_Post Object
(
    [type]           => facebook      // Could be "facebook", "instagram", or "twitter"
    [unix_timestamp] => 1424278572    // The Unix timestamp of time when the post was posted
    [username]       => laternastudio // The username associated with the social media account
    [images]         => stdClass Object
        (
            [low_resolution] => stdClass Object
                (
                    [url] => http://scontent-a.cdninstagram.com/hphotos-xfa1/t51.2885-15/s306x306/e15/10979612_825916514147021_1989884961_n.jpg
                    [width] => 306
                    [height] => 306
                )

            [thumbnail] => stdClass Object
                (
                    [url] => http://scontent-a.cdninstagram.com/hphotos-xfa1/t51.2885-15/s150x150/e15/10979612_825916514147021_1989884961_n.jpg
                    [width] => 150
                    [height] => 150
                )

            [standard_resolution] => stdClass Object
                (
                    [url] => http://scontent-a.cdninstagram.com/hphotos-xfa1/t51.2885-15/e15/10979612_825916514147021_1989884961_n.jpg
                    [width] => 640
                    [height] => 640
                )

        )
)

Troubleshooting

We’ll add to this section as we notice user-side issues that seem to be common points of confusion. We also may add issues that involve compatibility with other plugins. If you have found an issue that we can either repair or add to this section, please let us know!

Q. The plugin simply shows a message that says “Please enable the Curl PHP extension on your server.” What do I do?

Curl is a tool that WP Social Media Slider uses to communicate with the Facebook and Twitter APIs. It’s included on most web servers, but if you don’t have it you can most likely get it by simply asking your web host to install it for you. It would be very rare indeed for a web host to refuse your request.

Q. The plugin won’t activate. There’s some error about Facebook.php and a square bracket (this character: [ )

The latest Facebook API uses some PHP 5.4+ only code, so you’ll need to make sure that your server is running at least PHP 5.4. You can often make this upgrade through your hosting cPanel, or your host might even take care of it for you!

Frequently Asked Questions (FAQs)

If there are any questions that we’ve missed, feel free to contact us using the contact form on our home page.

Q. What social media networks are supported?

The only social media networks supported at the moment are Facebook, Twitter, and Instagram. Other social media networks like Pinterest, LinkedIn, Google Plus, Tumblr, etc. may be added in the future. If so, all purchasers of the plugin will get free updates (note that Lite users will maintain the same restrictions).

Q. Can I display posts from my personal Facebook timeline?

Unfortunately WP Social Media Slider does not support personal Facebook profile pages (i.e. timelines). This is due to restrictions put in to place by Facebook. Thankfully, Facebook does not impose the same restrictions on pages (i.e. company pages, artist pages, etc.), so WP Social Media Slider works great with all pages.

Q. How difficult is it to set up the plugin?

Ordinarily, connecting plugins like this to Facebook, Instagram and Twitter can be a real pain. In order to solve this problem, we’ve written a straight-forward step-by-step installation guide to help you. It makes installation and set-up a breeze; you’ll be up and running in minutes!

Q. Can I use on commercial sites?

Of course! You can use it on commercial sites, personal sites, etc. You can even use it on a client’s website.

Q. What if my theme/plugin already loads Owl Carousel?

By default, WP Social Media Slider bundles Owl Carousel 2.2.1 into the plugin JS and CSS. If you don’t want that, you can load a version of WP Social Media Slider that doesn’t include Owl Carousel by adding a filter on the JS and CSS filenames like so:

/**
 * Remove loading of core Owl Carousel CSS
 *
 * @param   string  $filename  the original filename
 * @return  string             the modified filename
 */
function wpsms_load_css_without_owl( $filename  ) {
    return 'wpsms-public-no-owl.css';
}
add_filter( 'wpsms_public_css_filename', 'wpsms_load_css_without_owl', 10, 1 );

/**
 * Remove loading of core Owl Carousel JavaScript
 *
 * @param   string  $filename  the original filename
 * @return  string             the modified filename
 */
function wpsms_load_js_without_owl( $filename  ) {
    return 'wpsms-public-no-owl.min.js';
}
add_filter( 'wpsms_public_js_filename', 'wpsms_load_js_without_owl', 10, 1 );

Table of Contents

Documentation

Installation Guide

Installing via the WordPress Dashboard

How to Activate Your License Key

Basic Usage

Including it via shortcode

Including it in a PHP template

General Settings

Display Type

Display posts by most recent (regardless of social media network).

Display an equal number of posts from each social network.

Total Number of Posts

Cache Duration (in sec.)

AJAX Cache Refresh

I have no clue what you’re talking about…

Display Color

Auto-Play Slider

Omit Posts Shorter Than (Number of Characters)

Limit Total Post Length to (Number of Characters)

Custom JS Initialization

Setting up Facebook

Step One: Create an App on Facebook

Step Two: Enter the App ID and App Secret in to the WP Social Media Slider settings page

Step Three: Enter your Facebook Page URL

Step Four: Enable Facebook

Step Five: Get your Access Token

Setting up Instagram

Step One: Set up a Facebook App (Instagram Now Uses a Facebook App)

Step Two: Connect your Instagram client to the plugin

Step Four: Enable Instagram

Optional Step: Displaying Additional Sliders of Other Instagram Users

Step 1: Add the additional account as an Instagram Tester

Step 2: Get the access token for the account

Setting up Twitter

Step One: Enable Twitter and enter your Twitter handle.

Step Two: Set up a Twitter App and connect it to WP Social Media Slider

Advanced Customization

Customizing Functionality

Customizing Styles (CSS)

Customizing the Views (HTML/PHP)

Understanding the Cache

Multiple Caches for Multiple Sliders

Examining and Clearing your Cache

Filter Reference

wpsms-post-html

wpsms-post-date

wpsms-all-posts

Understanding the Post Object

Troubleshooting

Q. The plugin simply shows a message that says “Please enable the Curl PHP extension on your server.” What do I do?

Q. The plugin won’t activate. There’s some error about Facebook.php and a square bracket (this character: [ )

Frequently Asked Questions (FAQs)

Q. What social media networks are supported?

Q. Can I display posts from my personal Facebook timeline?

Q. How difficult is it to set up the plugin?

Q. Can I use on commercial sites?

Q. What if my theme/plugin already loads Owl Carousel?