Advanced Symlinks II

Advanced symlink techniques using the forward_merge_excludes System Setting

In the last article we saw how to prevent the field and TV values from the Symlink page from overwriting those of the target page. In this one, we'll look at how to fine tune that process so only some of the values come from the target page.

MODX logo


When I refer to the "Symlink" page (resource), I mean the page designated as a Symlink. Symlinks can be identified in the Resource Tree by their icon: two overlapping folders. When I refer to the "target page (resource)", I mean the resource whose ID is in the Symlink field of the Symlink resource.


As we discussed in the last article, when a user visits a Symlink, they will see the content of the target page, but by default, the URL, template, and most other fields will be those of the Symlink itself, if they are not empty. You can set the symlink_merge_fields System Setting to No, but then *all* fields and TV values will come from the target page, including the id, template, and pagetitle fields. Often, that's not what you want.

A Common Use Case

You might be fine with using all the field values from the target page. You can give it whatever Template you want, but what if you want to use the pagetitle field from the Symlink page? What if you have a Wayfinder or getResources tag on the target page containing a property that uses this tag:?


If you have set the symlink_merge_fields System Setting to Yes (because you want some of the field values from the Symlink page), the id tag will always be replaced with the ID of the Symlink page, not the target page — almost certainly not what you want.

The Solution

The way out of this is to set the symlink_merge_fields System Setting to Yes, but edit the forward_merge_excludes to exclude certain fields from being overwritten with values from the Symlink. The comma-separated list of fields listed in the forward_merge_excludes setting will always come from the target page, even if the symlink_merge_fields System Setting is set to Yes. If, for example, you want the ID of the target page for use in a tag property, simply add ,id to the end of the forward_merge_excludes setting.

You can also include the names of TVs in the forward_merge_excludes setting. That way, you can have the value of some TVs come from the Symlink page, while the ones listed in the forward_merge_excludes setting will come from the target page.

Coming Up

In the next article, we'll look at some reasons why particular resources can't be saved.

For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (3)

  1. Rob HorAug 10, 2018 at 09:47 AM

    Hi Bob,

    I can't get "forward_merge_excludes" to work with template variables. My comma separated list looks something like... pagetitle,longtitle,mytemplatevariable... pagetitle and long title always get their value from the target (no problem) but mytemplatevariable always comes from the Symlink not the target or if the TV is empty in the symlink, doesn't display at all. I know you've studied this in depth (as I have)... Do you happen to know if there's a special format for TVs in the list? - something like; pagetitle,longtitle,tv.mytemplatevariable ??

    Best Regards
    Rob Horn

  2. Bob RayOct 16, 2018 at 05:56 PM

    Sorry for the delay -- Quip never notifies me of new comments. I don't have a good answer. It worked when I tested it with TVs (no prefix, IIRC). I'm afraid I don't have time to test it again right now.

  3. Bob RayOct 16, 2018 at 05:57 PM

    Is the TV connected to both templates (the one for the symlink and the one for the other page)?

Please login to comment.