WordPress.org

Plugin Directory

WPQuery Shortcode

A lightweight plugin that wraps the functionality of WP_Query in an easy-to-use shortcode.

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 =.

Filters & Actions

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

Requires: 3.5 or higher
Compatible up to: 3.8.10
Last Updated: 2013-12-13
Active Installs: 30+

Ratings

0 out of 5 stars

Support

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.