-
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 hook 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: 2.1.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 filter hook 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 );Since: 3.0.0.
The recently_thumbnail_class_attribute filter hook 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 two parameters:
-
$classes, an array of CSS classes. -
$post_id, the ID of the post/page.
Here's an example:
/**
* Adds some custom CSS classes to our Recently posts.
*
* @param array $classes
* @param int $post_id
* @return array The (modified) $classes array
*/
function custom_recently_css_class( $classes, $post_id ){
$classes[] = 'my-custom-css-class';
return $classes;
}
add_filter( 'recently_thumbnail_class_attribute', 'custom_recently_css_class', 10, 2 );Since: 3.0.0.
This filter hook allows you to customize the ALT attribute of every post thumbnail loaded by Recently.
This filter receives two parameters:
-
$alt, the original ALT attribute. -
$post_id, the ID of the post/page.
Here's an example:
/**
* Add a default ALT attribute if empty/missing.
*
* @param string $alt
* @param int $post_id
* @return string The (modified) $classes array
*/
function custom_recently_alt_attribute( $alt, $post_id ){
if ( '' == $alt )
$alt = 'No image';
return $alt;
}
add_filter( 'recently_thumbnail_alt_attribute', 'custom_recently_alt_attribute', 10, 2 );Since: 3.0.0.
This filter hook allows you to enable/disable Recently's retina display support.
This filter receives only parameter:
-
$enable, a boolean (default: true).
Here's an example:
/**
* Disables Recently's retina display support.
*
* @param bool $enabled
* @return bool Whether retina display is enabled or not
*/
function disable_recently_retina_support( $enabled ){
return false;
}
add_filter( 'disable_recently_retina_support', 'custom_recently_alt_attribute', 10, 1 );Since: 3.0.0.
Changes the image compression quality of Recently's thumbnails.
Parameters:
-
$quality- an integer value ranging from 0 to 100 (eg. 85)
Usage example:
/**
* Sets Recently thumbnail's image quality to 85.
*
* @param int $quality
* @return int
*/
function my_recently_thumbnail_compression_quality($quality){
return 85;
}
add_filter('recently_thumbnail_compression_quality', 'my_recently_thumbnail_compression_quality', 10, 1);Since: 3.0.0.
Extends the CSS rules of the currently applied theme.
Parameters:
-
$additional_styles- Additional CSS rules. -
$theme_name- Theme name.
Usage example:
/**
* Make Recently's post links red in 'Cards' theme.
*
* @param string $additional_styles
* @param string $theme_name
* @return string
*/
function recently_additional_css_rules($additional_styles, $theme_name){
if ( 'cards' == $theme_name ) {
$additional_styles .= '.recently-list li a { color: red; }';
}
return $additional_styles;
}
add_filter('recently_additional_theme_styles', 'recently_additional_css_rules', 10, 2);Make sure you change cards for whatever is the name of the Recently theme you're currently using.
Since: 3.0.0
This hooks allows you to register one or more themes for the widget (see developing a custom theme for more details).
Parameters:
-
$themes- An array of theme paths.
Usage example:
/**
* Registers my Recently theme.
*
* @param array $themes
* @return array
*/
function recently_register_my_theme($themes){
// Absolute path to the theme
$themes[] = plugin_dir_path(__FILE__) . 'my-theme'; // Use get_template_directory() instead if your Recently theme is inside a WordPress theme directory.
return $themes;
}
add_filter('recently_additional_themes', 'recently_register_my_theme');