-
Notifications
You must be signed in to change notification settings - Fork 2
1. Filter Hooks
Filter hooks are one of the most versatile and useful features that WordPress has to offer. It allows maximum flexibility when it comes to modifying stuff, be it a theme, a plugin and even WordPress itself.
Recently takes advantage of this feature to let you modify the widget so it matches your specific needs. To use these filters, put them in your theme's functions.php file (or you can also create a plugin for this purpose, if you know how to).
Available filter hooks:
Since: 1.0.0.
The recently_query_args filter hooks allows you to customize the set of parameters used by the plugin to retrieve your recent posts from the database.
This filter hook receives one parameter:
-
$args, an array of arguments. You can find the complete set of available options here.
Here's an example:
/**
* Get scheduled movie posts from the Action and Comedy genres
* but exclude those associated to actor IDs 103, 115 and 206.
*
* @param array $args array of parameters
* @return array $args array of parameters
*/
function recently_custom_query_args( $args ){
$args['post_type'] = 'movie';
$args['post_status'] = 'future';
$args['tax_query'] = array(
'relation' => 'AND',
array(
'taxonomy' => 'movie_genre',
'field' => 'slug',
'terms' => array( 'action', 'comedy' ),
),
array(
'taxonomy' => 'actor',
'field' => 'term_id',
'terms' => array( 103, 115, 206 ),
'operator' => 'NOT IN',
),
);
return $args;
}
add_filter( 'recently_query_args', 'recently_custom_query_args' );Since: 2.1.0
Pretty much like the recently_query_args, this filter hook also allows to customize the parameters used by the plugin to query the database for posts. The only difference is that, unlike the recently_query_args, this filter hook includes the widget ID so you can customize each Recently widget separately.
Parameters:
-
$args, an array of arguments. You can find the complete set of available options here. -
$widget_id, the ID of the current widget instance.
Here's an example:
/**
* Have Recently return random posts
* for widget instance ID 'recently-2'
*
* @param array $args The args passed to WP_Query.
* @param string $widget_id The ID of the current widget instance.
* @return array
*/
function recently_get_random_posts( $args, $widget_id ){
if ( 'recently-2' == $widget_id )
$args['orderby'] = 'rand';
return $args;
}
add_filter( 'recently_pre_get_posts', 'recently_get_random_posts', 10, 2 );Since: 1.0.0.
The recently_custom_html filter hook gives you complete control over the HTML output of the widget.
This filter receives two parameters:
-
$recents, an array of recent posts objects. -
$options, an array of options from the widget.
Keep in mind that the data you'll receive depends on what options you have enabled/disabled in the widget.
Here's an example:
/**
* Builds custom HTML for the Recently plugin
*
* With this function, I can alter WPP's HTML output from my theme's functions.php.
* This way, the modification is permanent even if the plugin gets updated.
*
* @param array $recents
* @param array $options
* @return string
*/
function custom_recently_html_output( $recents, $options ){
$output = '';
if ( $recents->have_posts() ) {
$output = '<ul class="recently-list">' . "\n";
// Loop through items
while ( $recents->have_posts() ) {
$recents->the_post(); global $post;
$stats = array(); // placeholder for the stats tag
// Comment count option active, display comments count
if ( $options['meta_tag']['comment_count'] ) {
// display text in singular or plural, according to comments count
$stats[] = '<span class="recently-comments">' . sprintf(
_n('1 comment', '%s comments', get_comments_number( get_the_ID() ), 'recently'),
number_format_i18n( get_comments_number( get_the_ID() ) )
) . '</span>';
}
// Pageviews option checked, display views count
if ( $options['meta_tag']['views'] && function_exists('wpp_get_views') ) {
// display text in singular or plural, according to views count
$stats[] = '<span class="recently-views">' . sprintf(
_n('1 view', '%s views', intval( wpp_get_views( get_the_ID() ) ), 'recently'),
number_format_i18n( wpp_get_views( get_the_ID() ) )
) . '</span>';
}
// Author option checked
if ( $options['meta_tag']['author'] ) {
$author = get_the_author_meta( 'display_name', $post->post_author );
$display_name = '<a href="' . get_author_posts_url( $post->post_author ) . '">' . $author . '</a>';
$stats[] = '<span class="recently-author">' . sprintf(__('by %s', 'recently'), $display_name). '</span>';
}
// Date option checked
if ( $options['meta_tag']['date']['active'] ) {
$date = date_i18n( $options['meta_tag']['date']['format'], strtotime( $post->post_date ) );
$stats[] = '<span class="recently-date">' . sprintf(__('posted on %s', 'recently'), $date) . '</span>';
}
// Taxonomy option checked
if ( $options['meta_tag']['taxonomy']['active'] && !empty($options['meta_tag']['taxonomy']['names']) ) {
$post_tax = array();
// Get terms
foreach( $options['meta_tag']['taxonomy']['names'] as $tax_name ) {
$terms = get_the_terms( $post->ID, $tax_name );
if ( !empty($terms) && !is_wp_error($terms) ) {
foreach ( $terms as $term ) {
$post_tax[$tax_name][] = '<a href="' . get_term_link( $term->slug, $tax_name ) . '">' . $term->name . '</a>';
}
}
}
if ( !empty($post_tax) ) {
$stats[] = '<span class="recently-taxonomy recently-category">under ' . implode(', ', $post_tax['category']) . '</span>';
}
}
// Build stats tag
if ( !empty($stats) ) {
$stats = '<div class="recently-meta">' . join( ' — ', $stats ) . '</div>';
}
$output .= '
<li itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
<span itemprop="item" itemscope itemtype="http://schema.org/WebPage">
<a href="' . get_the_permalink( get_the_ID() ) . '" title="' . esc_attr( get_the_title() ) . '" itemprop="url" rel="bookmark"><span itemprop="name">' . get_the_title() . '</span></a>
</span>
' . $stats . '
</li>' . "\n";
}
$output .= '</ul>' . "\n";
}
return $output;
}
add_filter( 'recently_custom_html', 'custom_recently_html_output', 10, 2 );Since: 4.2.0
Use this filter to add new Content Tags for use in Recently's custom HTML markup options (except when using the recently_custom_html filter hook).
Parameters:
-
$html- the parsed HTML string. -
$post_id- the post/page ID.
Usage example:
/**
* Parses custom content tags in Recently.
*
* @param string $html The HTML markup from the plugin.
* @param integer $post_id The post/page ID.
* @return string
*/
function recently_parse_my_custom_content_tags( $html, $post_id ){
// Replace custom content tag {tags} with actual tags
if ( false !== strpos($html, '{tags}') ) {
// Get tags
$tags = get_the_tags( $post_id );
$tag_links = '<small>Tags: ';
if ( $tags ) {
foreach( $tags as $tag ) {
$tag_links .= '<a href="' . get_tag_link( $tag->term_id ) . '">' . $tag->name . '</a>, ';
}
// Remove last comma from tags list
$tag_links = rtrim( $tag_links, ', ');
// Replace {tags} with the actual tags
$html = str_replace( '{tags}', $tag_links, $html );
$html .= '</small>';
}
}
return $html;
}
add_filter( "recently_parse_custom_content_tags", "recently_parse_my_custom_content_tags", 10, 2 );Since: 1.0.0.
The recently_no_data allows you to customize the "Sorry, nothing to show yet" message returned by the widget when there are no posts to show.
This filter receives one parameter:
-
$message, a HTML paragraph that contains the default message.
Here's an example:
/**
* Changes the default "Sorry, nothing to show yet" message returned by the widget
* when there are no posts to show.
*
* @param array $message
* @return string
*/
function custom_recently_no_posts_found_message( $message ){
return "<p>Err... it seems we don't have anything to show yet!</p>";
}
add_filter( 'recently_no_data', 'custom_recently_no_posts_found_message', 10, 1 );