MODX Property Sets: Stop Repeating Snippet Parameters Across Templates

The drift problem

When the same snippet appears in a dozen templates, its parameter list tends to rot. A news renderer might start as &limit=`10` &tpl=`NewsCard`, then one template needs five items, another needs a different chunk, and a third adds a parent filter. Six months later, nobody knows which call is authoritative, and a small change means editing every template.

MODX Revolution property sets exist to stop that drift. A property set is a named, reusable bundle of parameters attached to a snippet or plugin. You define it once in the manager, then invoke it with the @SetName syntax. Call sites stay short, and the configuration lives in one place.

How the @Set syntax works

A property set binds to a specific element. When you call a snippet, MODX looks for a matching set in this order:

1. Inline parameters passed in the tag (highest priority).
2. Properties from the named set, if you use [[Snippet@SetName]].
3. The element's default set, if one is marked.
4. The element's own default property values (lowest priority).

This means you can keep a shared baseline in a set and tweak individual calls without copying the whole list. The behavior of default sets and override precedence can vary between MODX 2.x and 3.x, so confirm the exact order on your installed version before relying on it in production.

A worked example: LatestNews

Suppose you have a snippet named LatestNews with two properties: limit (default 10) and tpl (default NewsCard).

In the manager, open the snippet's Properties tab and create a set called NewsList. Set limit to 5 and leave tpl as NewsCard. If you mark NewsList as the default set, every bare [[LatestNews]] call picks up those values automatically.

Your templates become:

<!-- Standard block: uses the default NewsList set -->
[[LatestNews]]

<!-- Sidebar variant: same set, but limit overridden to 3 -->
[[LatestNews@NewsList? &limit=`3`]]

In the sidebar call, tpl still comes from the set, while limit is overridden inline. You have not repeated the chunk name or the parent list; you have only stated the difference.

The nested-snippet trap

Property sets apply to the call they are attached to. They do not cascade into snippets that the called snippet invokes internally.

If LatestNews uses $modx->runSnippet('getResources', $props) or calls another extra snippet internally, that inner call does not see the outer property set. Keep in mind that getResources and pdoResources are extras, not core; verify they are installed and note their versions, since property names and defaults vary between them.

The fix is to pass options down explicitly. Inside your outer snippet, read the merged properties from $scriptProperties and hand them to the inner call:

$props = array(
    'limit' => $scriptProperties['limit'],
    'tpl'   => $scriptProperties['tpl'],
);
return $modx->runSnippet('getResources', $props);

If you forget this mapping, the inner snippet falls back to its own defaults, which may look correct in one context and wrong in another.

Operational notes that bite later

Property sets are linked to elements by database relationships. If you rename a snippet, the bindings can be orphaned. After any rename, open the element's Property Sets tab in the manager and confirm the set is still linked and, if intended, still marked as default.

Set values are cached with the element. After editing a set, clear the site cache before trusting the output of a previously cached resource. If a template still renders old values, a stale cache is the first thing to check.

Finally, property set values are visible to manager users with element access. Do not store credentials, API keys, or environment secrets in set properties.

Trade-offs: indirection versus repetition

Property sets add a layer of indirection. A reviewer reading a template sees [[LatestNews@NewsList]] and must open the set to know the real values. That is fine for shared configuration, but it is overkill for a one-off call.

A practical rule: use inline parameters when a call appears once. Invest in a property set when the same configuration repeats across three or more call sites, or when it must differ by environment (for example, development versus production).

One more limitation: property sets bind to snippets and plugins. They do not cascade into chunk defaults or template variable defaults. Template-level configuration still needs its own mechanism. Dynamic set selection—choosing a set name from a context or system setting at parse time—is also fragile across versions; prefer explicit set names or a small dispatcher snippet.

Verify before you trust it

Property set parsing and default-set handling have changed across MODX branches. Before documenting behavior as fact on your site, run a scratch test:

1. Create a scratch snippet with two properties and a property set.
2. On one test resource, render [[Snippet]], [[Snippet@Set]], and [[Snippet@Set? &prop=`x`]].
3. Diff the outputs to confirm defaults, binding, and override precedence.
4. Open the snippet's Property Sets tab to confirm the set is linked and marked default.
5. Reproduce the nested case: have the outer snippet call $modx->runSnippet('inner', $props) and log what the inner snippet receives.
6. Edit the set, clear cache, and reload a previously cached resource to confirm the change propagates.

If you support both MODX 2.8 and 3.x, repeat the scratch test on each branch and record any differences. The syntax is powerful, but only after you have confirmed it on your installed version.