# Custom Query Shortcode Custom Query Shortcode is a WordPress plugin that implements the WP\_Query functionality as a shortcode. It also allows you to embed queries within the body of a page or post. The plugin also allows you to customize the output of the results, either [inline with html](#inline-html-tags), through custom templates, or [lenses](#lenses-templates), as the shortcode parameter is called. If you are using Twig in your theme, you can even pass through a name of a [Twig](#twig) template. ### Shortcode parameters This shortcode will accept most of the parameters (methods) of the [WP\_Query class](https://developer.wordpress.org/reference/classes/wp_query/), that are simple key/value pairs. Due to complexity it does not accept nested arrays. In addition, the plugin also accepts thes following parameters: - `content_limit` (integer) - limit the number of words to display, used in conjunction with the `{CONTENT}` tag. If no value passed, it will output the whole of the post content. - `thumbnail_size` (string) - specify a defined image size - used with the `{THUMBNAIL}` tag - `featured` - (boolean) - when passed as TRUE, and sticky posts exist, will return the sticky or 'featured' posts. - `shortcode` - (boolean) - if passed as TRUE, then process any other shortcodes that exist within the content. - `lens` - (string) - the name of a [template](#lenses-templates) to display your posts. - `twig_template` - (string) - Specify a Twig template to use to displsy your posts. - `posts_separator` - (string) - A string to separate the posts, for example ', ' or '`
`' - grid parameters - you can list your posts in a simple grid, using the following parameters: - `cols` - (integer) - number of grid columns - `rows` - (integer) - number of grid rows ### Inline HTML with tags When you wrap the sortcode with opening and closing tags, you can use html and some select tags to output your posts. There are the available tags, which use curly brackets. - `{URL}` - the post permalink - `{TITLE}` - the post title - `{AUTHOR}` - maps to the the [get\_the\_author()](https://developer.wordpress.org/reference/functions/get_the_author/) function, outputs the author’s display name - `{AUTHOR_URL}` - gets the link to the authors' archive page, uses the [get\_author\_posts\_url()](https://developer.wordpress.org/reference/functions/get_author_posts_url/) function, - `{DATE}` - the Date the current post was written - uses the [get\_the\_date()](https://developer.wordpress.org/reference/functions/get_the_date/) function, formatted in your site's [date and time format](https://wordpress.org/documentation/article/customize-date-and-time-format/) - `{EXCERPT}` - uses [get\_the\_excerpt()](https://developer.wordpress.org/reference/functions/get_the_excerpt/) to return the post excerpt - `{COMMENT_COUNT}` - the number of comments the post has, uses the [get\_comments\_number()](https://developer.wordpress.org/reference/functions/get_comments_number/) function - `{THUMBNAIL}` - outputs the post thumbnail using the 'thumbnail' size by default; size can be customized using the 'thumbnail\_size' paramter - `{CONTENT}` = outputs the post content, either the full content, or a limited amount of words, or limited via the 'content\_limit' parameter #### Example of inline HTML: ```markup [query posts_per_page="5" cat="3"] {TITLE} ({COMMENT_COUNT}) [/query] ``` ### Lenses (Templates) We've provided a limited number of simple templates or "lenses" that you can pass through the 'lens' parameter, to display your content. Example: ```apache [query posts_per_page="5" featured="true" lens="carousel"] ``` I really liked this plugin, but noticed that it hadn't been updated in a while. I thought that it could use more lenses or templates to be really useful, so I [created a fork of the plugin](https://github.com/peterhebert/custom-query-shortcode/ "Custom Query Shortcode (GitHub)") and made my own customizations. #### List of included lenses / templates - `ul` - unordered list of linked post titles - `ul-title-date` - unordered list with the linked title and posted date - `article-excerpt` - article excerpt (linked title, featured image, excerpt) - `article-excerpt-date` - article excerpt with post date - `cards` - post thumbnail, linked title and excerpt - no styling provided. - Bootstrap components - [accordion](https://getbootstrap.com/docs/5.2/components/accordion/) - [carousel](https://getbootstrap.com/docs/5.2/components/carousel/) - [tabs](https://getbootstrap.com/docs/5.2/components/navs-tabs/#javascript-behavior) - the post title becomes the tab title and the post excerpt goes in the related content pane. - You can also pass in the names of your own custom PHP templates. It will search for the file within your active theme, within the following sub-folders: - `query-shortcode-templates/` - `partials/query-shortcode-lenses/` - `html/lenses/` ## Twig Template Support Starting with version 0.4, you can use Twig templates for your output. Support for Twig is provided by the [Timber](https://github.com/timber/timber) library. This requires that Timber 2.x be installed as a [Composer dependency](https://timber.github.io/docs/v2/installation/installation/). To use a Twig template for your query output, simply use the 'twig\_template' parameter instead of the 'lens' parameter, and provide the path to your template. By default, Timber looks within the `views` folder in your active theme. You can [change the default template location](https://timber.github.io/docs/v2/guides/template-locations/#changing-the-default-folder-for-twig-files) in Timber. Examples: ```apache [query twig_template="template-name.twig"] [query twig_template="folder/template-name.twig"] ``` ## Legacy widgets support Since WordPress does not allow shortcodes in widget areas by default, I [added a filter](https://codex.wordpress.org/Shortcode#Shortcodes_in_Widgets "Allow Shortcodes in Widgets (wordpress.org)") to allow this. ## Block Editor support While you can use Custom Query Shortcode using the Shortcode block, and it will work on the front end, this plugin does not support previewing the results within the block editor. I don't plan to provide full block editor support for this plugin. If you want a fully native query tool using the block editor, I would suggest using either the WordPress core [Query Loop](https://wordpress.org/documentation/article/query-loop-block/) block, or for more complex uses, the [Advanced Query Loop](https://wordpress.org/plugins/advanced-query-loop/) plugin. Project Type [WordPress plugin](/en/project-type/wordpress-plugin) Licence [GNU General Public License v2.0 or later](https://spdx.org/licenses/GPL-2.0-or-later.html#licenseText) Languages [PHP](/en/language/php) Tags [WordPress](/en/tag/wordpress) [plugins](/en/tag/plugins) Project Links [WordPress.org plugin page](https://wordpress.org/plugins/custom-query-shortcode/) [development repository (GitHub)](https://github.com/peterhebert/custom-query-shortcode/) - [Previous](/en/code/vagrant-recipe-for-drupal-and-wordpress-development) - [All](/en/code) - [Next](/en/code/phsite-cms)