menu

Simple and flexible favorite buttons for your WordPress site.

Download

Use withAny Post Type


Enable or disable favorite functionality per post type while automatically adding a favorite button before and/or after the content. Or, use the included functions to display the button anywhere in your template. Favorites is multisite compatible, and provides functions for accessing user favorites across sites.

Available forAll Users


Don’t want to hide functionality behind a login? Favorites includes an option to save anonymous users’ favorites by either Session or Cookie. Logged-In users’ favorites are also saved as user meta

Designed forDevelopers


Favorites works great out-of-the-box for beginners, but a full set of  template functions unlocks just about any sort of custom functionality developers may need. Favorites outputs the minimum amount of markup needed, putting the style and control in your hands.

Try it Out

Favorite some posts, refresh your page – favorites are available & saved.

RecipeBasic Pepperoni Pizza with Four Cheese

PostCan’t Miss Destinations this Spring

PostAnnouncing the Favorites Plugin for WordPress

RecipeEasy Homemade Macaroons

RecipeThree Layer Chocolate Brownies

PostBlueberries: Nature’s Candy

Using Favorites

Favorites is a WordPress plugin designed for end users and theme developers. It provides an easy-to-use API for adding favorite button functionality to any post type.

The plugin name is “Favorites,” but the button text is customizable. It can provide a way to save favorites, likes, bookmarks, or any other similar types of data.


Requirements

Favorites requires PHP version 5.4 or above, and WordPress version 3.8 or above. The plugin will not install on setups that do not meet the minimum requirements.


Installation

  1. Upload the favorites directory to the wp-content/plugins/ directory
  2. Activate the plugin through the Plugins menu in WordPress
  3. Visit the plugin settings to enable specific post types and specify display options.
  4. Use the template functions, display settings, or shortcodes to display the favorite button, favorite counts, and/or user favorites.

FAQs

How do I add custom formatting to the generated lists of favorites?
The generated lists are designed to be a simple “shortcut” for displaying a user’s favorites. The get_user_favorites() template function is provided for more advanced manipulation of user favorites. See this Gist for a quick example on how to use the function for formatting purposes.

Is this plugin multisite compatible?
As of version 1.1.0, Favorites is multisite compatible. The plugin API is designed for maximum flexibility while maintaining ease of use. For example, by passing a site_id parameter to the included functions, you may display user favorites across sites.

Does this work on sites with caching enabled?
Yes, although the buttons may display the incorrect state momentarily. Button states are updated via an AJAX call after page load in order to accommodate cached pages. This may be noticeable on slower servers or on pages with external resources that are slow to respond.

How do I donate to this plugin?
Monetary donations are not currently accepted. If you’d like to express appreciation, consider leaving a nice review on wordpress.org, or giving me a shout-out on Twitter.

Is this plugin available in “X” language?
The front-end components generated by this plugin are extremely minimal. The favorite button text is configurable to be any text/html combination. To submit a translation of the plugin admin, submit a Github pull request with your translation files, and it will be included in the next plugin release (pending review).


 Shortcodes

All shortcode parameters are optional. If a post ID is not provided, the current post will be used (must be inside the loop). The Site ID parameter is for use in multisite installations. By default, the current site/blog will be used.

[favorite_button post_id="" site_id=""]

Display a favorite button.

[favorite_count post_id=""]

Display the total favorite count for a post.

[user_favorite_count user_id="" site_id="" post_types=""]

Display the total favorite count for a user. Post types parameter accepts a comma-separated list of post types (names) to optionally filter by post type (by default, all post types are included).

[user_favorites user_id="" include_links="true" site_id="" post_types="" include_buttons="false"]

Display a list of the user’s favorited posts. To disable post links, set include_links to “false”. Post types parameter accepts a comma-separated list of post types (names) to optionally filter by post type (by default, all post types are included). To include favorite buttons in the generated list, set the include_buttons parameter to “true”

[clear_favorites_button site_id="" text=""]

Display a button which enables users to clear all favorites. Text parameter sets the button text. (available in 1.2.0+)

[post_favorites post_id="" site_id="" separator="list" include_anonymous="true" anonymous_label="Anonymous Users" anonymous_label_single="Anonymous User"]

Display a list of users who have favorited a post. Defaults to the current post being displayed if used inside the loop. To exclude anonymous users from being displayed, set the include_anonymous parameter to “false”. To display the list as an HTML list, set the separator parameter to “list”. Otherwise, set it to the character which separates the user names (for example, setting separator=”,” would output a comma separated string. (available in 1.2.0+)


Function Reference

The Favorite Button

The favorite button can be added automatically to the beginning and/or end of the post content. To add the button manually, disable the content filtering in the plugin options and use one of the following functions:


/**
* Get the favorite button for a specified post
* Post ID not required if inside the loop
* @param $post_id int, defaults to current post
* @param $site_id int, defaults to current blog/site
*/
get_favorites_button($post_id, $site_id);

/**
* Echo the favorite button for a specified post
* Post ID not required if inside the loop
* @param $post_id int, defaults to current post
* @param $site_id int, defaults to current blog/site
*/ 
the_favorites_button($post_id, $site_id);

 

Total Favorite Count for a Post

Each time a user favorites or unfavorites a post, the post’s favorite count is updated. To get or display the favorite count, use one of the following template functions. By default, all users’ favorites are included in the total. To remove anonymous users favorites from the total, update the appropriate plugin setting.


/**
* Get the total favorite count for a post
* Post ID not required if inside the loop
* @param int $post_id
*/
get_favorites_count($post_id);

/**
* Echo the total favorite count for a post
* Post ID not required if inside the loop
* @param int $post_id
*/
the_favorites_count($post_id);

 

Total Favorite Count for a User

Displays the total number of favorites a user has favorited. Template functions accept the same filters parameter as the user favorites functions. Defaults to the current user.


/**
* Get the number of posts a specific user has favorited
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $filters array of post types/taxonomies
* @param $html boolean, whether to output html (important for AJAX updates). If false, an integer is returned
* @return int
*/
get_user_favorites_count($user_id = null, $site_id = null, $filters = null, $html = false);

/**
* Print the number of posts a specific user has favorited
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $filters array of post types/taxonomies
* @return html
*/
the_user_favorites_count($user_id = null, $site_id = null, $filters = null);

User Favorites

The following functions may be used to get or display posts favorited by a specific user. If a user ID is not provided, the current user will be used. Functions are available for retrieving an array of post IDs or a formatted HTML list of post titles/links.


/**
* Get an array of User Favorites
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $filters array of post types/taxonomies
* @return array
*/
get_user_favorites($user_id = null, $site_id = null, $filters = null);

/**
* HTML List of User Favorites
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $filters array of post types/taxonomies
* @return html
*/
get_user_favorites_list($user_id = null, $site_id = null, $include_links = false, $filters = null);

/**
* Echo HTML List of User Favorites
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $filters array of post types/taxonomies
* @return html
*/
the_user_favorites_list($user_id = null, $site_id = null, $include_links = false, $filters = null);

Users Who Have Favorited a Post

The following functions may be used to get or display users who have favorited a specific post. If a post ID is not provided, the current post will be used (if inside the loop).


/**
* Get an array of users who have favorited a post
* @param $post_id int, defaults to current post
* @param $site_id int, defaults to current blog/site
* @return array of user objects
*/
get_users_who_favorited_post($post_id = null, $site_id = null);

/**
* Print a list of users who favorited a post
* @param $post_id int, defaults to current post
* @param $site_id int, defaults to current blog/site
* @param $separator string, custom separator between items (defaults to HTML list)
* @param $include_anonymous boolean, whether to include anonymous users
* @param $anonymous_label string, label for anonymous user count
* @param $anonymous_label_single string, singular label for anonymous user count
*/
the_users_who_favorited_post($post_id = null, $site_id = null, $separator = 'list', $include_anonymous = true, $anonymous_label = 'Anonymous Users', $anonymous_label_single = 'Anonymous User');

Clear Favorites Button

The following functions may be used to get or display a button which allows users to clear all of their favorites.


/**
* Get the clear favorites button
* @param $site_id int, defaults to current blog/site
* @param $text string, button text - defaults to site setting
* @return html
*/
get_clear_favorites_button($site_id = null, $text = null);

/**
* Print the clear favorites button
* @param $site_id int, defaults to current blog/site
* @param $text string, button text - defaults to site setting
* @return html
*/
the_clear_favorites_button($site_id = null, $text = null);

Using the Filters Parameter

To filter favorite lists or counts by post type and/or terms, the filters parameter is provided. The filters parameter accepts an array, which may contain an array of post types, and an array of terms/taxonomies. In the below example, only posts with the post type of “post” and “recipe”, with terms of news & updates (categories) and side items & desserts (recipe types) will be returned.


$filters = array(
  'post_type' => array(
    'post', 
    'recipe'
  ),
  'terms' => array(
    'category' => array(
      'news', 
      'updates'
    ),
    'recipe-type' => array(
      'side-item',
      'dessert'
    )
  )
);
the_user_favorites_list($user_id = null, $site_id = null, $include_links = true, $filters = $filters);

Hooks

Change the Loading Indicator Image

Two hooks are provided to customize the optional loading indicator image. In the following example, the image is replaced with an image in our theme for both the favorited (active) and normal button state. This may be helpful if your “favorited” state has a different color/background.


/**
* Change the Simple Favorites loading indicator
*/
add_filter( 'simplefavorites_spinner_url', 'custom_favorites_loader' );
function custom_favorites_loader($src){
	return get_stylesheet_directory_uri() . '/assets/images/loading-small-purple.gif';
}

add_filter( 'simplefavorites_spinner_url_active', 'custom_favorites_loader_active' );
function custom_favorites_loader_active($src){
	return get_stylesheet_directory_uri() . '/assets/images/loading-small-green.gif';
}



Filter the list of users who have favorited a post

The filter returns the output. The array of user objects and anonymous count are available as parameters. See a more complete usage example.


add_filter('simplefavorites_user_list', 'filter_favorites_user_list', 10, 3);
function filter_favorites_user_list($output, $users, $anonymous_count)
{
return $output;
}



 

Javascript Functions

 

Callback Functions

To use the callback functions in your theme’s scripts, the simple locator script handle must be added as a dependency when enqueueing your script. The Simple Locator script handle is simple-favorites. See the WordPress Codex for more information about properly enqueuing scripts.


/**
* Fires after a favorite button has been submitted
* @param favorites - Array of post objects the user has favorited
*/
function favorites_after_button_submit(favorites){}

/**
* Fires after the page has initially loaded
* @param favorites - Array of post objects the user has favorited
*/
function favorites_after_initial_load(favorites){}

 

Options

General Settings

Plugin CSS & Javascript may be disabled. Please note, the included Javascript is required for plugin functionality. If you are combining and minifying your scripts, you may copy and paste the provided scripts. Also note, the scripts use the following global variables for localization:

  • simple_favorites.favorite (Favorite Button Text)
  • simple_favorites.favorited (Favorited Button Text)

If you are combining and minifying your scripts, these global variables must be available.

User Settings

By default, buttons are displayed for all users. Anonymous users’ favorites may be saved in either browser cookies or in the session. Logged-in users’ favorites are saved as a custom user meta field.

To exclude anonymous users’ favorites from the total favorite count for posts, deselect the option. Note: This option is not backwards compatible. Favorite counts are stored as a simple integer, and are not saved on a per-user basis.

Display Options

Post Types
Favorite buttons may be added using the template functions, or automatically by post type. To enable and insert buttons for a specific post type, select the post type, and select the area where the button should appear (before and/or after the content). The total favorite count can be optionally displayed on the post entry screen for the specified post type.

Button Text
Customized button text may include html characters for formatting. The (Favorited) text represents the “active” button state, once a user has favorited a post.

Favorite Count
Displays the total number of favorites a post has received inside the button

Loading Indication
Displays the button in a “loading” state during page load and during button submission (helpful for slower sites with cache enabled).

Loading Text: Text displays during loading state
Loading Image: Display a “spinner” loading gif during the loading state (see function reference for use filters to alter the image)

No Favorites Text
Text to display in generated lists when user has no favorites.