Links to the Next and Previous Page

A common problem in a Web site is forming navigation links, especially to the next and previous pages in a series. RubyFrontier doesn’t exactly solve this for you; but it does give you the tools you need to construct solutions for your particular Web site structure and navigation needs.

Page Order and the NextPrevs List

The chief issue here is that the order of page objects within a folder, which is alphabetic, is rarely the order in which you want navigation of the Web site to proceed. It is therefore necessary to maintain a separate file, called by convention #nextprevs.txt (and known as the nextprevs list). Because this file’s name starts with a pound-sign, it is treated as a directive object and is not rendered as a Web page. The purpose of the file is simply to list pages in their proper navigation order. That way, a macro that forms navigation links can consult the list to figure out what to do.

The members of the nextprevs list should be identifiers suitable for lookup in the autoglossary. That way, you can use further method calls to form the actual links. For example, the nextprevs list for the folder containing this page looks like this:

  images
  outlinerenderers
  snippets
  template
  macros
  autoglossary
  glossary
  filters
  pageheader
  stylesheets
  standardmacros
  nextprevs
  xrefs
  user

If you examine this page, you can see the nextprevs list being used. The second navigation bar at the top of the page consists of the titles of the pages in this folder, in exactly the order of the nextprevs list. And at the bottom right of the page is a “next” link; since this page is the one coded as nextprevs, the “next” page should be the one coded as users, and so, indeed, it is.

This solution is far from ideal, but I haven’t found a better way. The main drawback with this approach is that it requires you to remember to maintain this separate list. If you add or remove a page from the source folder, you need to add or remove it from the nextprevs list. It is easy to forget to do this.

Use of the NextPrevs List

No rules tell you how to use a nextprevs list; indeed, no law requires that you use one at all. You can handle navigation in any way that suits you. Nor need a nextprevs list be structured like the one shown above. It is up to you to come up with a system, and to write a macro that will read the list and return the desired information.

RubyFrontier does provide one built-in method for forming navigation links. In this approach, it is assumed that navigation to the next and previous page takes place always within a single folder. The built-in method, which you can call in a macro by saying html.getNextPrev(), forms a list of all the files in the same folder as the file currently being rendered. The list is simply the folder’s nextprevs list if there is one (or, the files in alphabetical order if there is not). It then returns an array of two items — the members of the list just before and after the page currently being rendered (or nil if the page currently being rendered is first or last in the list). You could then use these values as keys into the autoglossary to form links.

Another helpful method, mentioned earlier, is html.getTitleAndPaths() (also known, for legacy reasons, as html.getTitleAndPath(), in the singular). It takes as parameter an identifier that keys into the autoglossary and returns an array providing the title and pathname of that page. For example, at the bottom right of this page is a link to the next page in the nextprevs list, which, as you can see, is xrefs. But the link does not say “xrefs”; it says “Next: Cross-References and Auto-Numbering”. The text of the link was formed by calling html.getTitleAndPaths to obtain the title of the xrefs.txt page object.

The New Site model site that comes with RubyFrontier demonstrates a simple approach based on these two macros. It puts a Prev link and a Next link at the bottom of each page, by calling this macro in the template:

def nextprevlinks()
  p, n = html.getNextPrev(adrObject)
  ntitle, npath = html.getTitleAndPaths(n) if n
  ptitle, ppath = html.getTitleAndPaths(p) if p
  s = ""
  s << "Prev: " + html.getLink(ptitle, ptitle) if p
  s << " | " if p and n
  s << "Next: " + html.getLink(ntitle, ntitle) if n
  "<p>#{s}</p>\n"
end

Observe that we can use the title of the target page not only as the visible text of the link but also as the href of the link, because it will be turned into a relative URL for us by the autoglossary mechanism. We could equally have used p and n themselves as identifiers to form the href for these links.