Dynamic Search Criteria for getResources

How to create a &where clause for getResources and other Snippets in a custom Snippet.

By Bob Ray  |  October 17, 2023  |  2 min read
Community MODX CMS Tutorials
Dynamic Search Criteria for getResources

There are many cases where the search criteria you want to specify for getResources, pdoResources, or another Extra that uses a &where property, require calculations or are too complex to enter off the top of your head. In this article we’ll look at a way to use a Snippet to create them for you.

We’ll use getResources as an example, but this method will work for any &where property (including one for pdoResources).

The Method

The getResources &where property is a JSON string specifying search criteria for getResources to use in selecting Resources. Sometimes, you can just create the JSON string yourself, but in other cases, you can use a Snippet or placeholder to provide the &where property:

[[getResources? &where=`[[CalculatedWhere]]` . . .]]

The work of creating the value for the &where property is done in a Snippet called “CalculatedWhere”. Here’s an easy example that you could create yourself if you understand JSON. It gets all Resources that are published and not deleted:

/* CalculatedWhere snippet */
$c = array(
    'published' => 1,
    'deleted' => 0,
);
return $modx->toJSON($c);

Note that the keys and values in the array are separated, not by an equals sign, but by the => array assignment operator and the lines in the array all end with a comma. The [[CalculatedWhere]] tag would be replaced by the value returned from the Snippet. The resulting property in the tag for the example above would look like this:

&where = `{"published":1,"deleted":0}`

More Examples

In the next example, we’ll get published, not-deleted Resources created by the current logged-in user. You still might be able to write your own &where property using a userinfo tag, but this will be faster and easier:

/* CalculatedWhere snippet */
$c = array(
    'published' => 1,
    'deleted' => 0,
    'createdby' => $modx->user->get('id'),
);
return $modx->toJSON($c);

The example above would produce something like this property in the tag:

&where = `{"published":1,"deleted":0,"createdby":12}`

Here’s one that would be almost impossible without a Snippet. It gets all Resources published during a specified month of a particular year.

[[getResources? &where=`[[CalculatedWhere? &month=`January` &year=`2015`]]` . . .]]
$month = $scriptProperties['month'];
$year = $scriptProperties['year'];
$a_date = $month . ' ' . $year;
$min = strtotime($a_date);
$time = date("Y-m-t 23:59", $min);
$max =  strtotime($time);

$where = array(
    'publishedon:>=' => $min,
    'publishedon:<=' => $max,
);
return $modx->toJSON($where);

The method used above is a little tricky (actually it’s tricky as hell). What we want is to calculate one Unix timestamp for midnight at the beginning of the specified month and another for one second before midnight on the last day of the month. The first is easy, it’s the $min calculation in line four. The next line uses the fact that the “t” token of the date() method evaluates to the number of the last day of the month, so $time will be set to one second before midnight on the last day of the month, regardless of the number of days in the month. For February, 2015, $time will be 2015-02-28 23:59. For January, it will be 2015-01-31 23:59. The $max calculation simply converts $time into a Unix timestamp. The resulting JSON string looks like this for January, 2015:

{"publishedon:>=":1420092000,"publishedon:<=":1422770340}

Using a Placeholder

There may be cases where a Snippet tag in the getResources call doesn’t work properly because of the parsing order. Another strategy is to put a placeholder tag in the getResources &where property and have your Snippet set a placeholder.

[[getResources? &where=`[[+CalculatedWhere]]` . . .]]

In the Snippet, then, just do this (the Snippet tag must be above the placeholder tag on the page):

$jsonString = $modx->toJSON($myArray);
$modx->setPlaceholder('CalculatedWhere', $jsonString);

If you have more than one getResources call on the page, you can add a property to the Snippet tag to specify the placeholder that will be set:

[[SetWhere? $month=`January` &year=`2015 &ph=`January`]]
[[getResources? &where=`[[+January]]` . . .]]

...

[[SetWhere? $month=`February` &year=`2015 &ph=`February`]]
[[getResources? &where=`[[+February]]` . . .]]

Then in the Snippet:

$placeholderName = $scriptProperties['ph']
// ...

$modx->setPlaceholder($placeholderName, $value);

Speeding Things Up

If the values sent to the Snippet won’t change, or won’t change very often, you can just write a utility version of the Snippet that simply returns the JSON string. Then you can paste that string as the value of the getResources &where property.

Caveats

The methods described here can fail under some circumstances when getResources is called in a Chunk (especially if it’s called more than once). You can experiment with calling the Snippet cached or uncached, but there will be some cases where it just won’t work, although you may be able to fix it by moving the getResources call up into the Template or the page content, or by using a placeholder.

If the return value of the Snippet never changes, the “CalculatedWhere” method is also somewhat inefficient. It’s perfect for queries that are “dynamic” and have criteria that may change at any time. If the value won’t ever change, (as in our first two examples above), the solution is to put a tag for the “CalculatedWhere” Snippet on a page. The Snippet will return its output as usual, and it will be displayed where the tag was when you visig the page. Just cut-and-paste the result into the Snippet properties of the Snippet that needs the &where statement.

More Information on xPDO Query Where

The &where property is used by a number of MODX Extras. Because they all use xPDO to retrieve the data, they will always take any valid xPDO criteria as long as they are in JSON format. There is documentation here along with some excellent examples. To generate a &whereproperty using a Snippet or Snippet plus placeholder, you don’t need all the query language, just the array inside the parentheses following the word “where” (which may have other arrays inside it).

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.