WordPress Page Add Custom Endpoint

Scenario is, you have a page http://example.com/popular/, and you want to add custom query variable for the page which can be retrieve using get_query_var() function to modify template or filter query. So a request to http://example.com/popular/music/2014/usa will make new query variables – (<popular_category = music, popular_year = 2014, popular_location = usa) available for you.

A solution can be achieved using add_rewrite_rule() & add_rewrite_tag() function, but there is a more easier way which will only use one function to make the custom query variable available for the specific page, and won’t effect any other pages or anything.

---

The Code

function popular_page_parse_request( $wp ) {
    // custom variables will only be available on popular page.
    $pageslug = 'popular';

    // get the actual request and parse it down
    if ( isset( $wp->request ) && strpos( $wp->request, '/' ) ) {
        $requests = explode( '/', $wp->request );

        // array_shift takes out the first path what is the page slug/name.
        // and make sure it's the popular page.
        if ( $pageslug == array_shift( $requests ) ) {
            // set pagename to make sure we have found a page with the name.
            $wp->set_query_var( 'pagename', $pageslug );

            // wordpress automatically try to check if it's an attachment when a parameter is present
            // after pageslug, so we set it false as we do the parsing ourselves.
            $wp->set_query_var( 'attachment', false );

            // we understand this is a valid page, and let WordPress understand there's no error.
            $wp->set_query_var( 'error', false );

            $count = count( $requests );

            if ( $count > 0 ) {
                // stop the canonical redirection, if a url request isn't same as get_permalink( ) or
                // the_permalink( ), then wordpress redirects it to the actual page
                // and removes all parameter after slug name.
                remove_action( 'template_redirect', 'redirect_canonical' );

                // the first parameter will definitely be the category.
                $wp->set_query_var( 'popular_category', $requests[0] );

                // for second one, we check if it could be a year, or it could be the country name.
                if ( isset( $requests['1'] ) ) {
                    // pretty basic checks.
                    if ( 4 == strlen( $requests['1'] ) && is_numeric( $requests['1'] ) ) {
                        $wp->set_query_var( 'popular_year', $requests[1] );
                    } else {
                        $wp->set_query_var( 'popular_location', $requests[1] );
                    }
                }

                // if location wasn't found yet, and we have third parameter variable.
                if ( isset( $requests['2'] ) && !isset( $wp->query_vars['popular_location'] ) ) {
                    if ( ! is_numeric( $requests['2'] ) ) {
                        $wp->set_query_var( 'popular_location', $requests[2] );
                    }
                }
            }

            // the final step to set some defaults if no value was available.
            if ( ! isset( $wp->query_vars['popular_category'] ) ) {
                $wp->set_query_var( 'popular_category', 'any' );
            }

            if ( !isset( $wp->query_vars['popular_year'] ) ) {
                $wp->set_query_var( 'popular_year', 'any' );
            }

            if ( !isset( $wp->query_vars['popular_location'] ) ) {
                $wp->set_query_var( 'popular_location', 'any' );
            }
        }
    }
}
add_action( 'parse_request', 'popular_page_parse_request' );

Above function processes has been commented for better understanding. Now we can use get_query_var( 'popular_category' ) or get_query_var( 'popular_year' ) or get_query_var( 'popular_location' ) to retrieve specific url custom query variable.

---

Example

We will create a list of posts based on our custom query variable. For that, first we will create a shortcode which will generate content using the custom query variable. And then place the shortcode on the Popular page.

function popular_posts_shortcode( $attrs ) {
    $html  = '';
    $query_args = array( 
        'order'          => 'DESC',
        'orderby'        => 'comment_count',
        'post_type'      => 'post',
        'post_status'    => 'publish',
        'posts_per_page' => -1,
        'meta_query'     => array()
    );

    if ( 'any' != get_query_var( 'popular_category' ) ) {
        $query_args['category_name'] = get_query_var( 'popular_category' );
    }

    if ( 'any' != get_query_var( 'popular_year' ) ) {
        $query_args['year'] = get_query_var( 'popular_year' );
    }

    // i use post custom field to add one or multiple location name with post
    // if you don't have any similar thing, don't use it. Otherwise you will always see empty result.
    if ( 'any' != get_query_var( 'popular_location' ) ) {
        $query_args['meta_query'][] = array( 
            'key' => 'location',
            'value' => array( get_query_var( 'popular_location' ) ),
            'compare' => 'IN'
        );
    }

    $query = new WP_Query( $query_args );

    if ( $query->have_posts() ) {
        $html .= '<ul>';
        while( $query->have_posts() ) : $query->the_post();
        $html .= sprintf( 
            '<li><a href="%1$s">%2$s</a> - <span title="posted %3$s ago">posted %3$s ago</span></li>',
            get_permalink(),
            get_the_title(),
            human_time_diff( strtotime( get_post()->post_date ), current_time( 'timestamp' ) )
        );
        endwhile;
        $html .= '</ul>';
    }

    wp_reset_query();

    return $html;
}
add_shortcode( 'popular_posts', 'popular_posts_shortcode' );

Ok, now if you use the shortcode [popular_posts] in your Page (Popular), you should see a list. Try manually entering url appending the popular page and check the results. You can also add some links to you nav menu using direct url of a popular page for quick access by you or user.

For ordering/sorting posts, we have used comment_count.