The base href Tag
The base href tag is used by browsers to resolve all relative URLS in a web page. Technically, it can be referred to as the "Document Base URL Element," though you will almost never see it referred to that way. In fact, the actual element is the <base> element — the href part is actually an attribute of the <base> tag.
There can be only one <base> tag on a page. If there is more than one, only the first will be used and the rest will be ignored.
Every <base> tag must have an href attribute, which is why it's often referred to as the base href tag. The <base> tag can also have a target attribute, but I have never seen it used in the MODX Revolution base href tag.
In non-MODX HTML code, a typical base href tag will look like this:
<base href="https://mysite.com/">
If the page is at the root of the site, it might look like this:
<base href="/">
In MODX Revolution, there is a standard base href tag that is used on every page, as we'll see in the next section.
The base href Tag in MODX
As you probably know, links to pages on your site should always be in the form of link tags:
<a href="[[~12]]">Some Page</a>
In the example above, 12 is the ID of the resource you want to link to. The ID is shown in parentheses next to the pagetitle in the Resource tree at the left of the Manager. By using link tags, you can move your site to a new server, reorganize, or rename the pages and all the links will still work. For this to work correctly, though, you need a base href tag like this in the head section of all templates:
<base href="[[!++site_url]]"/>
The tag should be called uncached (note the exclamation point). This prevents external links to your site from leading to an incorrect URL if the site is moved to another server or restructured.
Be sure to use a short tag for the base href statement. Using a closing </base> tag will often cause problems.
When MODX generates the URL for a page, it will prefix it with the site URL (e.g., https://yoursite.com/). Although the tag above is a Setting tag, there's typically no System Setting with that key. MODX generates the setting based on the URL the user used to access the site. If you have multiple front-end contexts, though, you'll want to create a site_url Context Setting for each of them. In that case, MODX will use the value for the current context rather than generating it from the URL.
Things to remember
- Every template should have the standard
base hreftag near the top - Always include the exclamation point
!to make thebase href taguncached - Always use a "short tag" like the one above for your
base hreftag - Never close the
base hreftag with</base> - Because the
base hreftag is in every template, you never need to put it in the code of a resource
Exceptions
In spite of the advice above, you should not put a base href tag in the "empty" template, or any other special-purpose template that's not used to display MODX resources.
Coming Up
In my next article, we'll look at the MODX Constants and how to use them produce URLS on your MODX site in both Resources and PHP code.
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.