Mastering MODX TV Inheritance: Default Values, Overrides, and Cache Pitfalls

Problem: Inconsistent Header Text Across Pages

When building a MODX Revolution site, a common stumbling block is the header text that appears on every page. Some pages show the site‑wide “Welcome” header, while others display a custom message. The root cause is often a misunderstanding of how Template Variables (TVs) inherit values from templates and how overrides affect rendering and caching.

Thesis: Use TV inheritance wisely – set sensible defaults, override only when necessary, and be aware of cache behaviour.

1. Defining a TV on a Template

In the Manager, create a TV called header with a default value of Welcome. Assign this TV to the Text input type and set the Default Value field to Welcome. Next, add the TV to the Template (e.g., Standard) by dragging it into the TV tab.

When a Resource uses this template, MODX does not physically store the header value in the resource’s TV table. The value is inferred from the template, keeping the database lean.

2. Overriding a TV on a Resource

Open a Resource that uses the Standard template. Navigate to the TVs tab, find header, and change it to Hello. Click Save & Preview. The page now shows Hello instead of Welcome.

Under the hood, MODX creates a new row in modx_site_tmplvar_values linking the resource ID to the TV ID and storing the overridden value. This is a shallow copy: only the differences from the template are persisted.

3. Caching Implications

MODX’s cache layer respects TV inheritance. After overriding header, the resource is cached with the new value. Clearing the site cache via System > Cache > Clear Cache forces a re‑evaluation. If you change the default on the template to Greetings later, resources that never overridden header will still show Hello until you either clear the cache or delete the override row.

To verify cache behaviour programmatically, use:

// In a snippet or template
$header = $modx->getTemplateVar('header', '*', $modx->resource->get('id'));
echo $header;

Run this on a page, then clear the cache via the Manager. The output should still be Hello because the override persists. To see the new default, delete the override row manually or set the TV back to the template value.

4. Trade‑offs and Limitations

• Required TVs: If a TV is marked Required on the template, every resource must override it; otherwise the resource will fail to render.
• Changing defaults post‑deployment: Updating a TV’s default value does not retroactively update resources that rely on inheritance. Manual migration or a custom script is required.
• Performance: A large number of overrides can increase the size of modx_site_tmplvar_values and slightly slow down resource loading, especially if many resources share the same TV.

Concrete Example: Header TV Workflow

1. Create TV header with default Welcome.
2. Add TV to Template Standard.
3. Create Resource About Us using Standard.
4. Override header to Hello on About Us.
5. Publish and preview – page shows Hello.
6. Clear site cache – page still shows Hello.
7. Change template default to Greetings.
8. Publish About Us again – still shows Hello because of override.
9. Delete override row in modx_site_tmplvar_values or reset TV to template value – now shows Greetings.

Actionable Takeaway

When designing a MODX site:

• Set clear, meaningful defaults on templates.
• Override TVs only when page‑specific content is required.
• Document any required TVs to avoid rendering failures.
• Plan for default changes: use a migration script if you anticipate frequent updates.
• Monitor cache clearing as a safety net when adjusting TV defaults.

By following these guidelines, you keep the database tidy, reduce rendering errors, and maintain predictable cache behaviour.