14 Module reference
14.1 Cache
14.2 Core
14.3 Decode
14.4 File
14.5 Pagetree
14.6 Render
14.7 Setup
14.8 Tag
14.9 Template
14.10 Top
On this page:
14.5.1 Making pagetrees with a source file
14.5.2 Making pagetrees by hand
14.5.3 Nesting pagetrees
14.5.4 The automatic pagetree
14.5.5 Using pagetrees for navigation
14.5.6 Using "index.ptree" in the dashboard
14.5.7 Using pagetrees with raco pollen render
14.5.8 Functions
14.5.8.1 Predicates & validation
pagetree?
validate-pagetree
pagenode?
pagenodeish?
->pagenode
14.5.8.2 Navigation
current-pagetree
parent
children
siblings
other-siblings
previous
previous*
next
next*
14.5.8.3 Utilities
get-pagetree
pagetree->list
in-pagetree?
path->pagenode
7.0

14.5 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.

14.5.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:

"flat.ptree"
#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:

"hierarchical.ptree"
#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:

"duplicate-pagenode.ptree"
#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)

Pagenodes can refer to files in subdirectories. Just write the pagenode as a path relative to the directory where the pagetree lives:

"flat.ptree"
#lang pollen
 
foreword.html
facts-intro.html{
    facts/brennan.html
    facts/dale.html
}
analysis/intro.html{
    analysis/fancy-sauce/part-1.html
    analysis/fancy-sauce/part-2.html
}
conclusion.html
14.5.2 Making pagetrees by hand

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:

"make-flat-ptree.rkt"
#lang racket
(require pollen/pagetree)
(define node-names '(index introduction main_argument conclusion))
(define pt `(pagetree-root
  ,@(map (λ (n) (string->symbol (format "~a.html" n))) node-names)))
(if (pagetree? pt) pt "Oops, not a pagetree")

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.

14.5.3 Nesting pagetrees

You can put other pagetrees within a pagetree. Since every pagetree is an X-expression, you can nest pagetrees as you would ordinary X-expressions. Suppose you have this pagetree:

"sub.ptree"
#lang pollen
three
four

And you want to add it to an existing pagetree:

"index.ptree"
#lang pollen
one
two
five
six

You can require "sub.ptree" to import its doc. Be sure to use prefix-in so that the imported doc ends up with a distinct name that doesn’t conflict with the doc that’s already part of the current file:

"index.ptree"
#lang pollen
(require (prefix-in sub: "sub.ptree"))
one
two
sub:doc
five
six

And you’ll get this:

'(pagetree-root one two three four five six)

Pollen does one bit of housekeeping for you, which is that it automatically drops the root node of the imported pagetree, and splices the remaining nodes into the parent pagetree at the insertion point. Otherwise you’d get this, which is probably not what you wanted:

'(pagetree-root one two (pagetree-root three four) five six)

But if you do want the imported pagetree under a subnode, just add a containing pagenode as usual:

"index.ptree"
#lang pollen
(require (prefix-in sub: "sub.ptree"))
one
two
subtree{
  sub:doc
}
five
six

Which will give you:

'(pagetree-root one two (subtree three four) five six)

If you want to combine a number of pagetrees, require can get cumbersome because you have to juggle multiple doc imports (which can be done with prefix-in, but it’s still juggling). Instead, you can use dynamic-require to put each imported pagetree where you want it.

"index.ptree"
#lang pollen
one
two
(dynamic-require "sub.ptree" 'doc)
five
six
(dynamic-require "sub-two.ptree" 'doc)
nine
ten

Nesting pagetrees won’t circumvent the usual rule against duplicate pagenodes. So this pagetree, which tries to nest "sub.ptree" twice, won’t work:

"index.ptree"
#lang pollen
one
two
(dynamic-require "sub.ptree" 'doc)
(dynamic-require "sub.ptree" 'doc)
five
six
14.5.4 The automatic pagetree

In situations where Pollen needs a pagetree but can’t find one, it will automatically synthesize a pagetree from a listing of files in the directory. This arises most frequently when The project dashboard in a directory that doesn’t contain an explicit "index.ptree". This way, you can get going with a project without having to stop for .ptree housekeeping.

As usual, convenience has a cost. Pollen doesn’t know anything about which files in your directory are relevant to the project, so it includes all of them. For instance, if you start your project server on a Mac OS desktop, you’ll see things like "Thumbs.db" and "desktop.ini".

Also, though you can use pagetree-navigation functions like next or siblings with an automatic pagetree, the results of these functions are apt to include irrelevant files. So if you need to do pagetree navigation, that’s probably the point where you want to start using an explicit pagetree.

14.5.5 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.

14.5.6 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 The project dashboard.

14.5.7 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:

"utility.ptree"
#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.

14.5.8 Functions
14.5.8.1 Predicates & validation

procedure

(pagetree? possible-pagetree)  boolean?

  possible-pagetree : any/c
Test whether possible-pagetree is a valid pagetree. It must be a txexpr? where all elements are pagenode?, and each is unique within possible-pagetree (not counting the root node).

Examples:
> (pagetree? '(root index.html))

#t

> (pagetree? '(root duplicate.html duplicate.html))

#f

> (pagetree? '(root index.html "string.html"))

#f

> (define nested-ptree '(root 1.html 2.html (3.html 3a.html 3b.html)))
> (pagetree? nested-ptree)

#t

> (pagetree? `(root index.html ,nested-ptree (subsection.html more.html)))

#t

; Nesting a subtree twice creates duplication
> (pagetree? `(root index.html ,nested-ptree (subsection.html ,nested-ptree)))

#f

procedure

(validate-pagetree possible-pagetree)  pagetree?

  possible-pagetree : any/c
Like pagetree?, but raises a descriptive error if possible-pagetree is invalid, and otherwise returns possible-pagetree itself.

Examples:
> (validate-pagetree '(root (mama.html son.html daughter.html) uncle.html))

'(root (mama.html son.html daughter.html) uncle.html)

> (validate-pagetree `(root (,+ son.html daughter.html) uncle.html))

#f

> (validate-pagetree '(root (mama.html son.html son.html) mama.html))

validate-pagetree: members-unique? failed because items

aren't unique: (son.html mama.html)

procedure

(pagenode? possible-pagenode)  boolean?

  possible-pagenode : any/c
Test whether possible-pagenode is a valid pagenode. A pagenode can be any symbol? that is not whitespace. Every leaf of a pagetree is a pagenode. In practice, your pagenodes will likely be names of output files.

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:
; Three symbols, the third one annoying but valid
> (map pagenode? '(symbol index.html |   silly   |))

'(#t #t #t)

; A number, a string, a txexpr, and a whitespace symbol
> (map pagenode? '(9.999 "index.html" (p "Hello") |    |))

'(#f #f #f #f)

procedure

(pagenodeish? v)  boolean?

  v : any/c
Return #t if v can be converted with ->pagenode.

Example:
> (map pagenodeish? '(9.999 "index.html" |    |))

'(#t #t #t)

procedure

(->pagenode v)  pagenode?

  v : pagenodeish?
Convert v to a pagenode.

Examples:
> (map pagenodeish? '(symbol 9.999 "index.html" |  silly  |))

'(#t #t #t #t)

> (map ->pagenode '(symbol 9.999 "index.html" |  silly  |))

'(symbol |9.999| index.html |  silly  |)

14.5.8.2 Navigation

parameter

(current-pagetree)  pagetree?

(current-pagetree pagetree)  void?
  pagetree : pagetree?
A parameter that defines the default pagetree used by pagetree navigation functions (e.g., parent, children, et al.) if another is not explicitly specified. Initialized to #f.

procedure

(parent p [pagetree])  (or/c #f pagenode?)

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Find the parent pagenode of p within pagetree. Return #f if there isn’t one, or if you reach the root of the pagetree.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (parent 'son.html)

'mama.html

> (parent 'daughter.html)

'mama.html

> (parent "uncle.html")

#f

> (parent (parent 'son.html))

#f

procedure

(children p [pagetree])  (or/c #f (listof pagenode?))

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Find the child pagenodes of p within pagetree. Return #f if there aren’t any.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (children 'mama.html)

'(son.html daughter.html)

> (children 'uncle.html)

#f

> (children 'root)

'(mama.html uncle.html)

> (map children (children 'root))

'((son.html daughter.html) #f)

procedure

(siblings p [pagetree])  (or/c #f (listof pagenode?))

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Find the sibling pagenodes of p within pagetree. The result includes p itself. But the function will still return #f if pagetree is #f.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html)))
> (siblings 'son.html)

'(son.html daughter.html)

> (siblings 'daughter.html)

'(son.html daughter.html)

> (siblings 'mama.html)

'(mama.html)

procedure

(other-siblings p [pagetree])  (or/c #f (listof pagenode?))

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Like siblings, but the result does not include p itself.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html)))
> (other-siblings 'son.html)

'(daughter.html)

> (other-siblings 'daughter.html)

'(son.html)

> (other-siblings 'mama.html)

#f

procedure

(previous p [pagetree])  (or/c #f pagenode?)

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)

procedure

(previous* p [pagetree])  (or/c #f (listof pagenode?))

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Return the pagenode immediately before p. For previous*, return all the pagenodes before p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (previous 'daughter.html)

'son.html

> (previous 'son.html)

'mama.html

> (previous (previous 'daughter.html))

'mama.html

> (previous 'mama.html)

#f

> (previous* 'daughter.html)

'(mama.html son.html)

> (previous* 'uncle.html)

'(mama.html son.html daughter.html)

procedure

(next p [pagetree])  (or/c #f pagenode?)

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)

procedure

(next* p [pagetree])  (or/c #f (listof pagenode?))

  p : (or/c #f pagenodeish?)
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Return the pagenode immediately after p. For next*, return all the pagenodes after p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (next 'son.html)

'daughter.html

> (next 'daughter.html)

'uncle.html

> (next (next 'son.html))

'uncle.html

> (next 'uncle.html)

#f

> (next* 'mama.html)

'(son.html daughter.html uncle.html)

> (next* 'daughter.html)

'(uncle.html)

14.5.8.3 Utilities

procedure

(get-pagetree pagetree-source)  pagetree?

  pagetree-source : (or/c pagetree? pathish?)
Get a pagetree from a .ptree source file, namely pagetree-source. If pagetree-source is already a pagetree, just pass it through.

procedure

(pagetree->list pagetree)  list?

  pagetree : (or/c pagetree? pathish?)
Convert pagetree to a simple list. Uses flatten, and is thus equivalent to a pre-order depth-first traversal of pagetree.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (pagetree->list (current-pagetree))

'(mama.html son.html daughter.html uncle.html)

procedure

(in-pagetree? pagenode [pagetree])  boolean?

  pagenode : pagenodeish?
  pagetree : (or/c pagetree? pathish?) = (current-pagetree)
Report whether pagenode is in pagetree.

Examples:
> (current-pagetree '(root (mama.html son.html daughter.html) uncle.html))
> (in-pagetree? 'son.html)

#t

> (in-pagetree? 'alcoholic-grandma.html)

#f

procedure

(path->pagenode p [starting-path])  pagenode?

  p : pathish?
  starting-path : pathish? = (current-project-root)
Convert path p to a pagenode — meaning, make it relative to starting-path, run it through ->output-path, and convert it to a symbol. Does not tell you whether the resulting pagenode actually exists in the current pagetree (for that, use in-pagetree?).