@ -705,20 +705,20 @@ Here's the hard way. You can type out your list of attributes in Racket format a
@repl-output{'(title ((class "red") (id "first")) "The Beginning of the End")}
@repl-output{'(title ((class "red") (id "first")) "The Beginning of the End")}
But that's a lot of parentheses to think about. So here's the easy way. Anytime you use a tag function, there's a shortcut for inserting attributes. You can enter them as a series of symbol–string pairs between the Racket-argument brackets. The only caveat is that the symbols have to begin with a quote mark @litchar{'} and end with a colon @litchar{:}. So taken together, they look like this:
But that's a lot of parentheses to think about. So here's the easy way. Anytime you use a tag function, there's a shortcut for inserting attributes. You can enter them as a series of @italic{keyword arguments} between the Racket-argument brackets. The only caveat is that the values for these keyword arguments have to be strings. So taken together, they look like this:
@codeblock|{
@codeblock|{
#lang pollen
#lang pollen
◊title['class: "red" 'id: "first"]{The Beginning of the End}
◊title[#:class "red" #:id "first"]{The Beginning of the End}
}|
}|
@repl-output{'(title ((class "red") (id "first")) "The Beginning of the End")}
@repl-output{'(title ((class "red") (id "first")) "The Beginning of the End")}
Racket arguments can be any valid Racket expressions. For instance, this will also work:
The string arguments can be any valid Racket expressions that produce strings. For instance, this will also work:
@codeblock|{
@codeblock|{
#lang pollen
#lang pollen
◊title['class: (format "~a" (* 6 7)) 'id: "first"]{The Beginning of the End}
◊title[#:class (format "~a" (* 6 7)) #:id "first"]{The Beginning of the End}
}|
}|
@repl-output{'(title ((class "42") (id "first")) "The Beginning of the End")}
@repl-output{'(title ((class "42") (id "first")) "The Beginning of the End")}
@ -728,12 +728,12 @@ Since Pollen commands are really just Racket arguments underneath, you can use t
@codeblock|{
@codeblock|{
#lang pollen
#lang pollen
◊(define name "Brennan")
◊(define name "Brennan")
◊title['class: "red" 'id: ◊name]{The Beginning of the End}
◊title[#:class "red" #:id ◊name]{The Beginning of the End}
}|
}|
@repl-output{'(title ((class "read") (id "Brennan")) "The Beginning of the End")}
@repl-output{'(title ((class "read") (id "Brennan")) "The Beginning of the End")}
You can also use this area for @italic{keyword arguments}. Keyword arguments can be used to provide options for a particular Pollen command, to avoid redundancy. Suppose that instead of using the @code{h1 ... h6} tags, you want to consolidate them into one command called @code{heading} and select the level separately. You can do this with a keyword, in this case @racket[#:level], which is passed as a Racket argument:
When used in custom tag functions, keyword arguments don't have to represent attributes. Instead, they can be used to provide options for a particular Pollen command, to avoid redundancy. Suppose that instead of using the @code{h1 ... h6} tags, you want to consolidate them into one command called @code{heading} and select the level separately. You can do this with a keyword, in this case @racket[#:level], which is passed as a Racket argument:
@ -14,9 +14,11 @@ Convenience functions for working with tags.
@defproc[
@defproc[
(make-default-tag-function
(make-default-tag-function
[id txexpr-tag?])
[id txexpr-tag?]
[kw-attr-name keyword?]
[kw-attr-value string?] ... ...)
(-> txexpr?)]
(-> txexpr?)]
Make a default tag function for @racket[_id]. As arguments, a tag function takes an optional set of X-expression attributes (@racket[txexpr-attrs?]) followed by X-expression elements (@racket[txexpr-elements?]). From these, the tag function creates a tagged X-expression using @racket[_id] as the tag.
Make a default tag function for @racket[_id]. The new tag function takes an optional set of X-expression attributes (@racket[txexpr-attrs?]) followed by X-expression elements (@racket[txexpr-elements?]). From these, the tag function creates a tagged X-expression using @racket[_id] as the tag.
@examples[
@examples[
(require pollen/tag)
(require pollen/tag)
@ -25,20 +27,37 @@ Make a default tag function for @racket[_id]. As arguments, a tag function takes
(beaucoup '((id "greeting")) "Bonjour")
(beaucoup '((id "greeting")) "Bonjour")
]
]
Entering attributes this way can be cumbersome. So for convenience, a tag function provides an alternative: any symbol + string pairs at the front of your expression will be interpreted as attributes, if the symbols are followed by a colon. If you leave out the colon, the symbols will be interpreted as part of the content of the tag.
Entering attributes this way can be cumbersome. So for convenience, the new tag function provides an alternative: any keyword arguments and their values will be interpreted as attributes.
(code:comment @#,t{Don't forget to provide a value for each attribute})
You can also provide keyword arguments to @racket[make-default-tag-function] itself, and they will become default attributes for every use of the tag function.
Pollen also uses this function to provide the default behavior for undefined tags. See @racket[#%top].
Pollen also uses this function to provide the default behavior for undefined tags. See @racket[#%top].
Note that while default tag functions are typically used to generate tagged X-expressions, they don't enforce any restrictions on input, so they also do not guarantee that you will in fact get a valid tagged X-expression as output. This is intentional —default tag functions are a coding convenience, and their output is likely to be processed by other tag functions, so raising the error here would be premature.
Third, we need to include the content from our source file. By convention, every Pollen source file makes its output available through an exported variable named @code{doc}. A source file in preprocessor mode puts its text result in @code{doc}. And a source file in authoring mode puts its X-expression result in @code{doc}. So we put the variable @code{doc} inside the @code{body} tag.
Third, we need to include the content from our source file. By convention, every Pollen source file makes its output available through an exported variable named @code{doc}. A source file in preprocessor mode puts its text result in @code{doc}. And a source file in authoring mode puts its X-expression result in @code{doc}. So we put the variable @code{doc} inside the @code{body} tag.
@ -340,7 +340,7 @@ Third, we need to include the content from our source file. By convention, every
Under the hood, a template is just a partial program that relies on a set of variables defined by another source file. (In Racket, this set of variables is called a @defterm{lexical context}). So if you ran this template on its own, nothing would happen, because @code{doc} isn't defined. But when you run it in the context of another source file, it picks up the @code{doc} that's defined by that file.
Under the hood, a template is just a partial program that relies on a set of variables defined by another source file. (In Racket, this set of variables is called a @defterm{lexical context}). So if you ran this template on its own, nothing would happen, because @code{doc} isn't defined. But when you run it in the context of another source file, it picks up the @code{doc} that's defined by that file.
@ -192,15 +192,15 @@ Then you have two options for adding attributes. The verbose way corresponds to
Each key–value pair is in parentheses, and then the list of pairs is within parentheses, with a @racket[quote] (@litchar{'}) at the front that signals that the text should be used literally.
Each key–value pair is in parentheses, and then the list of pairs is within parentheses, with a @racket[quote] (@litchar{'}) at the front that signals that the text should be used literally.
This involves some superfluous typing, however, so Pollen also supports an abbreviated syntax for attributes:
This involves some superfluous typing, however, so Pollen also allows you to specify attributes with keyword arguments:
In this form, each attribute key starts with a quote mark @litchar{'} and ends with a colon @litchar{:}. As before, the attribute value is in quotation marks.
In this form, each attribute name is prefixed with @litchar{#:}, indicating a keyword argument. As before, the attribute value is in quotation marks following the keyword name.
Both of these forms will produce the same X-expression:
Both of these forms will produce the same X-expression:
@ -213,7 +213,7 @@ Now that you know how to make tags and attributes, you might wonder whether Poll
And then just convert it (using the @racket[->html] function) into the HTML above. Thus, the tags you already know (and love?) can be used in Pollen markup, but with fewer keystrokes and cruft.
And then just convert it (using the @racket[->html] function) into the HTML above. Thus, the tags you already know (and love?) can be used in Pollen markup, but with fewer keystrokes and cruft.
