On this page:
2.1 Templates
2.1.1 Syntax and bindings
2.1.2 The apply-template function
apply-template
2.1.3 Template filename conventions
2.2 Rendering
get-template-proc
render
2.3 For Pollen
external-renderer
8.2

2 Beeswax Reference

2.1 Templates

 #lang beeswax/template package: beeswax

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:

2.1.2 The apply-template function

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

procedure

(apply-template doc metas here)  bytes?

  doc : any/c
  metas : hash?
  here : pagenode?

Any Racket module that provides a procedure with the same name and arity as this one can be used as a Beeswax template, even if written in a different #lang. This is useful when writing templates for binary file formats.

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

 (require beeswax/render) package: beeswax

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

procedure

(get-template-proc template)  procedure?

  template : (or/c path? path-string?)
Returns a binding for the apply-template procedure provided from template. If template-path cannot be resolved to a module path, or if the template does not provide a binding named apply-template, or if that binding is not a procedure, an exception is raised. The signature of the procedure is not checked.

procedure

(render source output)  (or/c bytes? any/c)

  source : (or/c path? path-string?)
  output : (or/c path? path-string?)
Locates the correct Beeswax template for the source and target output format, and returns the result of calling that template’s apply-template procedure with the doc and metas provided by the source document, and with output (in symbol form) as the third parameter. This function does not write any output to the filesystem; output is only used to determine the target file format.

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

 (require beeswax/for-pollen) package: beeswax

procedure

(external-renderer source template output)

  (or/c string? bytes?)
  source : path?
  template : path?
  output : path?
Renders source into output and returns the string or bytes of the result. If source has a ".pm" (Pollen markup) or ".pmd" (Pollen Markdown) file extension, the render is done using Beeswax’s render function, otherwise the parameters are passed through to Pollen’s render function.

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))