Relative References

GlossPatch

In the previous exercise, we had to make sure the glossPatch mechanism was turned on, which we did with the #useGlossPatcher directive.

The glossPatch mechanism is an ingenious device for making relative references between pages in your site. This is useful because relative references are efficient as well as portable, in case you change your site's URL. It is useful also because Frontier maintains your relative references for you.

There are several parts to the glossPatch mechanism.

First, go into the glossary subtable. Notice the entries that are actually small, two-item tables. These are generated automatically every time you render a page.

In fact, things have probably gotten so messy in your glossary that it no longer reflects at all the actual state of your site. It is up to you to clean it out from time to time, so let's practice.

Mind your glossary

Carefully select and delete all the glossary entries that are actually tables -- I say "carefully" because you don't want to delete glossary entries that you put there yourself, like ourLogo. Now publish the whole site (being careful not to start from within the glossary table!). Now look at the glossary again. You should see just two table entries entries now, one for secondPage and one for fourthPage.

(While publishing your whole site is one way to re-build your glossary, there's another, easier way. Select your #glossary table and choose Build Glossary from the Web menu. It will make sure your relative glossary entries -- the kind we're talking about here -- are up-to-date.)

These entries are generated automatically, for each page, by the pagefilter. If you were to go into the pagefilter, see the line:

   html.addPageToGlossary (adrPageData)

and hit control-backslash to comment it out, automatic generation of these special glossary entries would cease.

The reason for this automatic generation of glossary entries is so that you can make relative references. Once these special glossary entries exist, then if you wanted to make a reference in secondPage to fourthPage, you could say something like this:

   If you want to see a table,
   take a look at "My Fourth Page".

What happens when you write this? Frontier will convert "My Fourth Page" into an elaborate-looking #glossPatch entry -- which you'll probably never see. It's just for Frontier's benefit, a machine-readable form of a relative glossary entry.

Then, at the very, very end of the rendering process, the #glossPatch expression in your page will be replaced by a nice HTML relative reference -- if, that is, #useGlossPatcher is true. If you refer to one of these #glossPatch glossary items in a Web page and #useGlossPatcher is false, the #glossPatch expression will just sit there in your final HTML like a bump on a log!

Anatomy of a glossPatch reference

Let's see how the glossPatch interpreter does its work. This requires that we understand the anatomy of a #glossPatch expression, which is really not that complicated. Consider, for instance, the automatically generated expression for fourthPage:

In the glossary, fourthPage is a table with to elements: linetext, and path. The linetext is the title and the path is relative to the root of the site (and including the file extension).

When this glossary item is looked up, Frontier translates it to this:

   [[#glossPatch My Fourth Page|fourthPage.html|]]

To remind you: you'll probably never see the above as you work on your web sites, but it doesn't hurt to know what's going on behind the scenes.

The "[[" and "]]" are just delimiters, and the "#glossPatch" says that this is a #glossPatch expression.

What's left is two expressions marked off by those little vertical "pipes," namely "My Fourth Page" and "fourthPage."

The first, "My Fourth Page," is the text that will appear in the browser, as a link.

The second, "fourthPage.html," tells where to link to. Since the word "fourthPage.html" just appears by itself, this means that fourthPage.html is at the surface level of your site, in its main folder.

On the other hand, if fourthPage.html were going to appear in a subfolder called "sub," then the automatically generated expression would look like this:

   [[#glossPatch My Fourth Page|sub/fourthPage|]]

Why are these references generated automatically? So that you can rearrange your site and have your references to those pages still work! Suppose you moved fourthPage into a subtable. If the glossary item "My Fourth Page" were hard-coded, for instance as:

   <a href="fourthPage.html">My Fourth Page</a>

then when you rebuilt the site, the link that replaced any use of "My Fourth Page" would break.

With the glossPatch mechanism, this is not so. The pageFilter makes a new set of glossary items, so now "My Fourth Page" will correctly be linked to fourthPage, without your changing anything in your pages. (You might, however, have to publish the whole site twice to get everything caught up, as it were.)

Customizing glossPatch references

When you insert into secondPage this line:

   If you want to see a table,
   take a look at "My Fourth Page".

then when you publish the site, secondPage.html will contain the phrase:

   If you want to see a table,
   take a look at My Fourth Page.

where those last three words, "My Fourth Page," act as a link to fourthpage.html. This is all very well, but what if you wanted to say:

   If you want to see a table, 
   I've got a great page that contains one.

where the words "a great page" are supposed to be the link to fourthpage.html? Clearly what you want in your page at the end of the rendering process, when the glossPatch calls are about to be interpreted, is this:

   [[#glossPatch a great page|fourthPage.html|]]

How can you cause this to happen? One answer is that you could just write this expression into the page yourself, secure in the knowledge that at the end of the rendering process it would be turned into a nice relative link to fourthPage.html emanating from the words "a great page." Nothing stops you from writing your own glossPatch calls.

But this is not as powerful a solution as you would ideally like. The expression contains, hard-coded, the premise that fourthPage.html sits at the top level of your site. But the whole idea of the glossPatch mechanism is that you can re-organize your pages without your relative references breaking.

If you now created a subtable called "sub" and moved fourthPage into it, this reference would break. And yet, the mechanism that generates glossPatch glossary entries would have modified the entry for "My Fourth Page" accordingly:

   [[#glossPatch My Fourth Page|sub/fourthPage.html|]]

What a waste! The automatic glossary entry generation mechanism is chugging away, keeping track of the organization of your site, and you're not taking advantage of it, so your hard-coded glossPatch calls are breaking!

The solution, of course, is a macro. And guess what? We've already written it. The glossSub macro we wrote earlier works on glossPatch glossary items too! That's why it's so long and complicated: it has to handle both <a>xxx<a> glossary items and glossPatch glossary items.

So now all you need to do is say:

   If you want to see a table, I've got 
   {glossSub ("My Fourth Page", "a great page")} 
   that contains one.

Final points

We have already observed that in the automatically generated glossPatch glossary entries, both the entry name and the text that will be linked from are, for any given page, the page's #title. On the one hand, this frees you relocate pages within your site. You can also rename the entries that contain the pages.

But if you change the #title of a page, any references to that page via its automatic glossary entry will break. So choose your page titles very carefully, because you are going to be locked into them -- as the price of not being locked into one particular location for each page.

Note: a number of users of long standing have found that the glossPatch mechanism gives them bad URLs in the resulting HTML, something that starts "/../../../" or the like. If this happens to you, it's because you're using a "remote" #ftpSite entry - that is, the #ftpSite entry in your site table isn't a table, as described in this tutorial, but the name of a table in user.html.sites.

The glossPatch mechanism is not compatible with remote #ftpSite entries, and indeed now that directives are no longer hierarchical there is probably no good reason to be using remote #ftpSite entries at all. Make the #ftpSite entry in your site table a table, such as is generated by the New Website command, and all will be well.