7 Templates: Separation of View

The Web Server provides a powerful Web template system for separating the presentation logic of a Web application and enabling non-programmers to contribute to Racket-based Web applications.

Although all the examples here generate HTML, the template language and the Text Generation it is based on can be used to generate any text-based format: C, SQL, form emails, reports, etc.

7.1 Static

Suppose we have a file "static.html" with the contents:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

</body>

</html>

If we write the following in our code:

(include-template "static.html")

Then the contents of "static.html" will be read at compile time and compiled into a racket program that returns the contents of "static.html" as a string:

"<html>\n <head><title>Fastest Templates in the West!</title></head>\n <body>\n <h1>Bang!</h1>\n <h2>Bang!</h2>\n </body>\n</html>"

7.2 Dynamic

include-template gives the template access to the complete lexical context of the including program. This context can be accessed via the @ Syntax syntax. For example, if "simple.html" contains:

<html>

<head><title>Fastest @thing in the West!</title></head>

<body>

</body>

</html>

Then

(let ([thing "Templates"])
(include-template "simple.html"))

evaluates to the same content as the static example.

There are no constraints on how the lexical context of the template is populated. For instance, you can built template abstractions by wrapping the inclusion of a template in a function:

(define (fast-template thing)
(include-template "simple.html"))

(fast-template "Templates")
(fast-template "Noodles")

evalutes to two strings with the predictable contents:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

</body>

</html>

and

<html>

<head><title>Fastest Noodles in the West!</title></head>

<body>

</body>

</html>

Furthermore, there are no constraints on the Racket used by templates: they can use macros, structs, continuation marks, threads, etc. However, Racket values that are ultimately returned must be printable by the Text Generation. For example, consider the following outputs of the title line of different calls to fast-template:

(fast-template 'Templates)
...<title>Fastest Templates in the West!</title>...
(fast-template 42)
...<title>Fastest 42 in the West!</title>...
(fast-template (list "Noo" "dles"))
...<title>Fastest Noodles in the West!</title>...
(fast-template (lambda () "Thunks"))
...<title>Fastest Thunks in the West!</title>...
(fast-template (delay "Laziness"))
...<title>Fastest Laziness in the West!</title>...
(fast-template (fast-template "Embedding"))
...<title>Fastest ...<title>Fastest Embedding in the West!</title>... in the West!</title>...

7.3 Gotchas

7.3.1 @ Syntax: @ character, identifiers, and spaces

To obtain an @ character in template output, you must escape it since @ is the escape character of the @ Syntax. For example, to obtain:

<head><title>Fastest @s in the West!</title></head>

You must write:

<head><title>Fastest @"@"s in the West!</title></head>

as your template: literal @s must be replaced with @"@". (Note that the double-quotes are basically a Racket expression, which can be used for longer strings too.)

The @ Syntax will read Racket identifiers, so it does not terminate identifiers on punctuations or XML angle brackets. So,

<head><title>Fastest @thing in the @place!</title></head>

will complain that the identifier place!</title></head> is undefined. You might be tempted to subvert this by adding a space after the identifier:

<head><title>Fastest @thing in the @place !</title></head>

This will remove the error, but the generated HTML will not look like what you want. Sometimes this is not relevant, but sometimes it is. The safest thing to do is explicitly delimit the identifier with |s:

<head><title>Fastest @thing in the @|place|!</title></head>

If you intend to use templates a lot, you should familiarize yourself with the details of the @ Syntax.

7.3.2 Iteration

Since the template is compiled into a Racket program, only its results will be printed. For example, suppose we have the template:

<table>

@for[([c clients])]{

}

</table>

If this is included in a lexical context with clients bound to

(list (cons "Young" "Brigham") (cons "Smith" "Joseph"))

then the template will be printed as:

<table>

</table>

because for does not return the value of the body. Suppose that we change the template to use for/list (which combines them into a list):

<table>

@for/list[([c clients])]{

}

</table>

Now the result is:

<table>

</tr>

</table>

because only the final expression of the body of the for/list is included in the result. We can capture all the sub-expressions by using list in the body:

<table>

@for/list[([c clients])]{

@list{

}

</table>

Now the result is:

<table>

<tr><td>Young, Brigham</td></tr>

<tr><td>Smith, Joseph</td></tr>

</table>

The templating library provides a syntactic form to deal with this issue for you called in:

<table>

@in[c clients]{

}

</table>

Notice how it also avoids the absurd amount of punctuation on line two.

7.3.3 Escaping

Thanks to Michael W. for this section.

Because templates are useful for many things (scripts, CSS, HTML, etc), the Web Server does not assume that the template is for XML-like content. Therefore when when templates are expanded, no XML escaping is done by default. Beware of cross-site scripting vulnerabilities! For example, suppose a servlet serves the following template where some-variable is an input string supplied by the client:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

@some-variable

</body>

</html>

If the servlet contains something like the following:

(let ([some-variable (get-input-from-user)])
(include-template "static.htm"))

There is nothing to prevent an attacker from entering <script type="text/javascript">...</script> to make the template expand into:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

</body>

</html>

Now the server will send the attacker’s code to millions of innocent users. To keep this from happening when serving HTML, use the xexpr->string function from the xml module.

This can be done in the servlet:

(require xml)

(let ([some-variable (xexpr->string (get-input-from-user))])
(include-template "static.htm"))

Alternatively, make the template responsible for its own escaping:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

@(xexpr->string some-variable)

</body>

</html>

The improved version renders as:

<html>

<head><title>Fastest Templates in the West!</title></head>

<body>

</body>

</html>

When writing templates, always remember to escape user-supplied input.

7.4 HTTP Responses

The quickest way to generate an HTTP response from a template is using a response? struct:

(response/output
(λ (op) (display (include-template "static.html") op)))

Finally, if you want to include the contents of a template inside a larger X-expression :

`(html ,(include-template "static.html"))

will result in the literal string being included (and entity-escaped). If you actually want the template to be unescaped, then use include-template/xml to assert that the content is valid XML.

`(html ,(include-template/xml "static.html"))

7.5 API Details

syntax
(include-template path-spec)
(include-template #:command-char command-char path-spec)

Compiles the template at path-spec using the @ Syntax syntax within the enclosing lexical context. The path-spec is the same format used by include. Use the command-char keyword to customize the escape character.

Examples:

(include-template "static.html")
(include-template #:command-char #\$ "dollar-static.html")

syntax
(include-template/xml path-spec)
(include-template/xml #:command-char command-char path-spec)

Like include/template, but expands to a cdata structure.

Added in version 1.3 of package web-server-lib.

syntax
(in x xs e ...)

Expands into

(for/list ([x xs])
(begin/text e ...))

Template Example:

@in[c clients]{

}

Racket Example:

(in c clients "<tr><td>" (car c) ", " (cdr c) "</td></tr>")

7.6 Conversion Example

Al Church has been maintaining a blog with Racket for some years and would like to convert to web-server/templates.

The data-structures he uses are defined as:

(define-struct post (title body))

(define posts
  (list
   (make-post
    "(Y Y) Works: The Why of Y"
    "Why is Y, that is the question.")
   (make-post
    "Church and the States"
    "As you may know, I grew up in DC, not technically a state.")))

Actually, Al Church-encodes these posts, but for explanatory reasons, we’ll use structs.

He has divided his code into presentation functions and logic functions. We’ll look at the presentation functions first.

The first presentation function defines the common layout of all pages.

(define (template section body)
  (response/xexpr
   `(html
     (head (title "Al's Church: " ,section))
     (body
      (h1 "Al's Church: " ,section)
      (div ([id "main"])
           ,@body)))))

One of the things to notice here is the unquote-splicing on the body argument. This indicates that the body is list of X-expressions. If he had accidentally used only unquote then there would be an error in converting the return value to an HTTP response.

(define (blog-posted title body k-url)
  `((h2 ,title)
    (p ,body)
    (h1 (a ([href ,k-url]) "Continue"))))

Here’s an example of simple body that uses a list of X-expressions to show the newly posted blog entry, before continuing to redisplay the main page. Let’s look at a more complicated body:

(define (blog-posts k-url)
  (append
   (apply append
          (for/list ([p posts])
            `((h2 ,(post-title p))
              (p ,(post-body p)))))
   `((h1 "New Post")
     (form ([action ,k-url])
           (input ([name "title"]))
           (input ([name "body"]))
           (input ([type "submit"]))))))

This function shows a number of common patterns that are required by X-expressions. First, append is used to combine different X-expression lists. Second, apply append is used to collapse and combine the results of a for/list where each iteration results in a list of X-expressions. We’ll see that these patterns are unnecessary with templates. Another annoying patterns shows up when Al tries to add CSS styling and some JavaScript from Google Analytics to all the pages of his blog. He changes the template function to:

(define (template section body)
  (response/xexpr
   `(html
     (head
      (title "Al's Church: " ,section)
      (style ([type "text/css"])
             "body {margin: 0px; padding: 10px;}"
             "#main {background: #dddddd;}"))
     (body
      (script
       ([type "text/javascript"])
       ,(make-cdata
         #f #f
         "var gaJsHost = ((\"https:\" =="
         "document.location.protocol)"
         "? \"https://ssl.\" : \"http://www.\");"
         "document.write(unescape(\"%3Cscript src='\" + gaJsHost"
         "+ \"google-analytics.com/ga.js' "
         "type='text/javascript'%3E%3C/script%3E\"));"))
      (script
       ([type "text/javascript"])
       ,(make-cdata
         #f #f
         "var pageTracker = _gat._getTracker(\"UA-YYYYYYY-Y\");"
         "pageTracker._trackPageview();"))
      (h1 "Al's Church: " ,section)
      (div ([id "main"])
           ,@body)))))

Some of these problems go away by using here strings, as described in the documentation on Reading Strings.

The first thing we notice is that encoding CSS as a string is rather primitive. Encoding JavaScript with strings is even worse for two reasons: first, we are more likely to need to manually escape characters such as "; second, we need to use a CDATA object, because most JavaScript code uses characters that "need" to be escaped in XML, such as &, but most browsers will fail if these characters are entity-encoded. These are all problems that go away with templates.

Before moving to templates, let’s look at the logic functions:

(define (extract-post req)
  (define binds
    (request-bindings req))
  (define title
    (extract-binding/single 'title binds))
  (define body
    (extract-binding/single 'body binds))
  (set! posts
        (list* (make-post title body)
               posts))
  (send/suspend
   (lambda (k-url)
     (template "Posted" (blog-posted title body k-url))))
  (display-posts))

(define (display-posts)
  (extract-post
   (send/suspend
    (lambda (k-url)
      (template "Posts" (blog-posts k-url))))))

(define (start req)
  (display-posts))

To use templates, we need only change template, blog-posted, and blog-posts:

(define (template section body)
  (response/full
   200 #"Okay"
   (current-seconds) TEXT/HTML-MIME-TYPE
   empty
   (list (string->bytes/utf-8 (include-template "blog.html")))))

(define (blog-posted title body k-url)
  (include-template "blog-posted.html"))

(define (blog-posts k-url)
  (include-template "blog-posts.html"))

Each of the templates are given below:

"blog.html":

<html>

<head>

<title>Al's Church: @|section|</title>

body {

margin: 0px;

padding: 10px;

}

#main {

background: #dddddd;

}

</style>

</head>

<body>

var gaJsHost = (("https:" == document.location.protocol) ?

"https://ssl." : "http://www.");

document.write(unescape("%3Cscript src='" + gaJsHost +

"google-analytics.com/ga.js'

type='text/javascript'%3E%3C/script%3E"));

</script>

var pageTracker = _gat._getTracker("UA-YYYYYYY-Y");

pageTracker._trackPageview();

</script>

<h1>Al's Church: @|section|</h1>

@body

</div>

</body>

</html>

Notice that this part of the presentation is much simpler, because the CSS and JavaScript can be included verbatim, without resorting to any special escape-escaping patterns. Similarly, since the body is represented as a string, there is no need to remember if splicing is necessary.

"blog-posted.html":

<h2>@|title|</h2>

<h1><a href="@|k-url|">Continue</a></h1>

"blog-posts.html":

@in[p posts]{

<h2>@(post-title p)</h2>

}

</form>

Compare this template with the original presentation function: there is no need to worry about managing how lists are nested: the defaults just work.

top ← prev up next →

1	Running Web Servlets
2	Stateful Servlets
3	Stateless Servlets
4	HTTP: Hypertext Transfer Protocol
5	URL-Based Dispatch
6	Formlets: Functional Form Abstraction
7	Templates: Separation of View
8	Page: Short-hand for Common Patterns
9	Testing Servlets
10	Troubleshooting and Tips
	Index

7.1	Static
7.2	Dynamic
7.3	Gotchas
7.4	HTTP Responses
7.5	API Details
7.6	Conversion Example