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, through custom templates, or lenses, as the shortcode parameter is called. If you are using Twig in your theme, you can even pass through a name of a Twig template.

Shortcode parameters

This shortcode will accept most of the parameters (methods) of the WP_Query class, 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 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 '<br>'
• 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() function, outputs the author’s display name
• {AUTHOR_URL} - gets the link to the authors' archive page, uses the get_author_posts_url() function,
• {DATE} - the Date the current post was written - uses the get_the_date() function, formatted in your site's date and time format
• {EXCERPT} - uses get_the_excerpt() to return the post excerpt
• {COMMENT_COUNT} - the number of comments the post has, uses the 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:

[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:

[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 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
  • carousel
  • tabs - 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 library.

This requires that Timber 2.x be installed as a Composer dependency.

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 in Timber.

Examples:

[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 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 block, or for more complex uses, the Advanced Query Loop plugin.