Glossaries and Filters

Stock phrases

One of the features of computer work, and this is very commonly true with Web pages and even more so when you have to deal with HTML, is that there is a lot of repetitive typing of the same fixed phrases over and over.

Frontier provides a way out of such annoying repetitive labor. (After all, what's a computer for if it doesn't save you from just this kind of busy work?)

This is the Glossary mechanism. You keep a table of text substitutions; when your page is rendered, the substitutions are performed. In effect, you get to make yourself a set of shorthand abbreviations for some stock phrases. The idea is utterly simple; yet it's such a handy tool that you'll use it all the time.

To see an example of the glossary at work, go into myFirstSite.default and, where it says "thanks to Frontier," surround the word "Frontier" with quotes. Now view the page in the browser. The word "Frontier" doesn't appear in quotes in the browser, but it has become a link, leading to the Frontier Web site at scripting.com.

The way this happens is that, at rendering time, Frontier searches for tables called "glossary," and it looks in these for entries whose name matches any quoted material in your Web page.

If it finds such an entry, it substitutes the value of the entry for the quoted material in the page. If it doesn't find such an entry, it just leaves the original quoted material alone. Before it gives up, it looks in user.html.glossary. That's where it found the entry for "Frontier" -- take a look at it.

You can see that user.html.glossary.Frontier has a value which is an <a> tag, the word "Frontier," and the closing </a> tag; this is what eventually made its way into the rendered version of our default page.

You can prevent any particular quoted phrase in your page from being searched as a glossary item by putting a backslash before the first quotation mark. You can also turn off the whole glossary mechanism, for one page or a group of pages, by means of the #expandGlossaryItems directive; this is "true" by default, but you can set it to "false."

Things in angle-brackets (HTML tags) are normally protected from having their contents seen as possible glossary items; things could get pretty crazy otherwise.

Creating glossary entries

Of course you can create glossary items manually; they're just table entries.

You also get a shortcut from within your browser to build glossary entries like "Frontier" and the others already in user.html.glossary.

On a Macintosh, when Frontier is running, the browser has an extra Scripts menu containing an item Add To Glossary, from which you can insert into user.html.glossary a reference to the page you're currently looking at in the browser. (User.html.glossary may not be where you ultimately want to keep the reference, but it is a good initial storage location; you can easily cut and paste the entry to another glossary table later if you like.) You can also use items in the Scripts menu to get quickly to user.html.glossary, and even to see user.html.glossary converted into an actual page of links in the browser.

You may want to add user.html.glossary to your Bookmarks menu, as that's a place you may go often. Jump to user.html, then select the glossary entry, then choose the Add Bookmark command from the Bookmarks menu.

Using glossaries the way you want

You'll doubtless find many uses for the glossary mechanism, since many kinds of boilerplate or repetition are likely to occur throughout your pages. People's tastes and needs vary.

Personally, although I like to use the glossary for link references, I don't always use the mechanism quite the way it's illustrated by the entries at user.html.glossary, because I don't like being restricted to one fixed phrase which is going to appear between the <a> and the </a> tags.

For example, right now the glossary item "Frontier" resolves to a link emanating from the word \"Frontier." It would be nice to have more flexibility about what text the link emanates from.

One solution I used to use is to have a glossary entry for "Frontier" which consists of just the <a> tag, like this:

   <a href="http://www.scripting.com/frontier/">

That way, I can have any phrase I want become a link to the Frontier Web site; of course I have to put in the final </a> myself, but that's no trouble. So, for instance, I might write:

   There is a "Frontier"really cool tool</a> 
   you should know about.

This ends up rendered as a good HTML link.

Now I mostly use a different solution: a macro. I call it glossSub. Here's what it does. Suppose our Frontier glossary entry is the one in user.html.glossary.Frontier. In my page, instead of putting a glossary item (a phrase in quotes), I put a macro. Like this:

   There is a {glossSub("Frontier", "really cool tool")} 
   you should know about.

That ends up saying: "There is a really cool tool you should know about.", with the link to the Frontier site emanating from the words "really cool tool." The first thing in parentheses is the name of the glossary table entry; the second is the text we want the link to emanate from. (This assumes, of course, that the glossary item's value is a link.) You really ought to try this, it's fun!

Go into myFirstSite.default, and where you previously had "Frontier," take it out (including the quotes around it) and in its place put:

   {glossSub("Frontier", "a really cool tool")}

Preview the page. Getting the idea now?

Notice how we've only just learned about glossaries and already we're fiddling with how they work. In setting up the original glossary mechanism, Dave has done what's convenient for him, given the way he works and thinks; I substitute what's convenient for me, given the way I work and think; you'll eventually substitute what's convenient for you. And that's the whole idea! And of course links are far from being the only kinds of things you are liable to write glossary entries for.

Where are the glossaries?

The behavior of the glossary mechanism, in the way it searches for each quoted phrase as a glossary entry, is really special -- nothing else in the Web site management tools acts quite like this. So let's be clear about it, so you can take full advantage of it!

First, your page can have a special glossary of its own. This can be anywhere in the database. Just use a #glossary directive in the page:

   #glossary "people.MAN.mySpecialGlossary"

Next, we look for a glossary table in the same table as the page we're rendering. Then in the table that contains that, and so on. And we always look in user.html.glossary last. So, if myFirstSite has a sub-table called someFolder, and you're rendering a page in it called myPage, which has the #glossary directive above, then for each glossary item in myPage:

• First we look in people.MAN.mySpecialGlossary
• Then we look in websites.myFirstSite.someFolder.#glossary (if there is one)
• Then we look in websites.myFirstSite.#glossary (if there is one)
• Then we look in websites.#glossary (if there is one)
• Then we look in #glossary -- hey, this is getting silly...
• Ultimately we look in user.html.#glossary

As soon as we find the item we're looking for, we stop looking and perform the substitution. You can use this to give glossaries the same hierarchical object-oriented power as directives and images.

Glossaries and macros

At this point a word is in order about the relationship between glossary items and macros.

Perhaps you noticed while doing the Images exercise that typing the imageRef call was rather a pain. If you wanted to include the same imageRef call at several places in your page or site, things might become particularly trying.

This comes up for me all the time, such as when I have a list of items and some of them are marked with a little GIF that says "new" or "cool." I don't want to have to write a whole imageRef call for every occurrence of this GIF; I want to just put "new" or "cool" and have the glossary put the imageRef call in for me.

Fortunately, you can put macros in glossaries. Glossary entries are evaluated first, then macros.

You'll have to see this for yourself. Go into the template, and select the entire imageRef call, including the curly braces at both ends.

Cut, and now type "ourLogo," including the quotes, thus replacing the call with the quoted phrase. Open myFirstSite.glossary (ignoring anything that may be in there; I'll explain all that later), and from the Table menu use New Scalar to create a new String.

Call the string "ourLogo" (without the quotes), tab into its value, and Paste (and hit Enter to set it). Now go to any page, such as myFirstSite.default, and view it in the browser. Voila! The logo appears.

Filters

You probably didn't know you had any Filters, but you do; look in myFirstSite.#filters and you'll see there are three. They're all scripts.

FirstFilter is called first, before much happens. The page table has been built, but no other parts of the rendering process have yet happened.

PageFilter is so that you can do things to your page before it has been embedded into its template; it is called after directives in your page have been processed but before anything else has happened, and you are expected to modify an object called html.data.adrPageTable^.bodytext as desired.

FinalFilter is called at the end of the rendering process, and you are expected to modify an object called html.data.adrPageTable^.renderedtext.

By default, firstFilter doesn't do much: it just returns. Pagefilter makes the first letter of your page larger than all the others, and helps build your glossary to prepare it for use of the glossPatch mechanism (that's how all those entries got into your glossary; I'll explain about the glossPatch mechanism later). Finalfilter doesn't do anything. But that's just the defaults: you can modify your filters as you choose.

Another filters thing

You might want to modify pagefilter so that it doesn't make the first character of every page large any more. To do so, just select the third line, the one that starts "try," and choose Toggle Comment from the Outliner menu. (And hit the Compile button.)

Don't worry; making the first character of every page larger was just put there as an example of the kind of thing Frontier's pagefilter can do. You're expected to customize this routine.