Renders the source file at @racket[_source-path]. The rendering behavior depends on the type of source file:
Renders @racket[_source-path]. The rendering behavior depends on the type of source file:
A @racketmodname[pollen/pre] file is rendered without a template.
A @racketmodname[pollen/markup] or @racketmodname[pollen/markdown] file is rendered with a template. If no template is provided with @racket[_template-path], Pollen tries to find one using @racket[get-template-for]. If that doesn't work, Pollen uses the fallback template.
A @racketmodname[pollen/markup] or @racketmodname[pollen/markdown] file is rendered with a template. If no template is provided with @racket[_template-path], Pollen finds one using @racket[get-template-for].
Be aware that rendering with a template uses @racket[include-template] within @racket[eval]. This is necessary to allow dynamic refresh of pages. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.
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.
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 — ``there is always @racket[eval].''
@secref["How do I use templates “dynamically\"?" #:doc '(lib "web-server/scribblings/faq.scrbl")]
@ -35,13 +35,17 @@ Like @racket[render], but saves the file to @racket[_output-path], overwriting w
@defproc[
(render-to-file-if-needed
[source-or-output-path complete-path?]
[source-path complete-path?]
[template-path (or/c #f complete-path?) #f]
[output-path (or/c #f complete-path?) #f])
[output-path (or/c #f complete-path?) #f]
[#:force force-render? boolean? #f])
void?]
Like @racket[render-to-file], with two differences. First, the mandatory argument can be either a source or an output path, and the function will compute the other. Second, the render only happens if one of these conditions exist:
Like @racket[render-to-file], but the render only happens if one of these conditions exist:
@itemlist[#:style 'ordered
@item{No file exists at @racket[_output-path]. (Corollary: an easy way to force a refresh of a particular @racket[_output-path] is to delete it.)}
@item{The @racket[_force-render?] flag is not @racket[#f].}
@item{No file exists at @racket[_output-path].
@margin-note{Corollary: an easy way to force a refresh of a particular @racket[_output-path] from the desktop is to delete it.}}
@item{Either @racket[_source-path] or @racket[_template-path] have changed since the last trip through @racket[render].}
@ -56,7 +60,7 @@ If none of these conditions exist, @racket[_output-path] is assumed to be curren
(render-batch
[source-paths (listof pathish?)] ...)
void?]
Render multiple @racket[_source-paths] in one go. This can be faster than @racket[(map render _source-paths)] if your @racket[_source-paths] rely on a common set of templates. Templates may have their own Pollen 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.
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.
@defproc[
@ -67,6 +71,8 @@ Find a template file for @racket[_source-path], with the following priority:
If the metas for @racket[_source-path] have a key for @code[(format "'~a" world:template-meta-key)], then use the value of this key.
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].~a" world:default-template-prefix world:template-source-ext)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the default template would be @code[(format "~a.html.~a" world:default-template-prefix world:template-source-ext)].
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].~a" world:default-template-prefix world:template-source-ext)]. 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.~a" world:default-template-prefix world:template-source-ext)].
If this file doesn't exist, the fallback template is used.
If this file doesn't exist, use the fallback template.
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]).
