HTML Generation

CL-HTTP includes a comprehensive set of routines for generating HTML to the HTML 4.0 standard. This section gives an overview of the routines available.

Introduction

The basic routines emit a single tag on the output stream specified by the :stream keyword parameter. For example:

(break-line :stream stream)

emits:

<br>

The next set of routines emit a construct consisting of a string surrounded by opening and closing tags. For example:

(declare-title "Home Page" :stream stream)

emits:

<title>Home Page</title>

These routines can generally either take a literal string, or a function which is called with the stream; for example:

(declare-title (lambda (stream) (format stream "Page ~a" n)) :stream stream)

Environment macros

The environment macros establish an environment by emitting opening and closing tags around the routines specified in the body. These typically have names of the form with-xxx. For example:

(with-paragraph (:stream stream)
  (write-stream "Log out" stream))

emits:

<p>Log out</p>

The CL-HTTP routines for HTML generation attempt to rationalise some of the inconsistencies in the HTML standard by providing unified ways of doing related functions. For example, the routine with-division can be used to create either a div or a span block depending on the value of its :inline-p parameter. For example:

(with-division (:id "heading" :stream *standard-output*)
  (write-string "Introduction" *standard-output*))

will emit:

<div id="heading">Introduction</div>

whereas:

(with-division (:inline-p t :class :bold :stream *standard-output*)
  (write-string "Important!" *standard-output*))

will emit

<span class="bold">Important!</span>	

Common keywords

Where appropriate many of the HTML generation routines can take the following common keywords:

Keyword Description
:class The class for the element
:id An element identifier
:title A string used as an element title.
:style Inline CSS parameters.

The value of each parameter can be specified as a keyword, string, or function of stream; for example:

(with-paragraph (:class :bold :id "legal-notice" :stream stream)
  (write-string  "Copyright 2011" stream))

will emit:

<p id="legal-notice" class="bold">Copyright 2011</p>

Here we use a keyword for the class name, for efficiency. If you use a keyword for the id CL-HTTP capitalises it to warn you that the id should be unique, so a string is more efficient in this case.


blog comments powered by Disqus