menu

Favoritesfor WordPress

Developer-friendly favorites for your WordPress site.

Favorite any 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.

Designed for Devs.

Favorites works out-of-the-box for beginners, but its API unlocks just about any custom functionality a developer needs. Favorites uses the minimum amount of markup needed, putting the style and control in your hands. No theme-specific CSS muddying up your pixel-perfect design.

No Login? No Problem.

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.

Try it Out.

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

Getting Started

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?
As of version 2.1.0, the list may be customized through the plugin settings.

  • Visit Settings > Favorites > Display & Post Types, and scroll to the “Listing Display” header.
  • Check the “Customize the favorites list HTML” and click the “Settings” button. Here, the list wrapper HTML element type and individual listing HTML element type may be customized. Custom CSS classes may be added to elements as well.
  • To edit the content displayed in the listings, select the “Customize Content” checkbox. A WordPress editor field will display, which represents a single listing. To add dynamic post fields, select the fields from the list above and click “add.” To add a custom field, include the field key, surrounded by brackets. Only single variable custom fields are supported (not arrays).

How do I include the post thumbnail in the favorites list?
As of version 2, the thumbnail may be included by setting the shortcode parameter in the [user_favorites] shortcode: include_thumbnails=”true”. To display a size other than “thumbnail/small”, include a size parameter: thumbnail_size=”large”. Additionally, the listing content may be fully customized using the steps outlined in the above answer.

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.

Some servers use very aggressive caching methods. If anonymous user favoriting is enabled, and favorites are not saving, this may be due to the host caching cookies. You may need to request that they disable caching on the simplefavorites cookie. If you have chosen ‘session’ as the save type, and favorites are not saving, the host may have sessions disabled on the server. In this case, cookies may be required for anonymous users.

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

I want to display the favorite buttons, but not let unauthenticated users favorite items. How do I do that?
As of version 2.1, there is an option to prevent unauthenticated users from favoriting posts while showing them a modal alert:

  • Visit Settings > Favorites > Users
  • Uncheck “Enable Anonymous Users”
  • Check “Require Login & Show Modal to Anonymous Users”
  • Customize the modal content to display. The content is also filterable.

How do I change the star icon to a hear in the button?
Version 2 offers several methods of customizing the button:

Option 1: Custom Markup

  • Visit Settings > Favorites > Display & Post Types
  • Under “Button Type,” choose “Custom Markup.”
  • Include the markup specific to your theme in the provided Text/HTML inputs. Colors may also be specified (these will override theme colors).

Option 2: Use a Preformatted Button

  • Visit Settings > Favorites > Display & Post Types
  • Under “Button Type,” choose a different type of button. A preview will display. Colors may also be specified (these will override theme colors).

Option 3: Use a Filter

  • Filters are available for the button html. If a preformatted button is selected, additional filters are available for each of the button elements.

My site is hosted on WP Engine. Favorites aren’t saving. What do I do?
WP Engine disables PHP sessions, so anonymous users must be saved via cookies. WP Engine also caches cookies, so you’ll need to contact their tech support and ask to have the cookie simplefavorites removed from caching. If favorites are still not saving, the server may be forcing admin-ajax to load via HTTPS, even if an SSL has not been installed. If this is the case, save a file named ‘x_disable_wpesec.php’ in the /mu-plugins directory with the following:

<?php
add_action( 'widgets_init', 'wpe_remove_encourage_tls', 0 );
function wpe_remove_encourage_tls() {
remove_action( 'init', 'wpesec_encourage_tls' );
}

Shortcodes

[favorite_button]

Display a favorite button.

ParameterTypeUseExample
post_idInteger

Specify a post to show. Defaults to the current post (inside the loop)

post_id=”1″
site_idInteger

Specify a site ID if used in a multisite installation. Defaults to the current site/blog

site_id=”1″

[favorite_count]

Display the total favorite count for a post.

ParameterTypeUseExample
post_idInteger

Specify the post for which to display the total favorite count

post_id=”1″

[user_favorite_count]

Display the total favorite count for a user.

ParameterTypeUseExample
user_idInteger

Specify the user who’s favorites are to be displayed.

user_id=”1″
site_idInteger

Specify a site ID if used in a multisite installation. Defaults to the current site/blog.

site_id=”1″
post_typesComma-Separated List

Specify the post types to include in the count. Defaults to all post types.

post_types=”post,recipe”

[user_favorites]

Display a list of the user’s favorited posts.

Important: If the “Customize Single Listing Content Markup” option is selected under the plugin settings, the content options set in shortcodes will be overridden with the customized markup.

ParameterTypeUseExample
user_idInteger

Specify the user who’s favorites are to be displayed.

user_id=”1″
site_idInteger

Specify a site ID if used in a multisite installation. Defaults to the current site/blog.

site_id="1"
include_linksBoolean

Whether to include the permalink in the title. Defaults to false.

include_links=”true”
include_buttonsBoolean

Whether to include the favorite button in the listings. Defaults to false.

include_buttons=”true”
include_thumbnailsBoolean

Whether to include the post thumbnail in the listings. Defaults to false.

include_thumbnails=”true”
thumbnail_sizeString

The thumbnail size to display. The include_thumbnails parameter must be set to true. Defaults to “thumbnail,” but may be any size supported by the theme.

thumbnail_size=”large”
include_excerptsBoolean

Whether to include the post excerpt in the listings. Defaults to false.

include_excerpts=”true”

[clear_favorites_button]

Display a button which enables users to clear all favorites.

ParameterTypeUseExample
site_idInteger

Specify a site ID if used in a multisite installation. Defaults to the current site/blog.

site_id=”1″
textString

Set the button text. Overrides the “Clear Favorites Button Text” plugin setting. Defaults to “Clear Favorites.”

text=”Clear Favorites”

[post_favorites]

Display a list of users who have favorited a post.

ParameterTypeUseExample
post_idInteger

Specify a post to show. Defaults to the current post (inside the loop)

post_id=”1″
site_idInteger

Specify a site ID if used in a multisite installation. Defaults to the current site/blog

site_id=”1″
separatorString

To display as an HTML list, set the separator parameter to “list” (default), otherwise, include a character to separate items.

separator=”,”
include_anonymousBoolean

Whether to include anonymous users who have favorited the post. Defaults to true.

include_anonymous=”true”
anonymous_labelString

The label for plural anonymous users. Displays if more than one anonymous user has favorited the post and include_anonymous is set to true. Defaults to “Anonymous Users”.

anonymous_label=”Anonymous Users”
anonymous_label_singleString

The label for a single anonymous user. Displays if only one anonymous user has favorited the post and include_anonymous is set to true. Defaults to “Anonymous User”.

anonymous_label_single=”Anonymous User”

Functions

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
* @param int $site_id - defaults to current site
*/
get_favorites_count($post_id, $site_id);

/**
* Echo the total favorite count for a post
* Post ID not required if inside the loop
* @param int $post_id
* @param int $site_id - defaults to current site
*/
the_favorites_count($post_id, $site_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);

 

Total Favorite Count for a Site

Displays the total number of favorites across an entire site. Includes all users, anonymous and authenticated.

/**
* Get the total number of favorites, for all posts and users
* @param $site_id int, defaults to current blog/site
* @return html
*/
get_total_favorites_count($site_id = null);


/**
* Print the total number of favorites, for all posts and users
* @param $site_id int, defaults to current blog/site
* @return html
*/
the_total_favorites_count($site_id = null);

 

User Favorite

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 $include_links bool, whether to wrap the post title with the permalink
* @param $filters array of post types/taxonomies
* @param $include_button boolean, whether to include the favorite button for each item
* @param $include_thumbnails boolean, whether to include the thumbnail for each item
* @param $thumbnail_size string, the thumbnail size to display
* @param $include_excerpt boolean, whether to include the excerpt for each item
* @return html
*/
get_user_favorites_list($user_id = null, $site_id = null, $include_links = false, $filters = null, $include_button = false, $include_thumbnails=false, $thumbnail_size='thumbnail', $include_excerpt=false);

/**
* Echo HTML List of User Favorites
* @param $user_id int, defaults to current user
* @param $site_id int, defaults to current blog/site
* @param $include_links bool, whether to wrap the post title with the permalink
* @param $filters array of post types/taxonomies
* @param $include_button boolean, whether to include the favorite button for each item
* @param $include_thumbnails boolean, whether to include the thumbnail for each item
* @param $thumbnail_size string, the thumbnail size to display
* @param $include_excerpt boolean, whether to include the excerpt for each item
* @return html
*/
the_user_favorites_list($user_id = null, $site_id = null, $include_links = false, $filters = null, $include_button = false, $include_thumbnails = false, $thumbnail_size = 'thumbnail', $include_excerpt = false);

 

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 &amp; updates (categories) and side items &amp; desserts (recipe types) will be returned.

$filters = array(
  'post_type' => array(
    'post', 
    'recipe'
  ),
  'status' => array(
    'publish', 
    'future'
  ),
  '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);

Filters

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 Favorites loading indicator Image
*/
add_filter( 'favorites/button/loading/image_url', 'custom_favorites_loader_image' );
function custom_favorites_loader_image($src)
{
	return get_stylesheet_directory_uri() . '/assets/images/loading-small-purple.gif';
}

add_filter( 'favorites/button/loading/image_url_active', 'custom_favorites_loader_image_active' );
function custom_favorites_loader_image_active($src)
{
	return get_stylesheet_directory_uri() . '/assets/images/loading-small-green.gif';
}


 

Change the Loading Indicator HTML

If the “CSS Spinner” option is selected under “Loading Indication” (Settings > Favorites > Display), the spinner html filter is available for altering the output. This is returned as html.

/**
* Change the Favorites loading indicator
*/
add_filter( 'favorites/button/loading/html', 'custom_favorites_html_loader' );
function custom_favorites_html_loader($html)
{
	return $html;
}

add_filter( 'favorites/button/loading/html_active', 'custom_favorites_html_loader_active' );
function custom_favorites_html_loader_active($html)
{
	return $html;
}


 

Change the Authentication Gate Modal Content

If the “Require Login & Show Modal to Anonymous Users” option is selected under the plugin settings (User Tab), this filter may be used to alter the output of the modal. This overrides custom modal content saved under the plugin settings.

/**
* Change the Favorites Authentication Modal Content
*/
add_filter( 'favorites/authentication_modal_content', 'custom_favorites_auth_content' );
function custom_favorites_auth_content($html)
{
	return $html;
}

 

Change the Preset Button Properties

If a preset button has been selected under the plugin settings (Display & Post Types Tab), the following filters are available.

/**
* Change the Favorites Preset Button Icon
*/
add_filter( 'favorites/button/icon', 'custom_favorites_button_icon' );
function custom_favorites_button_icon($html)
{
	return $html;
}

/**
* Change the Favorites Preset Button Icon Class
*/
add_filter( 'favorites/button/icon-class', 'custom_favorites_button_icon_class' );
function custom_favorites_button_icon_class($string)
{
	return $string;
}

/**
* Change the Favorites Preset Button HTML (Unfavorited)
*/
add_filter( 'favorites/button/text/default', 'custom_favorites_button_html' );
function custom_favorites_button_html($html)
{
	return $html;
}

/**
* Change the Favorites Preset Button HTML (Favorited)
*/
add_filter( 'favorites/button/text/active', 'custom_favorites_button_html_active' );
function custom_favorites_button_html_active($html)
{
	return $html;
}

 

Customize the Button CSS Classes

/**
* Customize the Favorites Button CSS Classes
*/
add_filter( 'favorites/button/css_classes', 'custom_favorites_button_css_classes', 10, 3 );
function custom_favorites_button_css_classes($classes, $post_id, $site_id)
{
	return $classes;
}

 

Customize the Button HTML

/**
* Customize the Favorites Button HTML
*/
add_filter( 'favorites/button/html', 'custom_favorites_button_html', 10, 4 );
function custom_favorites_button_html($html, $post_id, $favorited, $site_id)
{
	return $html;
}

 

Customize the Thumbnail Displayed in a Favorites List Item

/**
* Customize the Favorites List Thumbnail
*/
add_filter( 'favorites/list/thumbnail', 'custom_favorites_list_thumbnail', 10, 3 );
function custom_favorites_list_thumbnail($image_element, $post_id, $size)
{
	return $image_element;
}

 

Customize the Favorites Listing HTML

/**
* Customize the Favorites Listing HTML
*/
add_filter( 'favorites/list/listing/html', 'custom_favorites_listing_html', 10, 4 );
function custom_favorites_listing_html($html, $markup_template, $post_id, $list_options)
{
	return $html;
}

 

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 Events

Events

The callback functions from version 1 have been replaced with events. Various parameters are passed for use.

/**
* favorites-updated-single
* Fires after a favorite button has been submitted successfully
* @param favorites - Array of post objects the user has favorited
* @param post_id - The post ID that was updated
* @param site_id - The site ID for the post that was updated (for multisite)
* @param status - Whether the button was active or inactive
*/
$(document).on('favorites-updated-single', function(event, favorites, post_id, site_id, status){
  // Do stuff here as needed
});

/**
* favorites-user-favorites-loaded
* Fires after the user's favorites have loaded
* @param favorites - Array of post objects the user has favorited
* @param intial_load - Boolean 
*/
$(document).on('favorites-user-favorites-loaded', function(event, favorites, intial_load){
  // Do stuff here as needed
});

/**
* favorites-nonce-generated
* Fires after the form nonce has been generated and saved (for cached pages)
* @param nonce - The form nonce
*/
$(document).on('favorites-nonce-generated', function(event, nonce){
  // Do stuff here as needed
}); 

/**
* favorites-cleared
* Fires after all favorites have been cleared
* @param button - The active clear button
*/
$(document).on('favorites-cleared', function(event, button){
  // Do stuff here as needed
}); 

Options

General Settings

Page Cache

If page cache is enabled, whether through a plugin or through your host, this should be checked. If page cacheing is not enabled, deselecting this option may improve performance.

Dependencies

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:

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

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

Favorites General Settings

User SettingsFavorites User Settings

Anonymous Users

To display buttons for anonymous users, this option should be checked.

Include in the Post Count

If anonymous users are enabled, this option displays. To exclude anonymous users’ favorites from the total favorite count for posts, deselect the option.

Note: Anonymous user options are not backwards compatible. Favorite counts are stored as a simple integer, and are not saved on a per-user basis.

Require Login to Favorite

Displays if anonymous users are disabled. If this option is selected, favorite buttons will still be displayed for unauthenticated users. If the user attempts to favorite a post, a modal window displays with messaging which may be set here.

Save Unauthenticated User Favorites as

If favorites are enabled for anonymous users, an option displays allowing their favorites to be saved in either a browser cookie or session.

Display Options: Post Types

Post Types

Favorites may be enabled for all post types.

Insert Favorite button before content

Automatically inserts the favorite button before the content, using the_content filter.

Insert Favorite button after content

Automatically inserts the favorite button after the content, using the_content filter.

Show favorite count on post edit screen

Adds a meta box on the post edit/update screen with the total number of favorites the post has received.

Show favorite count in admin columns

Adds an admin column with the total number of favorites the post has received.

Favorite Button Content (Custom Markup)Favorites Settings 3

Button Type

To display custom markup in the favorite button, select this option.

Color Options

Color options override theme css. Color option specifics are covered below.

Button Markup: Unfavorited

The HTML to display in the button in an unfavorited state.

Button Markup: Favorited

The HTML to display in the button in a favorited state.

Include Total Favorite Count

Check to include the total number of times the post has been favorited in the button text.

Button Color Options

Favorites Button Customization

Button Types

If custom markup is not your thing, your choice of predefined button types are available.

Color Options

To override theme styles and inject custom colors in buttons, select the “Specify custom colors” checkbox. A list of color options are available for the button in favorited and unfavorited states.

Loading Indication

Favorites 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/HTML

Replaces the button text during the loading state

Loading Spinner

The loading spinner may display as an image/GIF or as an HTML icon using CSS animations. Filters are available depending on the choice. If none are selected, a spinner will not display but the loading text will.

Page Load

Adds the loading state to the favorite buttons during page load (helpful on sites with page cacheing enabled).

Listing Display

Favorites Listing Display

List Wrapper Element

List Wrapper Type: Choose an HTML element type for the wrapping list. Defaults to a <ul> element.

List Wrapper CSS: Add custom CSS classes to the list wrapper element.

Single List Element

Listing Element Type: Choose an HTML element type for the individual listings. Defaults to a <li> element.

Listing CSS: Add custom CSS classes to the listing elements.

Single Listing Markup

To customize the markup in each favorite listing within the list, select this option. Dynamic fields may be added to the listing by selecting them from the dropdowns and selecting “Add.” To add custom meta fields to the output, use the format [[custom_field:custom_field_name]]. Array fields like ACF relationships are not supported. The markup is also available through a filter if more advanced options are required.

Additional Display Settings

Favorites Additional Display Settings

Clear Favorites Button Text

The default text to appear in “Clear Favorites” buttons generated by either the shortcode or API function.

No Favorites Text

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

Favorites for WordPress is created and maintained by Kyle Phillips.

Crafted with pride in WordPress. ©2017