Advanced Symlinks I

Advanced Symlink options using the forward_merge_excludes System Setting

This article, and the next one, were inspired by the investigations of MODX Forum user Rob Horn (robh76). Symlinks pull the content of the target page (the page whose ID is in the Symlink's Symlink field) into the Symlink. However, in many cases, the other fields of the target resource will be overwritten with those of the Symlink. You may not want that, and in this article and the next one, we'll look at some ways around that.

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 (content) field of the Symlink resource.


As we discussed in a previous 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. Say, for example, that you have a Symlink with 12 in the 'Symlink' field of the Symlink resource (which you'll recall is actually stored in the 'content' field of the Symlink resources in the database). When a user visits the Symlink, they will see the Symlink's template and URL, but they'll see the Resource Content field of Resource 12. Most other non-empty fields will be taken from the Symlink itself. If you put tags like the following ones in Resource 12's Resource Content field, those tags will be replaced by the values from the Symlink page, not from resource 12, if those fields of the Symlink are not empty:

<p>ID: [[*id]</p>
<p>LongTitle: [[*longtitle]]</p>
<p>Summary: [[*introtext]]</p>
<p>Description: [[*description]]</p>


First, the values from the target page will always be used if the corresponding field of the Symlink page is empty. Of course the id, template, and pagetitle fields will never be empty, so their values will always come from the Symlink page unless you do something to avoid that (more on this later).

There are two other kinds of exceptions to the rule that the values always come from the Symlink field. I'll call them "internal" and "external" exceptions.

Internal Exceptions

These are hard-coded into the modX class. These fields will always come from the target page:

  • 'content'
  • 'pub_date'
  • 'unpub_date'
  • 'richtext'
  • '_content'
  • '_processed'

You can't change these without hacking the MODX core code (strongly discouraged). Luckily, it's very unlikely that you'd want to change these.

External Exceptions

These come from the forward_merge_excludes System Setting. That means you can change them. By default, they are:

  • type
  • published
  • class_key

Tip: You can find the System Settings discussed in this and the next article by going to System (gear icon) -> System Settings on the Manager's top menu, putting merge in the search box at the upper right and pressing Enter

Preventing the Overwrite

The URL will *always* be that of the Symlink page. If you don't want that, you have to use a Weblink rather than a Symlink.

If you want to use some values from the target resource, such as longtitle, introtext, description, or any TV, you can just make sure that those fields are blank on the Symlink page. For the TVs, you can leave their value empty (make sure that Allow Blank is set for that TV). As an alternative, you can make sure the TVs are not attached to the template of the Symlink page. You might think this would cause trouble, but it doesn't. MODX will just grab the value of the TV from the target page.

If you want all the values (except the URL) to come from the target page, you can change the symlink_merge_fields System Setting from Yes to No. Once you've done that all values (including the template) will come from the target page.

Coming Up

Setting the symlink_merge_fields setting to No won't always give you what you want. You may want to use the Symlink page's template and pagetitle, but get some other field values from the target page, for example. We'll see how to do that in the next article.

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 (0)

Please login to comment.