Skip to content

1. Filter Hooks

Jump to bottom
Héctor Cabrera edited this page May 17, 2021 · 13 revisions

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:

recently_query_args

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' );

recently_pre_get_posts

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

recently_custom_html

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( ' &mdash; ', $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 );

recently_parse_custom_content_tags

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

recently_no_data

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

recently_thumbnail_class_attribute

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

recently_thumbnail_alt_attribute

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

recently_retina_support

Since: 3.0.0.

This filter hook allows you to enable/disable Recently's retina display support.

This filter receives only parameter:

  • $enabled, a boolean (default: true).

Here's an example:

/**
 * Disables Recently's retina display support.
 *
 * @param   bool    $enabled
 * @return  bool    Whether retina display support is enabled or not
 */
function disable_recently_retina_support( $enabled ){
    return false;
}
add_filter( 'recently_retina_support', 'disable_recently_retina_support', 10, 1 );

recently_thumbnail_compression_quality

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

recently_additional_theme_styles

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 the name of the Recently theme you're using.

recently_additional_themes

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');
Clone this wiki locally