►Pollen:   the book is a program
▼10 Module reference
10.1 Cache
10.2 Decode
10.3 File
10.4 Pagetree
10.5 Render
10.6 Template
10.7 Tag
10.8 Top
10.9 World
On this page:
render
render-to-file
render-to-file-if-needed
render-batch
render-pagetree
get-template-for
6.1.0.5
    ← prev  up  next → 

10.5 Render

 (require pollen/render) package: pollen

Rendering is how Pollen source files get converted into output.

procedure

(render source-path [template-path]) → 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:

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 provided with template-path, Pollen finds 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    
  #:force force-render?]) → void?
  source-path : complete-path?
  template-path : (or/c #f complete-path?) = #f
  output-path : (or/c #f complete-path?) = #f
  force-render? : boolean? = #f
Like render-to-file, but the render only happens if one of these conditions exist:

  1. The force-render? flag — set with the #:force keyword — is #t.

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

  3. Either source-path or template-path have changed since the last trip through render.

  4. One or more of the project requires have changed.

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

procedure

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

  source-paths : (listof 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-pagetree pagetree) → void?

  pagetree : pagetree?
(render-pagetree pagetree-source) → void?
  pagetree-source : pathish?
Using pagetree, or a pagetree loaded from pagetree-source, render the pages in that pagetree using render-batch.

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.

  2. If this key doesn’t exist, or if it points to a nonexistent file, look for a default template in the project directory 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.

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

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

    ← prev  up  next →