Favoritesfor WordPress

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.

[favorite_count]

Display the total favorite count for a post.

[user_favorite_count]

Display the total favorite count for a user.

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

[clear_favorites_button]

Display a button which enables users to clear all favorites.

[post_favorites]

Display a list of users who have favorited a post.

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 & updates (categories) and side items & 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
});