►Pollen:   the book is a program
▼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:
render
render-to-file
render-to-file-if-needed
render-batch
render-pagenodes
get-template-for
8.12
  top  contents    up   

14.6 Render🔗ℹ

 (require pollen/render) package: pollen

Rendering is how Pollen source files get converted into output.

procedure

(render source-path [template-path]) → (or/c string? bytes?)

  source-path : complete-path?
  template-path : (or/c #f complete-path?) = #f
Renders source-path. The rendering behavior depends on the type of source file (for details, see File formats):

A pollen/pre file is rendered without a template.

A pollen/markup or pollen/markdown file is rendered with a template. If no template is specified with template-path, Pollen tries to find one using get-template-for.

Be aware that rendering with a template uses include-template within eval. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.

For those panicked at the use of eval, please don’t be. As the author of include-template has already advised, “If you insist on dynamicism” — and yes, I do insist — “there is always eval.”

procedure

(render-to-file source-path    
  [template-path    
  output-path]) → void?
  source-path : complete-path?
  template-path : (or/c #f complete-path?) = #f
  output-path : (or/c #f complete-path?) = #f
Like render, but saves the file to output-path, overwriting whatever was already there. If no output-path is provided, it’s derived from source-path using ->output-path.

procedure

(render-to-file-if-needed source-path    
  [template-path    
  output-path]) → void?
  source-path : complete-path?
  template-path : (or/c #f complete-path?) = #f
  output-path : (or/c #f complete-path?) = #f
Like render-to-file, but the render only happens if one of these conditions exist:

  1. No file exists at output-path. (Thus, an easy way to force a render of a particular output-path is to delete it.)

  2. Either source-path, template-path, or the associated "pollen.rkt" has changed since the last trip through render.

  3. The render cache is deactivated.

If none of these conditions exist, output-path is deemed to be up to date, and the render is skipped.

procedure

(render-batch source-path ...) → void?

  source-path : pathish?
Render multiple source-paths in one go. This can be faster than (for-each render source-paths) if your source-paths rely on a common set of templates. Templates may have their own source files that need to be compiled. If you use render, the templates will be repeatedly (and needlessly) re-compiled. Whereas if you use render-batch, each template will only be compiled once.

procedure

(render-pagenodes pt-or-pt-source) → void?

  pt-or-pt-source : (or/c pathish? pagetree?)
Using pt-or-pt-source, render the pagenodes in that pagetree using render-batch.

Note that pt-or-pt-source is used strictly as a list of files to render, like a batch file. It is not used as the navigational pagetree for the rendered files.

procedure

(get-template-for source-path) → (or/c #f complete-path?)

  source-path : complete-path?
Find a template file for source-path, with the following priority:

  1. If the metas for source-path have a key for template, then use the value of this key, e.g. —

    ◊(define-meta template "my-template.html")

    If your project has multiple output targets, you can supply a list of templates, and the template with an extension matching the current output target will be selected automatically, e.g. —

    ◊(define-meta template (list "my-template.html" "my-template.txt" "my-template.pdf"))

  2. If this key doesn’t exist, or refers to a nonexistent file, look for a default template with the name template.[output extension]. Meaning, if source-path is intro.html.pm, the output path would be intro.html, so the default template would be template.html. Look for this default template in the same directory as the source file, and then search upwards within successive parent directories. (Corollary: a default template in the project root will apply to all files in the project unless overridden within a subdirectory.)

  3. If this file doesn’t exist, use the fallback template as a last resort. (See Templates.)

This function is called when a template is needed, but a template-path argument is missing (for instance, in render or render-to-file).

  top  contents    up