Up and Running with Frontier Web Site Management
by Matt Neuburg
Author of the book Frontier: The Definitive Guide

Prev | TOC | Next


Includes and Macros

Pages within pages

Our discussion of outlines and outline renderers may have caused you to wonder as follows: "Clearly outlines can do wonderful things for me if my entire Web page consists of only one type of entity. For instance, the default outline rendering is great if my whole Web page is a bulleted list. But how does it help me include a bulleted list as part of a larger page? The table outline renderer is cute, but usually I don't want an entire page consisting of nothing but a single table, do I? So what should I do? I can't change outline renderers in the middle of the outline, can I? And what if I want to use wptext for my page, but put an outline-based list into it?"

The solution lies in the use of an "include" mechanism. Frontier lets you embed the rendering of one Web page inside another.

To see how this works, let's go back to our thirdPage, the one with the list of things to do. Remove the #title and the #renderOutlineWith directives from it; it doesn't need a title, since we're going to embed it in another page, and it doesn't need a #renderOutlineWith directive because we want the default outline renderer.

Now go into secondPage and add, at the end, the following (get it exactly right):

{renderObject(@websites.myFirstSite.thirdPage)}

Now preview secondPage in the browser. Not bad, eh?

The syntax here is {renderObject(@xxx)}, where for "xxx" you substitute the exact full name of the database entry you want to include. Do not forget any of the pieces, especially the "@", or nutty things will happen.

When, as in this case, the thing we want to include is somewhere within our site table, a somewhat more flexible way of saying the same thing is like this:

{renderObject(@adrSiteRootTable^.thirdPage)}

This has the advantage that it works in any Web site table. We could rename the "myFirstSite" table, or cut it and paste it to somewhere else within the "websites" table, and our reference to thirdPage would still work (as long as there is an item called thirdPage at the root level of our site table).

You can perform an "include" with any kind of Web page; you can include anything in anything with fairly reasonable results. Clearly you can use this mechanism not only to combine one kind of Web page with another (like putting an outline list into a wptext-based page as above) but also to manage boilerplating.

For instance, you might have a large legal paragraph which you use at various points throughout many of your pages. If that paragraph were embedded at each occurrence with this "include" mechanism, then if the paragraph were to change, you wouldn't have to do a find-and-replace; you would just change the database entry representing the paragraph, and render the site anew.

Macro syntax

The syntax of the {renderObject(@xxx)} command, with curly braces, is that of a macro. A macro is just a line of UserTalk. A macro call is rendered by "running" the UserTalk line (that is, evaluating it or obeying it or however you like to envision these things) and replacing the macro call with the result.

For example, if you put {3 + 4} in your Web page, it will be replaced by 7, because "3 + 4" is a valid UserTalk line, and when Frontier "runs" that line, the result is 7.

If you put {user.prefs.name} in your Web page, it will be replaced by your name, because "user.prefs.name" is a valid UserTalk line telling Frontier to fetch the value of the database object user.prefs.name.

In the case of {renderObject(@xxx)}, we are using a line of UserTalk which says tells Frontier to find a script called renderObject living in the database and hand it @xxx as a parameter, and run it.

Facts about macros

You can write your own macro scripts once you learn how to program in UserTalk; you can store those scripts anywhere in the database, but there are some commonly used places because of the way Frontier looks for database entries referred to in a macro call.

Here's the rule. If, in a macro call, you refer to something in the database, then Frontier will look first in the #tools table associated with the Web page being rendered, then in user.html.macros, then in html.data.standardMacros, and finally in the scratchpad table containing the current directive definitions. If none of that works, it looks in the database as a whole.

So, if you want to store a macro where just this page will see it, store it in the #tools table (other pages of the site associated with the same #tools table will be able to see it too, of course). If you want to store a macro where every page you ever render will see it, store it in user.html.macros.

html.data.standardMacros is where UserLand keeps macros that every page should be able to see. That's where renderObject lives; pageheader and pagefooter live there too -- you remember them, they appeared in the default template, and they too were enclosed in curly braces, because they too are scripts being executed through a macro call.

The scratchpad directives table (which is usually websites.#data) is consulted so that directives can easily be accessed as part of a macro call. We saw an example of this already; when our template said:

{pageheader(title)}

pageheader is a script in html.data.standardMacros, but "title" is the name of an item in the scratchpad directives table (look in websites.#data, you'll see the title of the last Web page you rendered). We'll talk more about this later when we learn about custom directives.

By the way, all this means you can't use curly braces in your Web page, because if you do, Frontier will think you mean this as a macro, and will try to interpret what's in the curly braces as a line of UserTalk! Of course, there's a way out; if you need to use curly braces as literals, just put a backslash before the opening (left) curly brace.

Also, Frontier won't see as macros things that are within quotes (literal strings) or angle-brackets (HTML tags): the rendering process figures that such things are sacred, and protects them. (On the other hand, you can turn off this protection by putting a backslash before the first quote or the first (left) angle-bracket.)

What's in the curly braces can be any UserTalk expression. It doesn't have to be a call to execute a script, though it often is. So even if you know just a little UserTalk, you can get Frontier to "calculate" some text without writing a whole script to do it. What time was it when we rendered this page?

This page was rendered at {clock.now()}.

What's the square root of 2?

The square root of 2 is {trigCmd.sqrt(2)}.

Is this making you want to learn UserTalk?

Yes, it's {1==1}, 
I wish I knew {nameOf(root[sizeof(root)-2])}talk.


Prev | TOC | Next

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; 6:59:58 PM.