Site Outline and NextPrev

Navigational aids

It is common experience that providing readers with a good repertoire of ways to navigate your site easily and intuitively can be crucial to their experience of your Web material.

Two common aids to navigation are the site outline, where you give a table of contents whence readers can link to any page of the site, and "Next" and "Prev" links which let readers click to proceed or go back through a linear arrangement of your site. Frontier provides tools that make it easy to create both of these kinds of navigational aid.

Site outline

Let's learn about the site outline feature first. Go into myFirstSite.default and add, at the end, a line which says:

   {outlineSite ()}

Publish the whole site, and examine default.html in the browser. You can see that links to all the other pages have been added, which is quite nice.

What's more, outlineSite is so clever that it looks in subtables, considers them to represent subfolders of your site, and makes sub-list entries for their contents.

Also, outlineSite properly ignores the tools, glossary, and images tables: it only catalogs the part of the site that will actually be rendered.

Now, the truth is that we aren't yet getting our money's worth out of the outlineSite macro; it is even cooler than we think. With outlineSite, we get to include a #subtext directive in each page; these will become descriptions in the outline. Try it out. To secondPage, add a line at the start which is something like this:

   #subtext "Illustrating how to embed an outlined list."

And to fourthPage, add a line at the start which is something like this:

   #subtext "Shows how to make a table out of an outline."

Now publish the whole site again, and view default.html in the browser. Cool, eh?

Here are some final considerations on OutlineSite. First, you get some directives we haven't used. #siteOutlineHeadFont is where you give an entire <font> tag for the titles of the pages; for instance, the default is <font face="geneva,arial" size=-1>. If this seems like too much for you, then don't use it; just let the default take over. #siteOutlineSubtextFont works similarly.

Also, #siteDefaultName lets you state the name of the default page. If you don't give this directive, the #defaultFileName directive (or the setting in user.html.prefs.defaultFileName) is used. Neither the stated default page nor the page we are actually rendering (if they are different) are included in the list.

Another thing is that you can hand outlineSite an argument so that it outlines a particular table rather your whole site. If you say:

   {outlineSite (@websites.myFirstSite.someSubTable)}

then only the things in the someSubTable table will be listed.

Further arguments let you describe the resulting layout: the width (in pixels) of the resulting table, and how big (in pixels) each indentation level should be. To outline your whole site with designated values for these, you could say:

   {outlineSite (maxWidth:200, indentPixels:5)}

A slight infelicity of outlineSite is that it sorts the page names alphabetically by #title. This may not be what you want. I presently use a couple of solutions which are rather crude, but effective.

One is that I render a page with outlineSite, just to get the HTML. I go into the actual HTML with a word-processor, copy it all out, and paste it into a Frontier outline. Now I can rearrange the outline, and then embed it (rendered with "newculture") into a page, using renderObject. Another method is that I include numbers at the start of my titles, to order them.

Another way, of course, is to write your own macro which does the sort of thing outlineSite does, but customizes it to suit your tastes. After you learn UserTalk you'll see this as a perfectly do-able challenge!

Previous and Next links

Now let's test out the NextPrev mechanism. The first step is to let Frontier make a list of your pages in an outline, so you can arrange them in the desired order; that's how Frontier will know what counts as "next" and "previous" for each page.

From the Web menu, choose Build NextPrev List. Frontier now forces you to type the full name of your site table, which may seem rather silly, especially since you're probably right there in the table; but go ahead and type websites.myFirstSite (warning: in this case it is crucial that you get the capitalization of the name right, so that it matches the actual table name perfectly), and click OK.

You are presented with an outline showing all your site's pages.

There may also be some pages listed that don't exist at all in your site; for some reason, this routine thinks you want a "default" entry for every subtable in your site. Just delete these if they don't correspond to anything real. If they do correspond to something real, you may have to correct the capitalization for them. For example, if your site is "myFirstSite" and the default.html entry ends "myfirstsite.default," you must fix this manually to say "myFirstSite.default" or things won't work later on. Sorry about all this.

Okay, the painful part is over. Now for the fun part.

Arrange the list of pages in the desired order, which in this case I suggest should put secondPage in the middle.

Now go into #template and put in a line just before the {bodytext} line that says:

   <p>{linkPrev ("Previous")} | {linkNext ("Next")}</p><hr>

The syntax here is fairly obvious. We are creating two macro calls; the material in quotes is the text that will actually appear in the browser, and that text will be turned into a prev link or a next link by the appropriate macro.

Finally, create a new String entry in the #prefs table of the myFirstSite table, where you set the #useGlossPatcher directive to "true" (without the quotes). This is absolutely essential; the NextPrev mechanism will not work unless #useGlossPatcher is true, and you don't want to take any chances that it is false at some other level of the directive/preference hierarchy.

Now publish the entire site (you may need to publish twice), and look at default.html in the browser. Click the "Next" link repeatedly to cycle through the pages of your site. You now have quite a sophisticated little site; I'll leave you to play with it for a while.

Images instead of words

You probably are already dreaming of modifying the NextPrev mechanism to make it even cooler. For instance, a common question is how to make the "next" and "prev" links be from clickable graphics instead of text. It's easy; you've probably already guessed how to do it.

Suppose you have two images, called "prev" and "next." You would think that this might work:

   {linkPrev (imageRef ("prev"))}
   {linkNext (imageRef ("next"))}

For instance, the left and right arrows at the bottom of this page are generated by these two lines:

   {linkPrev (imageRef ("previous", "Previous"))}
   {linkNext (imageRef ("next", "Next"))}

Room for improvement

You can probably think of lots of ways you'd like to customize this whole mechanism.

For instance, you probably think that the cyclical arrangement of the links isn't right (where the last page leads to the first, and vice versa). You'd probably prefer to prevent the "next" and "prev" links from being active if there is no next or previous page.

This isn't hard to implement with a finalfilter routine, or by creating modified versions of the linkNext and linkPrev macros, but you're going to have to script Frontier in order to do it, so this tutorial is not the place to discuss the matter further. Still, I hope you're drooling over the possibilities.