You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
pollen/scribblings/render.scrbl

89 lines
4.7 KiB
Plaintext

11 years ago
#lang scribble/manual
@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world web-server/templates pollen/file sugar pollen/render))
11 years ago
@(define my-eval (make-base-eval))
@(my-eval `(require pollen))
11 years ago
@title{Render}
11 years ago
@defmodule[pollen/render]
11 years ago
@italic{Rendering} is how Pollen source files get converted into output.
11 years ago
@defproc[
(render
[source-path complete-path?]
[template-path (or/c #f complete-path?) #f])
bytes?]
Renders @racket[_source-path]. The rendering behavior depends on the type of source file (for details, see @secref["File_formats" #:doc '(lib "pollen/scribblings/pollen.scrbl")]):
11 years ago
A @racketmodname[pollen/pre] file is rendered without a template.
11 years ago
A @racketmodname[pollen/markup] or @racketmodname[pollen/markdown] file is rendered with a template. If no template is specified with @racket[_template-path], Pollen tries to find one using @racket[get-template-for].
11 years ago
11 years ago
Be aware that rendering with a template uses @racket[include-template] within @racket[eval]. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.
11 years ago
11 years ago
For those panicked at the use of @racket[eval], please don't be. As the author of @racket[include-template] has already advised, ``If you insist on dynamicism'' — and yes, I do insist — ``@link["http://docs.racket-lang.org/web-server/faq.html#%28part._.How_do_.I_use_templates__dynamically__%29"]{there is always @racket[eval].}''
11 years ago
@defproc[
(render-to-file
[source-path complete-path?]
[template-path (or/c #f complete-path?) #f]
[output-path (or/c #f complete-path?) #f])
void?]
11 years ago
Like @racket[render], but saves the file to @racket[_output-path], overwriting whatever was already there. If no @racket[_output-path] is provided, it's derived from @racket[_source-path] using @racket[->output-path].
11 years ago
@defproc[
(render-to-file-if-needed
11 years ago
[source-path complete-path?]
11 years ago
[template-path (or/c #f complete-path?) #f]
11 years ago
[output-path (or/c #f complete-path?) #f]
[#:force force-render? boolean? #f])
11 years ago
void?]
11 years ago
Like @racket[render-to-file], but the render only happens if one of these conditions exist:
11 years ago
@itemlist[#:style 'ordered
11 years ago
11 years ago
@item{The @racket[_force-render?] flag — set with the @racket[#:force] keyword — is @racket[#t].}
11 years ago
@item{No file exists at @racket[_output-path]. (Thus, an easy way to force a render of a particular @racket[_output-path] is to delete it.)}
11 years ago
@item{Either @racket[_source-path] or @racket[_template-path] have changed since the last trip through @racket[render].}
@item{One or more of the project requires have changed.}]
11 years ago
If none of these conditions exist, @racket[_output-path] is deemed to be up to date, and the render is skipped.
11 years ago
@defproc[
(render-batch
[source-paths (listof pathish?)] ...)
void?]
11 years ago
Render multiple @racket[_source-paths] in one go. This can be faster than @racket[(for-each render _source-paths)] if your @racket[_source-paths] rely on a common set of templates. Templates may have their own source files that need to be compiled. If you use @racket[render], the templates will be repeatedly (and needlessly) re-compiled. Whereas if you use @racket[render-batch], each template will only be compiled once.
11 years ago
11 years ago
@defproc*[
(
11 years ago
[(render-pagetree [pagetree pagetree?]) void?]
[(render-pagetree [pagetree-source pathish?]) void?])]
11 years ago
Using @racket[_pagetree], or a pagetree loaded from @racket[_pagetree-source], render the pages in that pagetree using @racket[render-batch].
11 years ago
Note that @racket[_pagetree] or @racket[_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.
11 years ago
@defproc[
(get-template-for
[source-path complete-path?])
(or/c #f complete-path?)]
Find a template file for @racket[_source-path], with the following priority:
11 years ago
@itemlist[#:style 'ordered
11 years ago
@item{If the @racket[metas] for @racket[_source-path] have a key for @code[(format "~a" world:template-meta-key)], then use the value of this key.}
11 years ago
@item{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 @code[(format "~a.[output extension]" world:default-template-prefix)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the output path would be @code["intro.html"], so the default template would be @code[(format "~a.html" world:default-template-prefix)].}
11 years ago
@item{If this file doesn't exist, use the fallback template as a last resort. (See @secref["Templates"
#:tag-prefixes '("tutorial-2")
#:doc '(lib "pollen/scribblings/pollen.scrbl")].)}
]
11 years ago
11 years ago
This function is called when a template is needed, but a @racket[_template-path] argument is missing (for instance, in @racket[render] or @racket[render-to-file]).