Up and Running with Frontier Web Site Management
by Matt Neuburg
Author of the book Frontier: The Definitive Guide
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. You can rearrange the site, but relative references among the pages will still work.The basis of the glossPatch mechanism is the glossary items that are automatically generated for each page in the site. You can see them if you examine myFirstSite.#glossary. Notice the entries which, instead of having string values, are subtables with a "linetext" entry and a "path" entry.
These are the glossPatch glossary items. They are generated automatically by the pageFilter every time you render a page, thus keeping them up-to-date on an ongoing basis.
However, they can also be regenerated on command; and this is often a good idea, because if you simply publish the whole site, the glosspatch glossary entry for a particular page may not be generated until after it is needed by some other page (and so, relative links will break).
In fact, things have probably gotten so messy in your glossary that it no longer reflects the actual state of your site. It is up to you to clean it out from time to time. So let's rebuild it.
Carefully select and delete all the glossPatch glossary items -- I say "carefully" because you don't want to delete glossary entries that you created yourself, like ourLogo.Now select the #glossary subtable itself, and choose Build Glossary from the Web menu. You will see three glossPatch glossary entries appear, one for each of the publishable pages in your site.
Now you can make relative references from one page to another. As you can see, each glossPatch glossary entry has, as its name, the #title of a Web page. You use that title as a glossary reference in order to make a link to that page.
For example, suppose we wish to make a relative reference in our default page to fourthPage. We could say something like this:
If you want to see a table, take a look at "The Planets".When you render the default page, the glossary reference "The Planets" is found to correspond to a glossPatch glossary entry, and accordingly, a #glossPatch expression is substituted for it in your page. (I mean, in the copy of your page that the rendering engine is working with; I don't mean to imply that the rendering engine would ever alter your original Web page object!)
A #glossPatch expression is a curious-looking animal. The one that will be substituted into the default page will look like this:
If you want to see a table, take a look at [[#glossPatch The Planets|someFolder/fourthpage.html|]]That, however, is obviously not the end of the story! Towards the very end of the rendering process, this #glossPatch expression in your page will be replaced by a nice HTML relative reference -- if, that is, the directive #useGlossPatcher is true (as, by default, it is). If you refer to a glossPatch glossary item 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!
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:
[[#glossPatch The Planets|someFolder/fourthpage.html|]]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 "The Planets" and "someFolder/fourthpage.html". If you look at the glossPatch glossary entry, you will realize that these are simply its "lineText" and "path" entries, respectively.
The lineText, "My Fourth Page", is the text that will appear in the browser, as a link. The path, "someFolder/fourthpage.html", tells where to link to. It says that the link should be to a file called fourthpage.html which is itself in a subfolder someFolder within the site folder.
When the #glossPatch expression is resolved, the clever stuff happens. The rendering engine knows where the page currently being rendered is going to live in the site folder; the #glossPatch expression tells it where the page being linked to is going to live in the site folder; so it can work out a relative URL from the one to the other!
You should now be able to understand what is so clever about the glossPatch mechanism. Suppose that the default page contained a hard-coded relative link to fourthPage. Then if either the default page or fourthPage were moved into a different subtable within the site table, that link would break.
Instead, what the default page contains is just the #title of fourthPage -- something that will presumably never change. Whenever fourthPage is rendered (or when you choose Build Glossary), the glossPatch glossary entry for fourthPage is updated, so it correctly states where fourthPage will end up in the site folder. Then, when the default page is rendered, that information is obtained from the glossary, used to create a #glossPatch expression, and finally, based on the default page's location in the site folder, a correct relative link is generated.
You should now also understand why the Build Glossary menu item is useful. Suppose you moved fourthPage from one subtable of the site to another and immediately published the whole site. The default page might be rendered before fourthPage, so it would be rendered before fourthPage's glossPatch glossary entry has a chance to update automatically. So its relative link to fourthPage wouldn't be correct.
Building the glossary before publishing the whole site ensures that this won't happen. In certain very advanced situations, though, it will actually be necessary to publish the whole site twice in order to get all the relative links to resolve themselves correctly.
We now face a problem that is just the same as one we faced earlier, in dealing with glossary entries that are hard-coded links. When you insert into the default page this line:
If you want to see a table, take a look at "The Planets".then when you release the site, default.html will contain the phrase:
If you want to see a table, take a look at The Planets.where those last two words, "The Planets", 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?
Just as the problem is the same as before, so is the solution. Guess what? It's glossSub again! GlossSub works for glossPatch glossary entries as well as hard-coded link glossary entries.
So all you need to do is say:
If you want to see a table, I've got {glossSub("The Planets", "a great page")} that contains one.By the same token, if you want the link to emanate from an image, you can make the second parameter a call to imageRef:
If you want to see a table, click this picture {glossSub("The Planets", imageRef("site"))} to see one.
We have already observed that in the automatically generated glossPatch glossary entries, the entry name is, for any given page, the page's #title.On the one hand, this frees you to relocate pages within your site. You can also rename the page obects.
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.
And, every page #title must be absolutely unique within the entire Web site, or one page's glossPatch glossary entry will overwrite another's.
All text is by Matt Neuburg, phd, matt@tidbits.com.
For information about the book Frontier: The Definitive Guide, see my home page:
http://www.tidbits.com/matt
All text copyright Matt Neuburg, 1997 and 1998. ALL RIGHTS RESERVED.
No one else has any right to copy or reproduce in
any form, including electronic. You may download this material but you may not post it for others to
see or distribute it to others without explicit permission from the author.
Downloadable versions at http://www.ojai.net/matt/downloads/webTutorial.hqx and http://www.ojai.net/matt/downloads/webTutorial.zip.
Please do not confuse this tutorial with a certain other Frontier 5 tutorial based upon my earlier work.
This page created with
Frontier, 2/11/2000; 7:00:02 PM.