►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:
->html
select
select*
select-from-metas
select-from-doc
when/  block
6.2.901.900
  top  ← prev  up  next → 

14.7 Template

 (require pollen/template) package: pollen

Convenience functions for templates. These are automatically imported into the eval environment when rendering with a template (see render).

This module also provides everything from sugar/coerce.

procedure

(->html xexpr-or-xexprs    
  [#:tag html-tag    
  #:attrs html-attrs    
  #:splice splice-html?]) → string?
  xexpr-or-xexprs : (or/c xexpr? (listof xexpr?))
  html-tag : (or/c #f txexpr-tag?) = #f
  html-attrs : (or/c #f txexpr-attrs?) = #f
  splice-html? : boolean? = #f
Convert xexpr-or-xexprs to an HTML string. Similar to xexpr->string, but consistent with the HTML spec, text that appears within script or style blocks will not be escaped.

Examples:

> (define tx '(root (script "3 > 2") "Why is 3 > 2?"))
> (xexpr->string tx)

"<root><script>3 &gt; 2</script>Why is 3 &gt; 2?</root>"

> (->html tx)

"<root><script>3 > 2</script>Why is 3 &gt; 2?</root>"

The optional keyword arguments html-tag and html-attrs let you set the outer tag and attributes for the generated HTML. If xexpr-or-xexprs already has an outer tag or attributes, they will be replaced.

Examples:

> (define tx '(root ((id "huff")) "Bunk beds"))
> (->html tx)

"<root id=\"huff\">Bunk beds</root>"

> (->html tx #:tag 'div)

"<div id=\"huff\">Bunk beds</div>"

> (->html tx #:attrs '((id "doback")))

"<root id=\"doback\">Bunk beds</root>"

> (->html tx #:tag 'div #:attrs '((id "doback")))

"<div id=\"doback\">Bunk beds</div>"

Whereas if xexpr-or-xexprs has no tag or attributes, they will be added. If you supply attributes without a tag, you’ll get an error.

Examples:

> (define x "Drum kit")
> (->html x)

"Drum kit"

> (->html x #:tag 'div)

"<div>Drum kit</div>"

> (->html x #:tag 'div #:attrs '((id "doback")))

"<div id=\"doback\">Drum kit</div>"

> (->html x #:attrs '((id "doback")))

->html: contract violation

  expected: can't use attribute list without a #:tag

argument

  given: #f

If the generated HTML has an outer tag, the splice-html? option will strip it off. Otherwise this option has no effect.

Examples:

> (define tx '(root (p "Chicken nuggets")))
> (->html tx)

"<root><p>Chicken nuggets</p></root>"

> (->html tx #:splice #t)

"<p>Chicken nuggets</p>"

> (define x "Fancy sauce")
> (->html x)

"Fancy sauce"

; This next one won't do anything
> (->html x #:splice #t)

"Fancy sauce"

; Adds the outer tag, but then #:splice removes it
> (->html x #:tag 'div #:attrs '((id "doback")) #:splice #t)

"Fancy sauce"

Be careful not to pass existing HTML strings into this function, because the angle brackets will be escaped. Fine if that’s what you want, but you probably don’t.

Examples:

> (define tx '(p "You did " (em "what?")))
> (->html tx)

"<p>You did <em>what?</em></p>"

> (->html (->html tx))

"&lt;p&gt;You did &lt;em&gt;what?&lt;/em&gt;&lt;/p&gt;"

As the input contract suggests, this function can take either a single xexpr? or a list of xexpr?, with the expected results.

Examples:

> (define tx '(p "You did " (em "what?")))
> (->html tx)

"<p>You did <em>what?</em></p>"

> (define txs '("You " "did " (em "what?")))
> (->html txs)

"You did <em>what?</em>"

> (->html #:tag 'p txs)

"<p>You did <em>what?</em></p>"

procedure

(select key value-source) → (or/c #f xexpr?)

  key : symbolish?
  value-source : (or/c hash? txexpr? pagenode? pathish?)

procedure

(select* key value-source) → (or/c #f (listof xexpr?))

  key : symbolish?
  value-source : (or/c hash? txexpr? pagenode? pathish?)
Find matches for key in value-source. The value-source can be 1) a hashtable of metas, 2) a tagged X-expression representing a doc, or 3) a pagenode or path that identifies a source file that provides metas and doc. In that case, first look for key in metas (using select-from-metas) and then in doc (using select-from-doc).

With select, you get the first result; with select*, you get them all.

In both cases, you get #f if there are no matches.

Note that if value-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (module nut-butters pollen/markup
  '(div (question "Flavor?")
    (answer "Cashew") (answer "Almond")))
; Import doc from 'nut-butters submodule
> (require 'nut-butters)
> (select 'question  doc)

"Flavor?"

> (select 'answer  doc)

"Cashew"

> (select* 'answer  doc)

'("Cashew" "Almond")

> (select 'nonexistent-key doc)

#f

> (select* 'nonexistent-key doc)

#f

procedure

(select-from-metas key meta-source) → (or/c #f xexpr?)

  key : symbolish?
  meta-source : (or/c hash? pagenodeish? pathish?)
Look up the value of key in meta-source. The meta-source argument can be either 1) a hashtable representing metas or 2) a pagenode or source path that identifies a source file that provides metas. If no value exists for key, you get #f.

Note that if meta-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (define metas (hash 'template "sub.xml.pp" 'target "print"))
> (select-from-metas 'template  metas)

"sub.xml.pp"

> ('target . select-from-metas . metas)

"print"

> (select-from-metas 'nonexistent-key metas)

#f

procedure

(select-from-doc key doc-source) → (or/c #f (listof xexpr?))

  key : symbolish?
  doc-source : (or/c txexpr? pagenodeish? pathish?)
Look up the value of key in doc-source. The doc-source argument can be either 1) a tagged X-expression representing a doc or 2) a pagenode or source path that identifies a source file that provides doc. If no value exists for key, you get #f.

Note that if doc-source is a relative path or pagenode, it is treated as being relative to world:current-project-root. If that’s not what you want, you’ll need to convert it explicitly to a complete-path (e.g., with path->complete-path or ->complete-path).

Examples:

> (module gelato pollen/markup
  '(div (question "Flavor?")
    (answer "Nocciola") (answer "Pistachio")))
; Import doc from 'gelato submodule
> (require 'gelato)
> (select-from-doc 'question  doc)

'("Flavor?")

> ('answer . select-from-doc . doc)

'("Nocciola" "Pistachio")

> (select-from-doc 'nonexistent-key doc)

#f

procedure

(when/block condition text-to-insert) → string?

  condition : any/c
  text-to-insert : any/c
Convenience function for templates that’s simpler to use than plain when. If condition is true, then put the text-to-insert into the template at the current location. Within a template file, usually invoked like so:

◊when/block[condition]{The text to insert.}

The inserted text can contain its own nested Pollen commands.

  top  ← prev  up  next →