This plugin hasn’t been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues when used with more recent versions of WordPress.

WPQuery Shortcode

Description

WPQuery Shortcode is a lightweight plugin that wraps the functionality of WP_Query in an easy-to-use shortcode.

Several filters are built in to allow all kinds of messing with how the output is displayed. From a simple “Recent Posts” block on your page to displaying upcoming events from your calendar plugin to showing the most visited job postings, WPQuery Shortcode makes it easy.

Examples

The most basic example is this:

[wqs][/wqs]

Which returns the following HTML by default:

<div class="wqs_list">
    <ul class="wqs_list_post_wrap">
+--     <li class="wqs_list_post_item">
|           <a href="…" class="wqs_title">Title One</a>
| 5x        <span class="wqs_list_wqs_excerpt">
|               <p>This is the excerpt text.</p>
|           </span>
+--     </li>
    </ul>
</div>

If you want to use a section tag instead of a div tag, use the following filters to override the defaults:

function wqs_wrapper_start($class) {
    return "<section class=\"{$class}\">";
}
WQSDefaults::remove_filter('wqs_wrapper_start');        // Removes the default filter
add_filter('wqs_wrapper_start', 'wqs_wrapper_start');

function wqs_wrapper_end() {
    return "</section>";
}
WQSDefaults::remove_filter('wqs_wrapper_end');          // Removes the default filter
add_filter('wqs_wrapper_end', 'wqs_wrapper_end');

If you want to use the plugin within another plugin or directly from your functions.php file in order to save yourself some trouble with The Loop:

WQSDefaults::remove_all_filters();                      // Removes all default filters
// Add your own filters here.
$wqs = WQS::get_instance();
$items = $wqs->wqs(array(
    'cat' => 3,
    // More WP_Query parameters here
), 'Some header text here', TRUE);                      // Third param returns an array instead of a string.
foreach ($items as $id => $item) {
    // do stuff
}

Options

WQS has a few attributes that do not belong to the WP_Query class.

class="wqs_list" - the CSS class assigned to the `ul` element that wraps the list of posts.

show_empty_message="Sorry, no posts were found." - the message displayed if no posts are found.

show_thumb=FALSE - whether to display the post thumbnail (Featured Image), if any.

show_excerpt=TRUE - whether to display the post excerpt.

show_date=FALSE - whether to display the post date below the excerpt.

Aside from that, any parameter that can be passed to WP_Query can be used here, except for tax_query and meta_query (for now). The following ones have defaults.

post_type=post - blog posts only

posts_per_page=5 - only displays 5 posts

orderby="date" - order by post date

order="DESC" - descending order (newest first)

meta_compare="=" - if a `meta_key` is specified, the default comparison is `=`.<h3>Filters & Actions</h3>WQS includes a few filter and action hooks for your hacking and themeing pleasure.

Filters

wqs_pre_query

  • executed after the options have been combined
  • intended to give theme authors the opportunity to mess with the query arguments, including adding advanced tax_query or meta_query arrays
  • includes two parameters:
    • $options – the complete array of attributes being passed to WP_Query
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return the modified $options array
  • Default the unmodified $options array

wqs_wrapper_start

  • executed immediately after the call to new WP_Query($args), before the Loop and before we’ve even checked if there are any posts returned
  • intended to allow theme authors to customize the wrapper element(s)
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return the opening wrapper element(s)
  • Default <div class="$class">

wqs_header

  • executed immediately after the wqs_wrapper_start filter
  • intended to allow theme authors to mess with the passed shortcode content (which is, itself, intended to be the header for the resulting list)
  • passed three parameters:
    • $header – the content between the [wqs] and [/wqs] tags
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return a header to display above the resulting list
  • Default <h3>$header</h3> or NULL if $header is empty

wqs_pre_results

  • executed before The Loop begins, but after we have confirmed there is at least one result to display
  • intended to allow theme authors to customize the wrapper for the result list itself
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return an opening wrapper element for the list of results
  • Default <ul class="{$class}_{$post_type}_wrap">

wqs_pre_item

  • executed before each item in the result list
  • intended to allow theme authors to customize the element that wraps each item in the list
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return an opening wrapper element for the current item
  • Default <li class="{$class}_{$post_type}_item">

wqs_item_link

  • executed within the Loop
  • passed four parameters
    • $permalink – the WordPress generated permalink URL to the item
    • $title – the title of the soon-to-be-displayed item (be it post, page, comment, or whatever)
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return a link to the post
  • Default <a href="{$permalink}" class="{$class}_title">{$title}</a>

wqs_show_thumb

  • executed within the Loop
  • passed four parameters:
    • $thumb – an empty string
    • $post_id – the ID of the current post (same as get_the_ID() function)
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return ideally, the thumbnail
  • Default <span class="{$class}_wqs_thumb"><img src="…" /></span> or $thumb if the call to has_post_thumbnail($post_id) fails

wqs_show_excerpt

  • executed within the Loop
  • passed four parameters:
    • $excerpt – a string containing the result of a call to get_the_excerpt(); should be modified and returned
    • $post_id – the ID of the current post (same as get_the_ID() function)
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return an excerpt for the current post
  • Default <span class="{$class}_wqs_excerpt">$excerpt</span>

wqs_show_date

  • executed within the Loop
  • passed four parameters:
    • $date – a string containing the result of a call to get_the_date(); should be modified and returned
    • $post_id – the ID of the current post (same as get_the_ID() function)
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return a date string to display
  • Default <span class="{$class}_wqs_date">$date</span>

wqs_post_item

  • executed after each item in the result list
  • intended to allow theme authors to customize the element that wraps each item in the list
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the actual post type (eg. post, attachment, movie)
  • Return a closing wrapper element for the current item
  • Default </li>

wqs_post_results

  • executed after The Loop finishes, but only if at least one result existed
  • intended to allow theme authors to customize the wrapper for the result list itself
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return a closing wrapper element for the list of results
  • Default </ul>

wqs_wrapper_end

  • executed immediately befoer the call to wp_reset_postdata()
  • intended to allow theme authors to customize the wrapper element(s)
  • passed two parameters:
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return the closing wrapper element(s)
  • Default </div>

wqs_result_empty

  • executed after the wqs_header filter if there are no results
  • passed three parameters:
    • $message – the show_empty_message value from the shortcode
    • $class – the CSS class from the shortcode
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Return the message to display if no posts are found
  • Default <p>$message</p>

Actions

wqs_post_query

  • executed immediately after the call to new WP_Query($args), before the Loop and before we’ve even checked if there are any posts returned
  • passed two parameters:
    • $query – the actual WP_Query object
    • $post_type – the post type from the shortcode (eg. post, attachment, movie)
  • Default there is currently no default action associated with this hook

Installation

  1. Upload the wpquery-shortcode folder to your wp-content/plugins/ folder
  2. Activate the plugin
  3. In your post or page (or anyplace that shortcodes are parsed), place the shortcode [wqs]Most Recent Posts[/wqs]

Contributors & Developers

“WPQuery Shortcode” is open source software. The following people have contributed to this plugin.

Contributors

Translate “WPQuery Shortcode” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.1.2

  • added wqs_item_link filter for modifying post titles and links
  • Documentation update
  • Docblocks made more consistent

1.1.1

  • Documentation improvements
  • added raw mode for theme and plugin authors
  • added convenience functions for remove_filter and remove_all_filters to remove a single default filter or all default filters, respectively
  • show_excerpt now defaults to TRUE
  • more consistent escaping in default filters

1.0.0

  • Initial release