11.4 Pagetree
| (require pollen/pagetree) | package: pollen |
Books and other long documents are usually organized in a structured way — at minimum they have a sequence of pages, but more often they have sections with subsequences within. Individual pages in a Pollen project don’t know anything about how they’re connected to other pages. In theory, you could maintain this information within the source files. But this would be a poor use of human energy.
Instead, use a pagetree. A pagetree is a simple abstraction for defining & working with sequences of pagenodes. Typically these pagenodes will be the names of output files in your project.
“So it’s a list of web-page filenames?” Sort of. When I think of a web page, I think of an actual file on a disk. Keeping with Pollen’s orientation toward dynamic rendering, pagenodes may — and often do — refer to files that don’t yet exist. Moreover, by referring to output names rather than source names, you retain the flexibility to change the kind of source associated with a particular pagenode (e.g., from preprocessor source to Pollen markup).
Pagetrees can be flat or hierarchical. A flat pagetree is just a list of pagenodes. A hierarchical pagetree can also contain recursively nested lists of pagenodes. But you needn’t pay attention to this distinction, as the pagetree functions don’t care which kind you use. Neither do I.
Pagetrees surface throughout the Pollen system. They’re primarily used for navigation — for instance, calculating “previous,” “next,” or “up” links for a given page. A special pagetree, index.ptree, is used by the project server to order the files in a dashboard. Pagetrees can also be used to define batches of files for certain operations, for instance raco pollen render. You might find other uses for them too.
11.4.1 Making pagetrees with a source file
A pagetree source file either starts with #lang pollen and uses the .ptree extension, or starts with #lang pollen/ptree and then can have any file extension.
Unlike other Pollen source files, since the pagetree source is not rendered into an output format, the rest of the filename is up to you.
Here’s a flat pagetree. Each line is considered a single pagenode (blank lines are ignored). Notice that no Pollen command syntax nor quoting is needed within the pagetree source:
#lang pollen index.html introduction.html main_argument.html conclusion.html
And here’s the output in DrRacket:
'(pagetree-root index.html introduction.html main_argument.html conclusion.html)
Keeping with usual Pollen policy, this is an X-expression. The pagetree-root is just an arbitrary tag that contains the pagetree.
Upgrading to a hierarchical pagetree is simple. The same basic rule applies — one pagenode per line. But this time, you add Pollen command syntax: a lozenge ◊ in front of a pagenode marks it as the top of a nested list, and the sub-pagenodes of that list go between { curly braces }, like so:
#lang pollen toc.html ◊first-chapter.html{ foreword.html introduction.html} ◊second-chapter.html{ ◊main-argument.html{ facts.html analysis.html} conclusion.html} bibliography.html
The output of our hierarchical pagetree:
'(pagetree-root toc.html (first-chapter.html foreword.html introduction.html) (second-chapter.html (main-argument.html facts.html analysis.html) conclusion.html) bibliography.html)
One advantage of using a source file is that when you run it in DrRacket, it will automatically be checked using validate-pagetree, which insures that every element in the pagetree meets pagenode?, and that all the pagenodes are unique.
This pagetree has a duplicate pagenode, so it won’t run:
#lang pollen index.html introduction.html main_argument.html conclusion.html index.html
Instead, you’ll get an error:
validate-pagetree: members-unique? failed because item isn’t unique: (index.html)
11.4.2 Making pagetrees by hand
Experienced programmers may want to know that because a pagetree is just an X-expression, you can synthesize a pagetree using any Pollen or Racket tools for making X-expressions. For example, here’s some Racket code that generates the same pagetree as the flat.ptree source file above:
Note that you need to take more care when building a pagetree by hand. Pagenodes are symbols, not strings, thus the use of string->symbol is mandatory. One benefit of using a pagetree source file is that it takes care of this housekeeping for you.
11.4.3 Using pagetrees for navigation
Typically you’ll call the pagetree-navigation functions from inside templates, using the special variable here as the starting point. For more on this technique, see pagetree navigation.
11.4.4 Using index.ptree in the dashboard
When you’re using the project server to view the files in a directory, the server will first look for a file called index.ptree. If it finds this pagetree file, it will use it to build the dashboard. If not, then it will synthesize a pagetree using a directory listing. For more on this technique, see Using the dashboard.
11.4.5 Using pagetrees with raco pollen render
The raco pollen render command is used to regenerate an output file from its source. If you pass a pagetree to raco pollen render, it will automatically render each file listed in the pagetree.
For instance, many projects have auxiliary pages that don’t really belong in the main navigational flow. You can collect these pages in a separate pagetree:
#lang pollen 404-error.html terms-of-service.html webmaster.html [... and so on]
Thus, when you’re using pagetree-navigation functions within a template, you can use your main pagetree, and restrict the navigation to the main editorial content. But when you render the project, you can pass both pagetrees to raco pollen render.
For more on this technique, see raco pollen render.
11.4.6 Functions
11.4.6.1 Predicates & validation
Examples: | ||||||||||||||||
|
procedure
(validate-pagetree possible-pagetree) → pagetree?
possible-pagetree : any/c
Examples: | |||||||
|
Pagenodes are symbols (rather than strings) so that pagetrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.
Examples: | ||||||
|
procedure
(pagenodeish? v) → boolean?
v : any/c
Example: | ||
|
procedure
(->pagenode v) → pagenode?
v : pagenodeish?
Examples: | ||||
|
11.4.6.2 Navigation
parameter
(current-pagetree pagetree) → void? pagetree : pagetree?
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||||||
|
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
procedure
p : (or/c #f pagenodeish?) pagetree : pagetree? = (current-pagetree)
Examples: | |||||||||||||||
|
11.4.6.3 Utilities
procedure
(pagetree->list pagetree) → list?
pagetree : pagetree?
procedure
(in-pagetree? pagenode [pagetree]) → boolean?
pagenode : pagenode? pagetree : pagetree? = (current-pagetree)
procedure
(path->pagenode p) → pagenode?
p : pathish?