►Pollen:   the book is a program
▼14 Module reference
14.1 Cache
14.2 Decode
14.3 File
14.4 Pagetree
14.5 Pygments
14.6 Render
14.7 Template
14.8 Tag
14.9 Top
14.10 World
On this page:
render
render-to-file
render-to-file-if-needed
render-batch
render-pagetree
get-template-for
6.2.901.900
  top  ← prev  up  next → 

14.6 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 (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    
  #: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.

Note that pagetree or pagetree_source is used strictly as a list of files to render. It is not used, for instance, 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.

  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  ← prev  up  next →