Skip to content

2. Template tags

Jump to bottom
Héctor Cabrera edited this page Jul 8, 2024 · 27 revisions

Template tags are custom WPP functions that can be integrated anywhere in your theme.

wpp_get_mostpopular()

With the wpp_get_mostpopular() template tag you can embed the most popular posts of your blog into your site's sidebar (or anywhere else) without using a widget.

Usage:

If you don't pass any parameters to the function, wpp_get_mostpopular() will list the most viewed posts (up to 10) from the last 24 hours:

<?php
if ( function_exists('wpp_get_mostpopular') ) {
    wpp_get_mostpopular();
}
?>

Let's say that you want to display the 5 most commented posts from the last 7 days. In that case, we'll need to pass some specific parameters to the function:

<?php
if ( function_exists('wpp_get_mostpopular') ) {
    /* Get up to the top 5 commented posts from the last 7 days */
    wpp_get_mostpopular(array(
        'limit' => 5,
        'range' => 'last7days',
        'order_by' => 'comments'
    ));
}
?>

Please check below for a complete list of parameters.

Parameters

Parameter What it does Possible values Defaults to Example
ajaxify Enables / disables AJAX loading 1 (enable), 0 (disable) 1 With wpp_get_mostpopular():

<?php
$args = array(
  'ajaxify' => 0
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp ajaxify=0]
header Sets a heading for the list Text string None With wpp_get_mostpopular():

<?php
$args = array(
  'header' => 'Popular Posts'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp header='Popular Posts']
header_start Sets the opening tag for the heading of the list Text string <h2> With wpp_get_mostpopular():

<?php
$args = array(
  'header' => 'Popular Posts',
  'header_start' => '<h3>',
  'header_end' => '</h3>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp header='Popular Posts' header_start='<h3>' header_end='</h3>']
header_end Sets the closing tag for the heading of the list Text string </h2> With wpp_get_mostpopular():

<?php
$args = array(
  'header' => 'Popular Posts',
  'header_start' => '<h3>',
  'header_end' => '</h3>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp header='Popular Posts' header_start='<h3>' header_end='</h3>']
limit Sets the maximum number of popular posts to be shown on the listing Positive integer 10 With wpp_get_mostpopular():

<?php
$args = array(
  'limit' => 3
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp limit=3]
range Tells WordPress Popular Posts to retrieve the most popular entries within the time range specified by you last24hours, last7days, last30days, all, custom last24hours With wpp_get_mostpopular():

<?php
$args = array(
  'range' => 'last7days'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp range='last7days']
time_quantity Specifies the number of time units of the custom time range Positive integer 24 With wpp_get_mostpopular():

<?php
$args = array(
  'range' => 'custom',
  'time_quantity' => 1,
  'time_unit' => 'hour'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp range='custom' time_quantity=1 time_unit='hour']
time_unit Specifies the time unit of the custom time range minute, hour, day, week, month hour With wpp_get_mostpopular():

<?php
$args = array(
  'range' => 'custom',
  'time_quantity' => 1,
  'time_unit' => 'hour'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp range='custom' time_quantity=1 time_unit='hour']
freshness Tells WordPress Popular Posts to retrieve the most popular entries published within the time range specified by you 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'range' => 'last7days',
  'freshness' => 1
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp range='last7days' freshness=1]
order_by Sets the sorting option of the popular posts comments, views, avg (for average views per day) views With wpp_get_mostpopular():

<?php
$args = array(
  'order_by' => 'comments'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp order_by='comments']
post_type Defines the type of posts to show on the listing Text string post With wpp_get_mostpopular():

<?php
$args = array(
  'post_type' => 'post, page, my-custom-post-type'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp post_type='post, page, my-custom-post-type']
pid If set WordPress Popular Posts will exclude the specified post(s) ID(s) from the listing. Text string None With wpp_get_mostpopular():

$args = array(
  'pid' => '60, 25, 31'
);
wpp_get_mostpopular($args); ?>

With the [wpp] shortcode:

[wpp pid='60, 25, 31']
cat If set WordPress Popular Posts will retrieve all entries that belong to the specified category ID(s). If a minus sign is used entries associated to the category will be excluded instead. text string None With wpp_get_mostpopular():

<?php
$args = array(
  'cat' => '1, 55, -74'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp cat='1, 55, -74']
taxonomy If set WordPress Popular Posts will filter posts by a given taxonomy(ies). If you want to filter by multiple taxonomies use a semicolon (;) to separate multiple taxonomies and their term IDs. Text string None With wpp_get_mostpopular():

<?php
$args = array(
  'taxonomy' => 'post_tag',
  'term_id' => '118, 75, 15'
);
wpp_get_mostpopular($args);
?>

<?php
$args = array(
  'taxonomy' => 'category; post_tag',
  'term_id' => '1, 55, -74; 118, 75, 15'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp taxonomy='post_tag' term_id='118, 75, 15']

[wpp taxonomy='category; post_tag' term_id='1, 55, -74; 118, 75, 15']
term_id If set WordPress Popular Posts will retrieve all entries that belong to the specified term ID(s). If a minus sign is used, entries associated to the term(s) will be excluded instead. Text string None With wpp_get_mostpopular():

<?php
$args = array(
  'taxonomy' => 'category',
  'term_id' => '1, 55, -74'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp taxonomy='category' term_id='1, 55, -74']
author If set WordPress Popular Posts will retrieve all entries created by the specified author ID(s). Text string None With wpp_get_mostpopular():

<?php
$args = array(
  'author' => '1, 7'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp author='1, 7']
title_length If set WordPress Popular Posts will limit the length of post titles to up to N characters Positive integer 25 With wpp_get_mostpopular():

<?php
$args = array(
  'title_length' => 35
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp title_length=35]
title_by_words If set to 1 WordPress Popular Posts will limit the length of post titles to up to N words (instead of characters) 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'title_length' => 10,
  'title_by_words' => 1
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp title_length=10 title_by_words=1]
excerpt_length If set WordPress Popular Posts will display an excerpt of up to N characters Positive integer 0 With wpp_get_mostpopular():

<?php
$args = array(
  'excerpt_length' => 55,
  'post_html' => '<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp excerpt_length=55 post_html='<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>']
excerpt_by_words If set to 1 WordPress Popular Posts will shorten the excerpt to N words (instead of characters) 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'excerpt_length' => 25,
  'excerpt_by_words' => 1,
  'post_html' => '<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp excerpt_length=25 excerpt_by_words=1 post_html='<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>']
excerpt_format If set WordPress Popular Posts will maintaing all styling tags (strong, italic, etc) and hyperlinks found in the excerpt 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'excerpt_length' => 55,
  'excerpt_format' => 1,
  'post_html' => '<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp excerpt_length=55 excerpt_format=1 post_html='<li>{title} <div class="wpp-excerpt">{excerpt}</div></li>']
thumbnail_width If set, and if your current server configuration allows it, you will be able to display thumbnails of your posts. This attribute sets the width of your thumbnails. Positive integer 0 With wpp_get_mostpopular():

<?php
$args = array(
  'thumbnail_width' => 100,
  'thumbnail_height' => 75
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp thumbnail_width=100 thumbnail_height=75]
thumbnail_height If set, and if your current server configuration allows it, you will be able to display thumbnails of your posts. This attribute sets the height of your thumbnails. Positive integer 0 With wpp_get_mostpopular():

<?php
$args = array(
  'thumbnail_width' => 100,
  'thumbnail_height' => 75
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp thumbnail_width=100 thumbnail_height=75]
rating If set, and if the WP-PostRatings plugin is installed and enabled on your blog, WordPress Popular Posts will show how your visitors are rating your entries 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'rating' => 1,
  'post_html' => '<li>{title} <div class="wpp-rating">{rating}</div></li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp rating=1 post_html='<li>{title} <div class="wpp-rating">{rating}</div></li>']
stats_comments If set WordPress Popular Posts will show how many comments each popular post received within the specified time range 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'stats_comments' => 1
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_comments=1]
stats_views If set WordPress Popular Posts will show how many views each popular post received within the specified time range 1 (true), 0 (false) 1 With wpp_get_mostpopular():

<?php
$args = array(
  'stats_views' => 0
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_views=0]
stats_author If set WordPress Popular Posts will display the author's name under each post 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'stats_author' => 1
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_author=1]
stats_date If set WordPress Popular Posts will display the publish date of each post 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'stats_date' => 1
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_date=1]
stats_date_format Sets the date format Text string 'F j, Y' With wpp_get_mostpopular():

<?php
$args = array(
  'stats_date' => 1,
  'stats_date_format' => 'Y-m-d'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_date=1 stats_date_format='Y-m-d']
stats_category If set WordPress Popular Posts will display the categories associated to each entry 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'stats_category' => 1,
  'post_html' => '<li>{title} {category}</li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp stats_category=1 post_html='<li>{title} {category}</li>']
stats_taxonomy If set WordPress Popular Posts will display the taxonomies associated to each entry 1 (true), 0 (false) 0 With wpp_get_mostpopular():

<?php
$args = array(
  'taxonomy' => 'post_tag',
  'stats_taxonomy' => 1,
  'post_html' => '<li>{title} {taxonomy}</li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp taxonomy='post_tag' stats_taxonomy=1 post_html='<li>{title} {taxonomy}</li>']
wpp_start Sets the opening tag for the listing Text string <ul> With wpp_get_mostpopular():

<?php
$args = array(
  'wpp_start' => '<ol>',
  'wpp_end' => '</ol>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp wpp_start='<ol>' wpp_end='</ol>']
wpp_end Sets the closing tag for the listing Text string </ul> With wpp_get_mostpopular():

<?php
$args = array(
  'wpp_start' => '<div>',
  'wpp_end' => '</div>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp wpp_start='<div>' wpp_end='</div>']
post_html Sets the HTML structure of each post Text string, custom HTML (see Content Tags) <li>{thumb} {title} <span class="wpp-meta post-stats">{stats}</span></li> With wpp_get_mostpopular():

<?php
$args = array(
  'thumbnail_width' => 100,
  'thumbnail_height' => 75,
  'post_html' => '<li>{thumb} <a href="{url}">{text_title}</a></li>'
);
wpp_get_mostpopular($args);
?>

With the [wpp] shortcode:

[wpp thumbnail_width=100 thumbnail_height=75 post_html='<li>{thumb} <a href="{url}">{text_title}</a></li>']

Content Tags

Content Tags are a WordPress Popular Posts exclusive feature. These Content Tags, like {url}, {thumb_img}, etc. are pretty much WPP's own "shortcodes": the plugin will replace these tags with actual content when rendering the popular posts list on the screen.

These are the ones that are currently included with the plugin (you can create your own Content Tags too by the way):

  • {author_copy}: returns linked author name with copy text (eg. by Hector Cabrera), requires stats_author to be 1.
  • {author}: returns linked author name (eg. Hector Cabrera), requires stats_author to be 1.
  • {category_copy}: returns linked category name(s) with copy text (eg. under WordPress), requires stats_category to be 1.
  • {category}: returns linked category name(s) (eg. WordPress), requires stats_category to be 1.
  • {comments_copy}: returns comments count with copy text (eg. 22 comments), requires stats_comments to be 1.
  • {comments}: returns comments count only, without text (eg. 22), requires stats_comments to be 1.
  • {current_class}: adds the CSS class current to the posts that's currently being visited (if any).
  • {date_copy}: returns post/page date with copy text (eg. posted on November 24, 2022), requires stats_date to be 1.
  • {date}: returns post/page date (eg. November 24, 2022), requires stats_date to be 1.
  • {excerpt} (or {summary}): returns the post/page excerpt, and requires excerpt_length to be greater than 0.
  • {item_position}: outputs the position of the post in the listing.
  • {pid}: returns the post/page ID.
  • {rating}: returns post/page current rating, and requires WP-PostRatings to be installed and enabled.
  • {score}: returns post/page current rating as an integer, requires WP-PostRatings to be installed and enabled.
  • {stats}: returns the default stats tags.
  • {taxonomy_copy}: returns linked taxonomy name(s) with copy, requires stats_taxonomy to be 1.
  • {taxonomy}: returns linked taxonomy name(s), requires stats_taxonomy to be 1.
  • {text_title}: returns the post/page title text.
  • {thumb_img}: returns thumbnail image without linking to post/page, requires using the thumbnail_width and thumbnail_height parameters.
  • {thumb_url}: returns thumbnail's URL, requires using the thumbnail_width and thumbnail_height parameters.
  • {thumb}: returns thumbnail linked to post/page, requires using the thumbnail_width and thumbnail_height parameters.
  • {title_attr}: similar to text_title but sanitized for use in title/alt attributes.
  • {title}: returns linked post/page title.
  • {total_items}: outputs number of popular posts found.
  • {url}: returns the URL of the post/page.
  • {views_copy}: returns views count with copy text (eg. 782 views), requires stats_views to be 1.
  • {views}: returns views count only, without text (eg. 782), and requires stats_views to be 1.

wpp_get_views()

The wpp_get_views() template tag returns the views count of a single post / page / Custom Post Type (eg. book).

It accepts four parameters:

  • Post / Page / Custom Post Type ID (integer, required).
  • Time range (string/array, optional). If time range isn't provided, wpp_get_views() will retrieve the total amount of views. Otherwise, it'll return the number of views received within the specified time range. Available options: all, last24hours, last7days, last30days. Since version 5.3 you can also pass an array with the following keys: range, time_unit, and time_quantity (see below for an example.)
  • Number format (boolean, optional). If number format is set to true (default), wpp_get_views() will format the views count with grouped thousands (eg. 1,233). If set to false then wpp_get_views() will return the views count without any number formatting (eg. 1233).
  • Cache results (boolean, optional). If cache results is set to true (default is false), wpp_get_views() will store the views count on cache for around a minute, reducing the amount database queries done to get this value. If you're using this function on a high-traffic site you'll want to set this to true.

Usage:

<?php
if ( function_exists('wpp_get_views') ) {
    // get_the_ID() only works when used 
    // inside The Loop! (https://codex.wordpress.org/The_Loop)
    echo wpp_get_views(get_the_ID());
}
?>
<?php
if ( function_exists('wpp_get_views') ) {
    // '15' here is the ID of the post / page
    echo wpp_get_views(15, 'last7days');
}
?>
<?php
if ( function_exists('wpp_get_views') ) {
    // displays the views count of the current / post page,
    // and caches this data for a minute
    echo wpp_get_views(get_the_ID(), 'last24hours', false, true);
}
?>
<?php
if ( function_exists('wpp_get_views') ) {
    echo wpp_get_views(
        15, /* '15' here is the ID of the post / page */
        [
            'range' => 'custom', /* accepted values: all, last24hours, last7days, last30days, custom */
            'time_unit' => 'hour', /* accepted values: minute, hour, day, month */
            'time_quantity' => 1
        ]
    );
}
?>
Clone this wiki locally