{"id":25113,"date":"2013-09-15T04:46:01","date_gmt":"2013-09-15T04:46:01","guid":{"rendered":"https:\/\/wordpress.org\/plugins-wp\/wpquery-shortcode\/"},"modified":"2013-12-13T06:18:59","modified_gmt":"2013-12-13T06:18:59","slug":"wpquery-shortcode","status":"closed","type":"plugin","link":"https:\/\/wordpress.org\/plugins\/wpquery-shortcode\/","author":4241320,"comment_status":"closed","ping_status":"closed","template":"","meta":{"version":"1.1.2","stable_tag":"1.1.2","tested":"3.7.41","requires":"3.5","requires_php":"","requires_plugins":"","header_name":"WPQuery Shortcode","header_author":"Russ Porosky ","header_description":"","assets_banners_color":"","last_updated":"2013-12-13 06:18:59","external_support_url":"","external_repository_url":"","donate_link":"","header_plugin_uri":"http:\/\/indyarmy.com\/wpquery-shortcode\/","header_author_uri":"http:\/\/indyarmy.com\/","rating":0,"author_block_rating":0,"active_installs":10,"downloads":1066,"num_ratings":0,"support_threads":0,"support_threads_resolved":0,"author_block_count":0,"sections":["description","installation","changelog"],"tags":[],"upgrade_notice":[],"ratings":{"1":0,"2":0,"3":0,"4":0,"5":0},"assets_icons":[],"assets_banners":[],"assets_blueprints":{},"all_blocks":[],"tagged_versions":["1.0.0","1.1.0","1.1.1","1.1.2"],"block_files":[],"assets_screenshots":[],"screenshots":[]},"plugin_section":[],"plugin_tags":[526,1626,80,32701,5913],"plugin_category":[43],"plugin_contributors":[95866],"plugin_business_model":[],"class_list":["post-25113","plugin","type-plugin","status-closed","hentry","plugin_tags-loop","plugin_tags-query","plugin_tags-shortcode","plugin_tags-wpquery","plugin_tags-wp_query","plugin_category-customization","plugin_contributors-indyarmy","plugin_committers-indyarmy"],"banners":[],"icons":{"svg":false,"icon":"https:\/\/s.w.org\/plugins\/geopattern-icon\/wpquery-shortcode.svg","icon_2x":false,"generated":true},"screenshots":[],"raw_content":"\n

WPQuery Shortcode<\/strong> is a lightweight plugin that wraps the functionality of WP_Query in an easy-to-use shortcode.<\/p>\n\n

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<\/strong> makes it easy.<\/p>\n\n

Examples<\/h3>\n\n

The most basic example is this:<\/p>\n\n

[wqs][\/wqs]\n<\/code><\/pre>\n\n
Which returns the following HTML by default:<\/p>\n\n
<div class=\"wqs_list\">\n    <ul class=\"wqs_list_post_wrap\">\n+--     <li class=\"wqs_list_post_item\">\n|           <a href=\"\u2026\" class=\"wqs_title\">Title One<\/a>\n| 5x        <span class=\"wqs_list_wqs_excerpt\">\n|               <p>This is the excerpt text.<\/p>\n|           <\/span>\n+--     <\/li>\n    <\/ul>\n<\/div>\n<\/code><\/pre>\n\n
If you want to use a section<\/code> tag instead of a div<\/code> tag, use the following filters to override the defaults:<\/p>\n\n
function wqs_wrapper_start($class) {\n    return \"<section class=\\\"{$class}\\\">\";\n}\nWQSDefaults::remove_filter('wqs_wrapper_start');        \/\/ Removes the default filter\nadd_filter('wqs_wrapper_start', 'wqs_wrapper_start');\n\nfunction wqs_wrapper_end() {\n    return \"<\/section>\";\n}\nWQSDefaults::remove_filter('wqs_wrapper_end');          \/\/ Removes the default filter\nadd_filter('wqs_wrapper_end', 'wqs_wrapper_end');\n<\/code><\/pre>\n\n
If you want to use the plugin within another plugin or directly from your functions.php<\/code> file in order to save yourself some trouble with The Loop:<\/p>\n\n
WQSDefaults::remove_all_filters();                      \/\/ Removes all default filters\n\/\/ Add your own filters here.\n$wqs = WQS::get_instance();\n$items = $wqs->wqs(array(\n    'cat' => 3,\n    \/\/ More WP_Query parameters here\n), 'Some header text here', TRUE);                      \/\/ Third param returns an array instead of a string.\nforeach ($items as $id => $item) {\n    \/\/ do stuff\n}\n<\/code><\/pre>\n\n
Options<\/h3>\n\n
WQS has a few attributes that do not belong to the WP_Query class.<\/p>\n\n
class=\"wqs_list\" - the CSS class assigned to the `ul` element that wraps the list of posts.\n\nshow_empty_message=\"Sorry, no posts were found.\" - the message displayed if no posts are found.\n\nshow_thumb=FALSE - whether to display the post thumbnail (Featured Image), if any.\n\nshow_excerpt=TRUE - whether to display the post excerpt.\n\nshow_date=FALSE - whether to display the post date below the excerpt.\n<\/code><\/pre>\n\n
Aside from that, any parameter that can be passed to WP_Query<\/code> can be used here, except for tax_query<\/code> and meta_query<\/code> (for now). The following ones have defaults.<\/p>\n\n
post_type=post - blog posts only\n\nposts_per_page=5 - only displays 5 posts\n\norderby=\"date\" - order by post date\n\norder=\"DESC\" - descending order (newest first)\n\nmeta_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.\n<\/code><\/pre>\n\n
Filters<\/h3>\n\n
wqs_pre_query<\/code><\/h4>\n\n
    \n
  • executed after the options have been combined<\/li>\n
  • intended to give theme authors the opportunity to mess with the query arguments, including adding advanced tax_query<\/code> or meta_query<\/code> arrays<\/li>\n
  • includes two parameters:\n\n
      \n
    • $options<\/code> - the complete array of attributes being passed to WP_Query<\/code><\/li>\n
    • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
    • Return<\/strong> the modified $options<\/code> array<\/li>\n
    • Default<\/strong> the unmodified $options<\/code> array<\/li>\n<\/ul>\n\n
      wqs_wrapper_start<\/code><\/h4>\n\n
        \n
      • executed immediately after the call to new WP_Query($args)<\/code>, before the Loop and before we've even checked if there are any posts returned<\/li>\n
      • intended to allow theme authors to customize the wrapper element(s)<\/li>\n
      • passed two parameters:\n\n
          \n
        • $class<\/code> - the CSS class from the shortcode<\/li>\n
        • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
        • Return<\/strong> the opening wrapper element(s)<\/li>\n
        • Default<\/strong> <div class=\"$class\"><\/code><\/li>\n<\/ul>\n\n
          wqs_header<\/code><\/h4>\n\n
            \n
          • executed immediately after the wqs_wrapper_start<\/code> filter<\/li>\n
          • intended to allow theme authors to mess with the passed shortcode content (which is, itself, intended to be the header for the resulting list)<\/li>\n
          • passed three parameters:\n\n
              \n
            • $header<\/code> - the content between the [wqs]<\/code> and [\/wqs]<\/code> tags<\/li>\n
            • $class<\/code> - the CSS class from the shortcode<\/li>\n
            • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
            • Return<\/strong> a header to display above the resulting list<\/li>\n
            • Default<\/strong> <h3>$header<\/h3><\/code> or NULL<\/code> if $header<\/code> is empty<\/li>\n<\/ul>\n\n
              wqs_pre_results<\/code><\/h4>\n\n
                \n
              • executed before The Loop begins, but after we have confirmed there is at least one result to display<\/li>\n
              • intended to allow theme authors to customize the wrapper for the result list itself<\/li>\n
              • passed two parameters:\n\n
                  \n
                • $class<\/code> - the CSS class from the shortcode<\/li>\n
                • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                • Return<\/strong> an opening wrapper element for the list of results<\/li>\n
                • Default<\/strong> <ul class=\"{$class}_{$post_type}_wrap\"><\/code><\/li>\n<\/ul>\n\n
                  wqs_pre_item<\/code><\/h4>\n\n
                    \n
                  • executed before each item in the result list<\/li>\n
                  • intended to allow theme authors to customize the element that wraps each item in the list<\/li>\n
                  • passed two parameters:\n\n
                      \n
                    • $class<\/code> - the CSS class from the shortcode<\/li>\n
                    • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                    • Return<\/strong> an opening wrapper element for the current item<\/li>\n
                    • Default<\/strong> <li class=\"{$class}_{$post_type}_item\"><\/code><\/li>\n<\/ul>\n\n
                      wqs_item_link<\/code><\/h4>\n\n
                        \n
                      • executed within the Loop<\/li>\n
                      • passed four parameters\n\n
                          \n
                        • $permalink<\/code> - the WordPress generated permalink URL to the item<\/li>\n
                        • $title<\/code> - the title of the soon-to-be-displayed item (be it post, page, comment, or whatever)<\/li>\n
                        • $class<\/code> - the CSS class from the shortcode<\/li>\n
                        • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                        • Return<\/strong> a link to the post<\/li>\n
                        • Default<\/strong> <a href=\"{$permalink}\" class=\"{$class}_title\">{$title}<\/a><\/code><\/li>\n<\/ul>\n\n
                          wqs_show_thumb<\/code><\/h4>\n\n
                            \n
                          • executed within the Loop<\/li>\n
                          • passed four parameters:\n\n
                              \n
                            • $thumb<\/code> - an empty string<\/li>\n
                            • $post_id<\/code> - the ID of the current post (same as get_the_ID()<\/code> function)<\/li>\n
                            • $class<\/code> - the CSS class from the shortcode<\/li>\n
                            • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                            • Return<\/strong> ideally, the thumbnail<\/li>\n
                            • Default<\/strong> <span class=\"{$class}_wqs_thumb\"><img src=\"\u2026\" \/><\/span><\/code> or $thumb<\/code> if the call to has_post_thumbnail($post_id)<\/code> fails<\/li>\n<\/ul>\n\n
                              wqs_show_excerpt<\/code><\/h4>\n\n
                                \n
                              • executed within the Loop<\/li>\n
                              • passed four parameters:\n\n
                                  \n
                                • $excerpt<\/code> - a string containing the result of a call to get_the_excerpt()<\/code>; should be modified and return<\/code>ed<\/li>\n
                                • $post_id<\/code> - the ID of the current post (same as get_the_ID()<\/code> function)<\/li>\n
                                • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                • Return<\/strong> an excerpt for the current post<\/li>\n
                                • Default<\/strong> <span class=\"{$class}_wqs_excerpt\">$excerpt<\/span><\/code><\/li>\n<\/ul>\n\n
                                  wqs_show_date<\/code><\/h4>\n\n
                                    \n
                                  • executed within the Loop<\/li>\n
                                  • passed four parameters:\n\n
                                      \n
                                    • $date<\/code> - a string containing the result of a call to get_the_date()<\/code>; should be modified and return<\/code>ed<\/li>\n
                                    • $post_id<\/code> - the ID of the current post (same as get_the_ID()<\/code> function)<\/li>\n
                                    • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                    • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                    • Return<\/strong> a date string to display<\/li>\n
                                    • Default<\/strong> <span class=\"{$class}_wqs_date\">$date<\/span><\/code><\/li>\n<\/ul>\n\n
                                      wqs_post_item<\/code><\/h4>\n\n
                                        \n
                                      • executed after each item in the result list<\/li>\n
                                      • intended to allow theme authors to customize the element that wraps each item in the list<\/li>\n
                                      • passed two parameters:\n\n
                                          \n
                                        • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                        • $post_type<\/code> - the actual post type (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                        • Return<\/strong> a closing wrapper element for the current item<\/li>\n
                                        • Default<\/strong> <\/li><\/code><\/li>\n<\/ul>\n\n
                                          wqs_post_results<\/code><\/h4>\n\n
                                            \n
                                          • executed after The Loop finishes, but only if at least one result existed<\/li>\n
                                          • intended to allow theme authors to customize the wrapper for the result list itself<\/li>\n
                                          • passed two parameters:\n\n
                                              \n
                                            • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                            • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                            • Return<\/strong> a closing wrapper element for the list of results<\/li>\n
                                            • Default<\/strong> <\/ul><\/code><\/li>\n<\/ul>\n\n
                                              wqs_wrapper_end<\/code><\/h4>\n\n
                                                \n
                                              • executed immediately befoer the call to wp_reset_postdata()<\/code><\/li>\n
                                              • intended to allow theme authors to customize the wrapper element(s)<\/li>\n
                                              • passed two parameters:\n\n
                                                  \n
                                                • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                                • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                                • Return<\/strong> the closing wrapper element(s)<\/li>\n
                                                • Default<\/strong> <\/div><\/code><\/li>\n<\/ul>\n\n
                                                  wqs_result_empty<\/code><\/h4>\n\n
                                                    \n
                                                  • executed after the wqs_header<\/code> filter if there are no results<\/li>\n
                                                  • passed three parameters:\n\n
                                                      \n
                                                    • $message<\/code> - the show_empty_message<\/code> value from the shortcode<\/li>\n
                                                    • $class<\/code> - the CSS class from the shortcode<\/li>\n
                                                    • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                                    • Return<\/strong> the message to display if no posts are found<\/li>\n
                                                    • Default<\/strong> <p>$message<\/p><\/code><\/li>\n<\/ul>\n\n
                                                      Actions<\/h3>\n\n
                                                      wqs_post_query<\/code><\/h4>\n\n
                                                        \n
                                                      • executed immediately after the call to new WP_Query($args)<\/code>, before the Loop and before we've even checked if there are any posts returned<\/li>\n
                                                      • passed two parameters:\n\n
                                                          \n
                                                        • $query<\/code> - the actual WP_Query<\/code> object<\/li>\n
                                                        • $post_type<\/code> - the post type from the shortcode (eg. post<\/code>, attachment<\/code>, movie<\/code>)<\/li>\n<\/ul><\/li>\n
                                                        • Default<\/strong> there is currently no default action associated with this hook<\/li>\n<\/ul>\n\n\n
                                                            \n
                                                          1. Upload the wpquery-shortcode<\/code> folder to your wp-content\/plugins\/<\/code> folder<\/li>\n
                                                          2. Activate the plugin<\/li>\n
                                                          3. In your post or page (or anyplace that shortcodes are parsed), place the shortcode [wqs]Most Recent Posts[\/wqs]<\/code><\/li>\n<\/ol>\n\n\n
                                                            1.1.2<\/strong><\/p>\n\n
                                                              \n
                                                            • added wqs_item_link<\/code> filter for modifying post titles and links<\/li>\n
                                                            • Documentation update<\/li>\n
                                                            • Docblocks made more consistent<\/li>\n<\/ul>\n\n
                                                              1.1.1<\/strong><\/p>\n\n
                                                                \n
                                                              • Documentation improvements<\/li>\n
                                                              • added raw<\/em> mode for theme and plugin authors<\/li>\n
                                                              • added convenience functions for remove_filter and remove_all_filters to remove a single default filter or all default filters, respectively<\/li>\n
                                                              • show_excerpt now defaults to TRUE<\/li>\n
                                                              • more consistent escaping in default filters<\/li>\n<\/ul>\n\n
                                                                1.0.0<\/strong><\/p>\n\n
                                                                  \n
                                                                • Initial release<\/li>\n<\/ul>","raw_excerpt":"A lightweight plugin that wraps the functionality of WP_Query in an easy-to-use shortcode.","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin\/25113","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin"}],"about":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/types\/plugin"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/comments?post=25113"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wporg\/v1\/users\/indyarmy"}],"wp:attachment":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/media?parent=25113"}],"wp:term":[{"taxonomy":"plugin_section","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_section?post=25113"},{"taxonomy":"plugin_tags","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_tags?post=25113"},{"taxonomy":"plugin_category","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_category?post=25113"},{"taxonomy":"plugin_contributors","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_contributors?post=25113"},{"taxonomy":"plugin_business_model","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_business_model?post=25113"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}