htmap

htmap is a library for creating bits of SHTML out of your data. For example, it can take some rows from a database and turn them into a table. Or, it can take a single row and turn it into a form.

htmap deals with definitions and rows. A definitions describes the fields that will be displayed, and a row contains the actual data. They are both alists.

A Simple Example

(define definition
  `((title)
    (year)))

(define rows '(((id . 1234) (title . "Rescue Dawn") (year . 2006))
               ((id . 1235) (title . "Aguirre") (year . 1972))))

(shtml->html (htmap:table definition rows))

Produces a table:

title	year
Rescue Dawn	2006
Aguirre	1972

Notice that the id field doesn't get shown. That's because it's not in the definition.

Now, if we wanted to change the column headings, we change the definition. The definition is an alist, with the field names as the key, and another alist of properties as the value. Here we'll use the property htmap-title to set a title for the column.

(define definition
  `((title . ((htmap-title . "Title")))
    (year . ((htmap-title . "Year Released")))))

(shtml->html (htmap:table definition rows))

And the result:

Title	Year Released
Rescue Dawn	2006
Aguirre	1972

Formatting Values

Now let's do something with the ID field. Let's show it in italics. htmap-value is a procedure that takes the field's value and returns the SHTML that we'd like to display.

(define definition
  `((title . ((htmap-title . "Title")))
    (year . ((htmap-title . "Year Released")))
    (id . ((htmap-title . "ID")
           (htmap-value . ,(lambda (x) `(i ,(->string x))))))))

(shtml->html (htmap:table definition rows))

Gives us:

Title	Year Released	ID
Rescue Dawn	2006	1234
Aguirre	1972	1235

Other Things to Display

Going through all the trouble of setting up these definitions wouldn't be worth it if we only wanted to display the data one way. But say, for instance, we wanted to show a different kind of table.

(shtml->html (htmap:property-table definition (car rows)))

Title	Rescue Dawn
Year Released	2006
ID	1234

This is a property table, which is a table for a single row oriented on it's side. We can also make a property table form. The first argument, "film" is used to name the fields to things like "film[title]" and "film[value]", which mettle can parse from from the GET or POST variables.

(shtml->html (htmap:property-table-form "film" definition (car rows)))

Title
Year Released
ID

Where to Go From Here

Well, hopefully you've got a general idea of what htmap is about by now, because I sure am tired of writing for the moment. Sorry. There really are a few more things to go over, like the fact that the proc for htmap-value can take some keyword args, most importantly one called row:, which lets you do things like calculated fields.