In the previous section you played with several brushes and painted a canvas with them. Now we will explain in detail how brushes work. A canvas provides a simple pattern for creating and using these brushes as shown in Figure 63.

Tell the canvas what type of brush you are using.

Configure the brush, specifying any special options that it may use.

Render the contents of this brush. This is often done by passing an object such as a string or a block to with:.

It is not always necessary to send a brush the with: message. Do so only if you want to specify the contents of the body of the XHTML tag. Since this message causes the XHTML tag to be rendered, it should be sent last.

Figure 63: Select brush, configure it, and render it.

Here is an example:

htmlheadinglevel:1;with:'Hello world'.

produces the following XHTML

<h1>Hello world</h1>

In this example

We first specify the brush (tag) we are using with html heading.

We then send that brush the level: 1 message to indicate that this should be a level 1 heading.

We tell the brush the contents of the heading and cause it to be rendered using with:.

Here are some examples that show that it is not necessary to use with: if you do not specify the attributes of the brush.

Just a brush

htmlparagraph

produces

<p></p>

A brush with implicit content

htmlparagraph:'foo'

produces

<p>foo</p>

Setting the content explicitly

htmlparagraphwith:'foo'

produces

<p>foo</p>

Setting attributes directly

htmlparagraphclass:'cool';with:'foo'

produces

<p class="cool">foo</p>

If no configuration of the brush is necessary, it is usually possible to specify it with a keyword parameter which becomes the contents of the tag. Thus the two following expressions are equivalent

htmlheadinglevel:1;with:'Hello world'.htmlheading:'Hello World'.

since level 1 is the default level for a heading.

As you can see, there are two cases where you can write more compact code. These are summarized in Figure 64. There is a style checking tool called Slime that checks for such cases. Slime is explained in Chapter 14.

Figure 64: Brush Simplifications.

The next section will show you what the other brushes are and how to find information about them within Seaside.