{"id":38641,"date":"2015-09-22T01:35:03","date_gmt":"2015-09-22T01:35:03","guid":{"rendered":"https:\/\/wordpress.org\/plugins-wp\/custom-query-shortcode\/"},"modified":"2025-08-22T21:12:24","modified_gmt":"2025-08-22T21:12:24","slug":"custom-query-shortcode","status":"publish","type":"plugin","link":"https:\/\/cs.wordpress.org\/plugins\/custom-query-shortcode\/","author":13600367,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_crdt_document":"","version":"0.5.0","stable_tag":"0.5.0","tested":"6.8.5","requires":"3.3","requires_php":"","requires_plugins":null,"header_name":"Custom Query Shortcode","header_author":"Peter Hebert","header_description":"","assets_banners_color":"","last_updated":"2025-08-22 21:12:24","external_support_url":"","external_repository_url":"","donate_link":"","header_plugin_uri":"https:\/\/github.com\/peterhebert\/custom-query-shortcode","header_author_uri":"https:\/\/peterhebert.com\/","rating":5,"author_block_rating":0,"active_installs":20,"downloads":3218,"num_ratings":1,"support_threads":0,"support_threads_resolved":0,"author_block_count":0,"sections":["description","installation","faq","changelog"],"tags":{"0.2.2":{"tag":"0.2.2","author":"peterhebert","date":"2016-07-08 22:34:40"},"0.2.3":{"tag":"0.2.3","author":"peterhebert","date":"2016-07-08 22:34:40"},"0.2.4":{"tag":"0.2.4","author":"peterhebert","date":"2016-07-08 22:34:40"},"0.2.5":{"tag":"0.2.5","author":"peterhebert","date":"2016-07-08 22:34:40"},"0.3":{"tag":"0.3","author":"peterhebert","date":"2016-07-08 23:00:53"},"0.4.0":{"tag":"0.4.0","author":"peterhebert","date":"2021-04-10 19:08:40"},"0.5.0":{"tag":"0.5.0","author":"peterhebert","date":"2025-08-22 21:12:24"},"0.6.0":{"tag":"0.6.0","author":"peterhebert","date":"2025-12-01 15:47:24"}},"upgrade_notice":{"":"<p>Upgrades are handled just like any other WordPress plugin.<\/p>"},"ratings":{"1":0,"2":0,"3":0,"4":0,"5":"1"},"assets_icons":[],"assets_banners":[],"assets_blueprints":{},"all_blocks":[],"tagged_versions":["0.2.2","0.2.3","0.2.4","0.2.5","0.3","0.4.0","0.5.0","0.6.0"],"block_files":[],"assets_screenshots":{"screenshot-1.png":{"filename":"screenshot-1.png","revision":1250795,"resolution":"1","location":"assets","locale":""}},"screenshots":{"1":"Example of shortcode syntax"},"jetpack_post_was_ever_published":false},"plugin_section":[],"plugin_tags":[86,1626,80],"plugin_category":[43,57,59],"plugin_contributors":[93412,78384],"plugin_business_model":[],"class_list":["post-38641","plugin","type-plugin","status-publish","hentry","plugin_tags-post","plugin_tags-query","plugin_tags-shortcode","plugin_category-customization","plugin_category-taxonomy","plugin_category-utilities-and-tools","plugin_contributors-peterhebert","plugin_contributors-shazdeh","plugin_committers-peterhebert"],"banners":[],"icons":{"svg":false,"icon":"https:\/\/s.w.org\/plugins\/geopattern-icon\/custom-query-shortcode.svg","icon_2x":false,"generated":true},"screenshots":[{"src":"https:\/\/ps.w.org\/custom-query-shortcode\/assets\/screenshot-1.png?rev=1250795","caption":"Example of shortcode syntax"}],"raw_content":"<!--section=description-->\n<p>This plugin gives you <code>[query]<\/code> shortcode which enables you to query and output any posts filtered by specific attributes.<\/p>\n\n<h4>Usage<\/h4>\n\n<p>You can use most parameters supported by <a href=\"http:\/\/codex.wordpress.org\/Class_Reference\/WP_Query\">WP_Query class<\/a> to filter the posts; you can query for specific post types, categories, tags, authors, etc.<\/p>\n\n<h4>Other supported parameters<\/h4>\n\n<p>Aside from WP_Query parameters, the shortcode also supports the following additional parameters:<\/p>\n\n<ul>\n<li><em>featured<\/em>: to query for sticky posts which by default are excluded from the query.<\/li>\n<li><em>thumbnail_size<\/em>: to specify the size of the {THUMBNAIL} images. You can use <a href=\"http:\/\/codex.wordpress.org\/Function_Reference\/add_image_size#Reserved_Image_Size_Names\">built-in image sizes<\/a> or custom ones you've defined.<\/li>\n<li><em>content_limit<\/em>: to limit the number of words of the {CONTENT} var; by default it's \"0\" which means it outputs the whole content.<\/li>\n<li><em>posts_separator<\/em>: text to display between individual posts.<\/li>\n<li><em>lens<\/em>: custom output template - see description below.<\/li>\n<li><em>twig_template<\/em>: output template using Twig templating engine - requires the Timber library.<\/li>\n<\/ul>\n\n<h4>Formatting the output<\/h4>\n\n<p>You can define how you want to format the output inline within an opening <code>[query]<\/code> and closing <code>[\/query]<\/code> tag.\nAvailable keywords are: TITLE, CONTENT, AUTHOR, AUTHOR_URL, DATE, THUMBNAIL, CONTENT, COMMENT_COUNT.<\/p>\n\n<p>The following example will display the latest 5 posts from the category with the ID of 3, showing a post title and comment count, with a link to the post:\n    [query posts_per_page=\"5\" cat=\"3\"]<\/p>\n\n<h3><a href=\"{URL}\">{TITLE} ({COMMENT_COUNT})<\/a><\/h3>\n\n<p>[\/query]<\/p>\n\nGrid display\n\n<p>With the \"cols\" parameter you can display the output in a grid.\n    [query posts_per_page=\"3\" cols=\"3\"] {THUMBNAIL}<\/p>\n\n<h3>{TITLE}<\/h3>\n\n<p>{CONTENT} [\/query]\nwill display the latest 3 posts in the defined template, in 3 columns.\nThe plugin will automatically divide the grid into rows based upon the 'posts_per_page' option, divided by the 'cols' option.<\/p>\n\n<h4>Lenses (output templates)<\/h4>\n\n<p>With the \"lens\" parameter you can customize the display of the query results using a template. Some basic lenses\/templates are provided:<\/p>\n\n<ul>\n<li><strong>ul<\/strong>: unordered list of linked post titles.<\/li>\n<li><strong>ul-title-date<\/strong>: same as 'ul', but also displays the posted date.<\/li>\n<li><strong>article-excerpt<\/strong>: series of articles, with a header containing the linked post title, and the excerpt.<\/li>\n<li><strong>article-excerpt-date<\/strong>: same as 'article-excerpt', but also displays the posted date.<\/li>\n<li><strong>cards<\/strong>: displays the post thumb above the header with linked post title, followed by the excerpt.<\/li>\n<\/ul>\n\nBootstrap lenses\n\n<p>Some pre-defined lenses\/templates are provided which use JavaScript Components from the <a href=\"http:\/\/getbootstrap.com\/\">Bootstrap<\/a> CSS framework. The generated markup is compliant with the 5.x version of Bootstrap.<\/p>\n\n<p>This feature relies on Bootstrap library to be already loaded on the page, the plugin does <em>not<\/em> include it.<\/p>\n\n<p>If you're using a Bootstrap-based theme, this <em>should<\/em> work; otherwise you can use the <a href=\"http:\/\/wordpress.org\/extend\/plugins\/bootstrap\/\">Bootstrap plugin<\/a>).<\/p>\n\n<a href=\"http:\/\/getbootstrap.com\/javascript\/#tabs\">Tabs<\/a>\n\n<p>This will show the latest 3 posts in a tabbed widget.\n    [query posts_per_page=\"3\" lens=\"tabs\"]<\/p>\n\n<a href=\"http:\/\/getbootstrap.com\/javascript\/#tabs\">Accordion<\/a>\n\n<p>This will create an accordion widget of all our posts from the \"faq\" post type.\n    [query posts_per_page=\"0\" post_type=\"faq\" lens=\"accordion\"]<\/p>\n\n<a href=\"http:\/\/getbootstrap.com\/javascript\/#carousel\">Carousel<\/a>\n\n<p>This creates a carousel of latest five featured posts:\n    [query posts_per_page=\"5\" featured=\"true\" lens=\"carousel\"]<\/p>\n\nCustom Lenses\/templates\n\n<p>You can create your own custom templates and put them into one of these pre-defined folder names within your theme:<\/p>\n\n<ul>\n<li>'query-shortcode-templates'<\/li>\n<li>'partials\/query-shortcode-lenses\/'<\/li>\n<li>'html\/lenses\/'<\/li>\n<\/ul>\n\n<p>Or simply specify your own subfolder in the 'lens' parameter:\n    [query lens=\"folder\/template-name\"]<\/p>\n\n<h4>Twig Template Support<\/h4>\n\n<p>Starting with version 0.4, you can use Twig templates for your output. Support for Twig is provided by the <a href=\"https:\/\/github.com\/timber\/timber\">Timber<\/a> library.<\/p>\n\n<p>This requires that Timber 2.x be installed as a <a href=\"https:\/\/timber.github.io\/docs\/v2\/installation\/installation\/\">Composer dependency<\/a>.<\/p>\n\n<p>To use a Twig template for your query output, simply use the &#039;twig_template&#039; parameter instead of the &#039;lens&#039; parameter, and provide the path to your template. By default, Timber looks within the <code>views<\/code> folder in your active theme. You can <a href=\"https:\/\/timber.github.io\/docs\/v2\/guides\/template-locations\/#changing-the-default-folder-for-twig-files\">change the default template location<\/a> in Timber.<\/p>\n\n<p>Examples:<\/p>\n\n<pre><code>[query twig_template=\"template-name.twig\"]\n[query twig_template=\"folder\/template-name.twig\"]\n<\/code><\/pre>\n\n<!--section=installation-->\n<ol>\n<li>Upload the whole plugin directory to the <code>\/wp-content\/plugins\/<\/code> directory<\/li>\n<li>Activate the plugin through the 'Plugins' menu in WordPress<\/li>\n<li>Now use <code>[query]<\/code> shortcode anywhere you want.<\/li>\n<li>Enjoy!<\/li>\n<\/ol>\n\n<!--section=faq-->\n<p>no questions have been asked yet.<\/p>\n\n<!--section=changelog-->\n<h4>0.5.0<\/h4>\n\n<ul>\n<li>Security release - fixes to address path traversal vulnerability as noted in CVE-2025-8562.<\/li>\n<li>Added localization template .pot<\/li>\n<\/ul>\n\n<h4>0.4.0<\/h4>\n\n<ul>\n<li>Added Twig templating support via the Timber Library - note we do not include Timber with this plugin.<\/li>\n<\/ul>\n\n<h4>0.3<\/h4>\n\n<ul>\n<li>Added a new directory to search for lenses within the current theme - 'query-shortcode-templates'<\/li>\n<li>Revamped readme.txt documentation<\/li>\n<\/ul>\n\n<h4>0.2.5<\/h4>\n\n<ul>\n<li>Changed lens 'ul', removing post date. I also added lens 'ul-title-date', which is the equivalent of the previous 'ul' lens.<\/li>\n<\/ul>\n\n<h4>0.2.4<\/h4>\n\n<ul>\n<li>Added lens 'ul', presenting an unordered list of query results with post date displayed.<\/li>\n<\/ul>\n\n<h4>0.2.3<\/h4>\n\n<ul>\n<li>Added lens 'article-excerpt-date', which is the same as 'article-excerpt', except with the post date displayed.<\/li>\n<\/ul>\n\n<h4>0.2.2<\/h4>\n\n<ul>\n<li>Added a filter to allow shortcodes within widget areas, which makes this plugin a lot more useful.<\/li>\n<\/ul>\n\n<h4>0.2.1.1<\/h4>\n\n<ul>\n<li>Added a second directory to search for lenses within the current theme - 'partials\/custom-query-lenses'.<\/li>\n<\/ul>\n\n<h4>0.2.1<\/h4>\n\n<ul>\n<li>Added posts_separator parameter.<\/li>\n<\/ul>\n\n<h4>0.2<\/h4>\n\n<ul>\n<li>Added Lens functionality. Now you can build tabs, accordions, and carousels (and build custom ones) out of queried posts. Relies on Twitter Bootstrap framework.<\/li>\n<\/ul>","raw_excerpt":"A powerful shortcode that enables you to query anything you want and display it however you like, on both pages and posts, and in widgets.","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin\/38641","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin"}],"about":[{"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/types\/plugin"}],"replies":[{"embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/comments?post=38641"}],"author":[{"embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wporg\/v1\/users\/peterhebert"}],"wp:attachment":[{"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/media?parent=38641"}],"wp:term":[{"taxonomy":"plugin_section","embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_section?post=38641"},{"taxonomy":"plugin_tags","embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_tags?post=38641"},{"taxonomy":"plugin_category","embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_category?post=38641"},{"taxonomy":"plugin_contributors","embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_contributors?post=38641"},{"taxonomy":"plugin_business_model","embeddable":true,"href":"https:\/\/cs.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_business_model?post=38641"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}