2 Beeswax Reference🔗

2.1 Templates🔗

2.1.1 Syntax and bindings🔗

Beeswax templates use Pollen command syntax, which treats everything after the #lang line as string content that will be included in the output, except for embedded Racket expressions, which are escaped with the command character ◊. Beeswax honors setup:command-char, so if you have a custom command character configured in your "pollen.rkt", any templates in that project will use it as well. (See How to override setup values in the Pollen docs.)

Within a template, you have access to all the same things you do in a normal Pollen template:

• The doc and metas of the current source file

• The here variable, which is the path of the current output file in pagenode form

• Everything in the pollen/core, pollen/template and pollen/pagetree modules

• Everything provided by a "pollen.rkt" located in the same or any parent folder.

2.1.2 The apply-template function🔗

Beeswax templates wrap their contents inside a function named apply-template that is provided to other files.

This is an implicit function provided by every #lang beeswax/template file. The function definition surrounds the contents of the template; calling the function renders a document, using doc, metas and here wherever they are referred to in escaped Racket expressions within the template.

Any require-like forms within the template are lifted to the top level. Any define-like forms are moved to the start of the function — so you should be careful that definitions within the template don’t depend on side-effects from other expressions.

Returns the bytes of the rendered result, stripped of any leading whitespace.

2.1.3 Template filename conventions🔗

Your template’s filename should look like template.ext.rkt, where ext is the extension for the template’s output format. So for example, a template for HTML files should be named "template.html.rkt".

Your template will be useable (e.g., via dynamic-require) no matter what you name it. But if you are applying your templates using Pollen with external-renderer, Beeswax’s render function, or raco beeswax render, you’ll want to use these filename conventions, because those tools will be unable to locate your template otherwise.

See also the documentation for render to see how Beeswax determines which template to use.

This is a part of Beeswax about which I’m still undecided. Alternately, Beeswax could specify that its template filenames should be identical to those of normal Pollen templates. This would have the advantage of playing nicely with Pollen’s render cache, and it would mean slightly fewer redundant cycles used to locate the correct template when doing a render within the context of raco pollen render (since Pollen always does the work of locating its own template even when using an external renderer).

On the other hand, the ".rkt" extension highlights the fact that a Beeswax template is a proper Racket module, and it makes Beeswax more friendly to use outside Pollen projects.

2.2 Rendering🔗

This module provides some convenience functions for working with Beeswax templates.

The source file is assumed to be a valid Pollen source: its doc and metas will be retrieved with cached-doc and cached-metas.

If the template uses #lang beeswax/template, then the result will be bytes?, otherwise it could be anything.

This function checks the following places in order to find the correct template:

1. If the metas for source have a key for 'template, then Beeswax will attempt to use the value of that key (regardless of whether the file specified in that key actually exists). If the value is a list, it will select the value from the list matching the current output target based on its penultimate extension.

2. The filesystem is searched for "template.ext.rkt" starting with the same folder in which source is located and moving up through its parent folders one at a time.

If neither of these methods yields a potential template, an exception is raised. (There are no “default templates” in Beeswax as there are in Pollen.)

2.3 For Pollen🔗

This function is designed to be used by Pollen itself as an external renderer; you’ll probably never use it directly. To designate Beeswax as the external renderer for a Pollen project, define and provide a value called external-renderer in the setup module of your "pollen.rkt" like so:

"pollen.rkt"

#lang racket/base

(module setup racket/base

(define external-renderer '(beeswax/for-pollen external-renderer))

(provide external-renderer))