Advanced Queries

When using theme elements that display posts such as the Post Cards element, there are built-in settings for controlling the posts that are shown so you can choose how many to display, include or exclude terms, change the order, etc…

If you need more complex queries, the theme offers an “Advanced” Query type which allows you to enter the exact arguments you need for your query using a “Parameter String”.

Once the setting is enabled you will see a new field named “Query Parameter String or Callback Function Name“. Here is where you will enter your advanced query settings and you have 2 options:

1. You can enter a Query String
2. You can enter a custom callback function

Using a Query String

A query string is a string that contains parameters which looks something like this:

posts_per_page=-1&post_type=portfolio&post_status=publish&orderby=title&tax_query[0][taxonomy]=portfolio_category&tax_query[0][field]=slug&tax_query[0][terms][]=inspiration

Think of this as creating a standard WP_Query using an array of arguments, but instead of providing an array you are providing a string.

Array Values

Since Total 5.5 any value that is an array can be defined using a comma separated string. So instead of doing the following:

post_type[]=post&post_type[]=portfolio

You can now simply do:

post_type=post,portfolio

Dynamic Values: The theme has various dynamic values you can use in the query, for example if you need to exclude the current post or display items from the current post author. Learn more here →

Creating advanced string queries using ChatGPT

If you are creating an advanced query with a lot of parameters you can always create your standard array like you would for WP_Query and use ChatGPT to convert it into a query string for you.

Using a Callback Function

Instead of entering your custom parameters as a string you can instead use a custom function in your child theme or code snippets plugin that returns an array of arguments to pass to WP_Query.

This is the preferred method for more advanced queries that require dynamic values or extra checks that are not possible via a simple string query.

Step 1: Create a New Function

Add a new PHP function to your child theme or Code Snippets plugin which will return your custom query arguments. Below is a very basic example:

function myprefix_get_staff_members() {
    $args = [
        'post_type' => 'staff',
        'posts_per_page' => '12',
    ];
    return $args;
}

Step 2: White List Your Function

For security reasons your function will need to be whitelisted so that the theme knows it's an allowed function. This is done by adding a new VCEX_CALLBACK_FUNCTION_WHITELIST constant to your child theme that returns an array of whitelisted functions.

/*
 * White list functions for use in Total Theme Core elements.
 */
define( 'VCEX_CALLBACK_FUNCTION_WHITELIST', [
    'myprefix_get_staff_members',
] );

Step 3: Select Your Callback Function

Once your custom function is added and whitelisted you can select it for use from the Post Cards element like such: