Since its modest beginnings, the plugin and gallery script behind it has significantly evolved and is now providing you with a wealth of settings and options. There are currently well over 160 different settings, which allow you to style and adjust the gallery to your needs.

While I realize that such a large number of possible settings with all its possible combinations can be overwhelming (particularly to inexperienced users), I’m hopeful that the included Admin / Settings Panel will explain the most important and most frequent settings that might be of interest to you.

Note: For the purpose of this manual, “Album(s)” refers to the album selection, while “Photo(s)” refers to the actual images within each album.

h
This is the manual for the WordPress Plugin “jQuery Facebook Gallery WP” script. If you are looking for the manual for the standalone version of this plugin, please click here.

Plugin Manual

A. Included Features

  • Multitude of different settings to enable or disable included features
  • Full Admin / Settings Panel in WordPress to control all possible settings
  • Unique Shortcode for each Gallery (create unlimited Galleries)
  • Either pull all albums (but exclude the ones you don’t want), predefine the albums you want to be shown or show one single album directly
  • Pagination Feature (smart pagination, set number of thumbnails per page, set number of pages or no pagination)
  • LazyLoad Feature for thumbnails (will only load images when thumbnails are in view)
  • Social share feature for Facebook, Twitter and Google+
  • Includes a tool-tip plugin (qTip2) with several design options; although it is possible to use your own tool-tip solution
  • Includes three optional lightbox plugins (fancyBox, colorBox and prettyPhoto); although it is possible to user other lightbox solutions
  • Exclude individual images from being shown
  • Automatically include or exclude the Timeline album
  • Possible to translate it into any other language by using provided setting parameters
  • Select between a responsive (fluid width) or static layout (fixed width)
  • Optional two-directional (asc. / desc.) album sorting feature (name / number of images / date album created / date album last updated)
  • Smart filter option to filter albums and photos by age groups
  • Search Feature to search for albums by keywords
  • Set initial sorting direction and sorting criteria
  • Option for floating control bar that follows the user while scrolling through the album selection
  • Option to show dates in “from now” format (i.e. “2 days ago”) instead of standard date format
  • Optional logs (in console) for better debugging (i.e. number of albums or photes retrieved, error codes, etc.)
  • No need for PHP unless internal image scaler is utilized; an external (web based) image scaling service is utilized by default
  • No requirement for creating a Facebook App via your Facebook Profile

B. General Information

Please note that this plugin / script was NOT designed to work with personal Facebook pages due to limitations in the Facebook Graph API. It should work without problem with Facebook pages that belong to businesses and organizations or are marked as fan pages. Also, the albums you want to pull from Facebook to your website need to be set to public. Private albums will not work with this script.

The plugin / script allows you to pull an unlimited amount of albums and images from Facebook. Obviously, the more albums and images you load, the longer the gallery will take to pull the required information. Speed is also dependent upon the users internet connection.

In order to limit browser / memory overloads, the script (upon initialization) will only pull the album cover images along with the album information from Facebook. That information will be used to create the actual gallery overview. No actual album content (meaning the actual images within each album) will be loaded during initialization.

Only when a user clicks on the cover image (thumbnail) of a specific album will the images within that one album be pulled from Facebook. Images can then stored in the browser memory for as long as the user session lasts or pulled again if a user views the same album again (depends on settings for “Caching of Album Data” in the Admin / Settings Panel of the plugin being either “true” or “false”). Once a user reloads the page or closes the tab / window, all information will be removed from the memory.

There are currently three approaches to using the script (more information can be found in Section G:

  1. You can pull all albums but exclude certain albums by ID and also set a total (maximum) number of albums to be pulled from Facebook.
  2. You can pre-define albums by ID and only these specified albums will be pulled from Facebook.
  3. You can show one single album in album detail view.

In order for the script to retrieve any data from Facebook, you need to create a Facebook APP in order to generate a so-called access token, which the script will use for the setting “facebookToken”.

If you have problems with creating a Facebook APP and token, the tutorials on the following pages have proven to be helpful for others:

Create APP and Standard Token
Convert Standard Token into Extended Token

The tutorials linked to above are only meant to give you a general guide regarding the Facebook APP and token process.

When creating the access token, you ONLY need to enable the scopes “user_photos” and “user_videos”. The “public_profile” scope will be applied automatically by Facebook. No other scopes should be required for the script to work correctly.

h
h

C. Plugin Installation

Please install the plugin like you would install any other plugin in WordPress. You can either upload the extracted plugin directory directly to you server using any FTP program, or use the WordPress Plugin Installation routine:

1. In your WordPress Admin panel, click on “Plugins” -> “Add New”

2. Click on “Upload”

3.  Click on “Browse” and navigate to the folder on your harddrive where the plugin file (ZIP version) is located. Select the plugin file and click on “Open” in your popup window.

4. Click on “Install Now”

5. Wait until WordPress finishes the upload and installation process.

6. Click on “Activate Now”

If you have problems installing the plugin, follow the step by step instructions you can find here.

If you have followed all these steps correctly, the plugin should now be installed and functional. You will find a new menu item in your Admin Panel, called “FB Gallery”.

CONGRATULATIONS, because you are done with the installation!

D. License Check (Disable Demo Mode)

After installation and activation of the plugin, you will notice that the plugin is saying that it is running in “Demo Mode”. So, as a first step, you need to enter your license key in order to fully activate the plugin and to enable all Features. Without license key, the gallery remains in “Demo Mode” which is severely limited in its functionality.

In your WordPress Admin Panel, locate the new menu item “FB Gallery” and click on “License Key”. Here you can enter the license key you received from Envato at the time of purchase. Click on the image to the left if you don’t know how to retrieve your license key. Once you entered and saved your license key, the page will connect to Envato/CodeCanyon to check the license and if successful, will disable the “Demo Mode” and unlock all features.

After you entered your license key, click on one of the “Save Settings” button and the plugin will check your license. If your license check was successful, the plugin will leave the “Demo Mode” and unlock all features. You will also see a summary of your license information as shown in the example below.

E. Provide Default Facebook User ID

This plugin provides a variety of settings that allow you to style the gallery to your liking and to enable / disable certain features. In order to make it as easy as possible to use these settings, the plugin includes a full settings panel (divided in sub categories) where you can control every aspect of the gallery output.

All options have been filled with Default Values already, except the value for your Facebook User ID.

As next step, you should enter you Default Facebook User ID. This ID will be used as default value for each gallery you create, but you will be able to use different user ID’s in your galleries, if you desire to do so. You can enter your Default Facebook User ID in the first Tab “Gallery Defaults”.

After you entered and saved your Default Facebook User ID, you will notice that you will now have some additional menu items. You will now have the option to create new galleries and add custom CSS and/or JS code that will be used with your galleries.

F. Settings Panel

The plugin / script provides you with over 160 different settings. But fear not … with this WordPress Plugin, you will get a full Admin / Settings Panel where you can conveniently change any setting without having to write a single line of code. The Admin / Settings Panel is divided into multiple sub-categories in order to make it less confusing and easier to navigate.

Each option / setting will provide you with some information about what that setting / option will do. Included animated Tooltips will provide you with more detailed information. You can disable the animated Tooltips in the tab “Admin Settings”.

The plugin will do some basic checks to see if any of the settings you made contradict each other of if any required information are still missing. In these cases, a popup will inform you about the error(s) in the settings and ask you to correct them. As long as there are errors, the galleries that are shown on any of your pages might not work correctly.

Default Settings for New Galleries

Tab: Gallery Defaults

Here you will define the default settings that will be used for each new Gallery that you create. You will later have the option to change these settings for each gallery individually, but the settings you define here, will get you started.

These settings include the Default Facebook User ID, the width of the gallery (including responsive or fixed layout), the number of albums and photos to be displayed and the albums or photos you want to include or exclude.

Global Settings for All Galleries

Tab: General Settings

Here you will define settings such as the kind of information you want to show with each Album or Photo Thumbnail, the way thumbnails are generated, the Lightbox you want to use and whether the gallery should “lazy load” all images (only load imaged when they are actually in browser view).

Note:

In some cases, your website is already using some lazyload feature/plugin that is part of another plugin or your theme. That can interfere with the lazyload feature the gallery implements. If that happens, please disable the lazyload feature for the gallery. In case that doesn’t solve the problem, you should also disable the spinner animation that is shown while the background image for each thumbnails is loading.

Tab: Pagination Settings

Here you will define if and how the galleries should be paginated. You can control the album overview and detailed album view separately. You can also select which pagination controls should be available for your visitors.

Tab: Album Thumbnails

Here you can define everything that is relevant to the overall design of the album thumbnails. That includes size of the thumbnails, information that are shown along with the thumbnail, thumbnail effects and decorations and the social share feature for each album.

Tab: Photo Thumbnails

Here you can define everything that is relevant to the overall design of the photo thumbnails. That includes size of the thumbnails, information that are shown along with the thumbnail, thumbnail effects and decorations and the social share feature for each album.

Tab: Tooltip Settings

Here you can define the HTML anchor that will be used to store any Tooltip content (i.e. “title”, “alt”, etc.). If you want to utilize the included qTip2 Tooltip extension, the panel will provide you with some additional options to style and better positions these Tooltips.

You can also assign a custom Class Name to each element that contains Tooltip content. That class name can be used to target these elements in case you want to use your own Tooltip extension.

Tab: Sorting Settings

Here you will define the sorting criteria / option you will provide to your visitors. You can also select how the album and photo thumbnails should be initially sorted at the time the gallery is created.

Tab: Filter Settings

Here you will define if you want to provide your visitors with a filter and search option for your galleries.

Tab: Translation Settings

The default language for the controls and information the gallery is displaying is English. If you want to use a different language, you can translate each text block / item used in the gallery. Of course, the text content that is provided by Facebook, for example the album or photo descriptions, can not be translated by this plugin.

Tab: Extension Files

If you utilize the included extension (i.e. lightbox, tooltips, etc.), these files will automatically loaded by the plugin, but only on the pages that actually contain a gallery. By default, the CSS files will be loaded in the HEAD section of the page, while all JS files will be loaded at the end of the BODY section.

Here you can select if these extension files should be loaded by the plugin; in case you are already loading these files yourself or another plugin you are using is loading the same extension files already, you can stop this plugin from loading the same files again.

You also have the option to load the JS files in the HEAD section, instead of the BODY section, although it is recommended to load the JS file in the BODY section.

Note:

The most common file conflict you will encounter is that another plugin or your theme is also loading the Metafizy Isotope file. While that will not break the gallery, it will prevent the gallery from centering the thumbnails in the gallery container, if your page is loading the isotope file another time after it has been loaded by the gallery already.

In that case, you should disable the “Metafizzy Isotope File” but allow the gallery to load the “Metafizzy Isotope Customization File”, which will restore the custom alignment plugin that is used by the gallery.

Tab: Admin Settings

The settings provided here do not affect the galleries but control the backend of the plugin. Here you can disable / enable the Tooltips that are utilized throughout the Admin / Setting Panels, enter your Envato License Key, and control how WordPress should treat all saved settings and galleries in case you disable or uninstall the plugin.

G. Custom CSS Editor

In order to adjust the Gallery CSS to your WordPress Theme, please use the Custom CSS Editor that comes with the plugin and do not change any CSS files directly. Direct changes to the CSS file will be lost after each update but the Custom CSS entered in the editor will be stored in the WordPress Database and will remain after each update.

While entering your CSS code, you don’t have to wrap the code in <style>…</style>; the plugin will do that for you. If you do add the wrapper anyway, your CSS code will break. Also, while the editor will do some basic checking of code syntax and integrity, you are responsible for entering the CSS code correctly. The plugin will output your CSS code as follows (inserted at the end of the HEAD section):

<style> ... Your Custom CSS ... </style>

H. Custom JS Editor

The gallery includes multiple extensions that can be used to add additional features to the gallery. You can select between three different Lightboxes and and optional Tooltip extension that has multiple design options. If you want to use a different lightbox or tooltip extension, maybe in order to match the ones you are already using on your website, the plugin provides you with a Custom JS Editor to initialize these 3rd party extensions.

While entering your JS code, you don’t have to wrap the code in <script type=”text/javascript”>…</script>; the plugin will do that for you. If you do add the wrapper anyway, your JS code will break. Also, while the editor will do some basic checking of code syntax and integrity, you are responsible for entering the JS code correctly. The plugin will output the code as follows:

<script type="text/javascript">
    (function ($) { 
        ... Your Custom JS ... 
    })(jQuery); 
</script>

The plugin will automatically add the required wrapper to allow for jQuery commands, using the “$” character when you target / address elements, instead of “jQuery” (you can still use “jQuery”). The Custom JS code will be inserted in the BODY section after the code that initializes the gallery.

I. Create a New Gallery

After you added and saved your Default Facebook User ID, you will notice the new menu item “Add Gallery”, as well as some control buttons “Add New Gallery”, strategically placed throughout the Admin / Setting Panels. Clicking on any of them will open a new page, where you can create a new Gallery.

As you will notice, all the default setting you defined earlier, are already pre-set for your new Gallery, but you can change any of them, if you want to. But first, you need to provide a name for your new Gallery. Once you confirmed or changed any of the other settings, click the button “Save New Gallery”.

A popup will confirm that the new gallery has been created and after closing it, you will be taken back to the page that is listing all your existing galleries. On that page, you can change (edit) any of your galleries or delete them. You will also find the corresponding shortcodes for each gallery.

J. Embedding a Gallery in a WordPress Page

Once you successfully created a gallery, using the provided admin / settings panel, the galleries listing will provide you with a shortcode that is unique for each gallery that you created (you can create an unlimited number of galleries). Copy the shortcode of the gallery you want to use and embed it in your page at the location where you want the gallery to show.

Please have in mind that you can only show one gallery per page. If you are attempting to show more than one gallery on the same page, the plugin will show a corresponding error message.

K. Facebook API

Starting in May 2015, Facebook retired its old API 1.x, which allowed this plugin to retrieve album data without needing an access token to do so, at least for public profiles belonging to businesses or organizations.

With the change to the new API 2.x, the plugin now requires a valid access token in order to retrieve any data from Facebook, as Facebook does not fulfill uncertified data requests anymore. The access token serves as authentication.

For that reason, you need to create a Facebook APP for your account first, and use that APP to create an access token. Once you created the token, which is only valid for up to two hours, you need to convert the token into an extended token, which will last for 60 days.

Note:

Facebook Access Tokens have a maximum expiration of 60 days. That means, you will have to refresh/update the “Access Token” every two months or create a new “Access Token” in order to continue to show albums/photos from a personal profile.

FAQ’s

Does this plugin / script require me to create a Facebook App in in my Facebook Profile?

Due to the retirement of the Facebook API 1.x as of May 2015, this plugin now requires a Facebook APP and access token in order to retrieve any data from Facebook.

Will this plugin / script work for my Facebook business or organization or fan page?

Yes. The plugin / script will work for Facebook pages that are registered for a business, organization, or pages that are setup as fan pages.

Will this plugin / script work with my personal / individual Facebook page?

Due to the forced switch to the Facebook API 2.x, this plugin will now also support personal / individual Facebook profiles, since a Facebook APP and access token as now always required, no matter what type of profile data is requested from.

Can I exclude albums or predefine the albums I want to show?

Yes. The script is flexible enough to provide you with several options. You can pull all existing albums from your Facebook page, but exclude the ones you do not want by providing the ID’s of the albums to be excluded when you initialize the script.

Or, you can predefine the albums that you want to show by providing their respective ID’s when you call the script. All albums not matching these ID’s will be ignored.

Lastly, you can initialize the script in single-mode, where the contents of one specific album will be shown right away.

Can I exclude individual images within an album, while showing all other images in that album?

Yes, you can exclude individual images by providing their respective image ID’s when you initialize the script.

Will this plugin / script work with Internet Explorer 9.0 or older?

The plugin / script works correctly on my Windows XP test computer with IE9. That is not to say that some other computer setups using IE9 or less might not have problems. While I did my best to ensure compatibility with all browsers, IE9 and less is particularly challenging, so I can’t give a 100% guaranty on full functionality with such an old and outdated browser. But in general, the script should work.

Once again, thank you so much for purchasing this plugin. As I said at the beginning, I’d be glad to help you if you have any questions relating to this script. No guarantees, but I’ll do my best to assist. If you have a more general question relating to the scripts on CodeCanyon, you might consider visiting the forums and asking your question in the “Item Discussion” section.