Magritte Rendering in Seaside

Magritte for Seaside allows one to automatically build Seaside components from descriptive objects. There are several possibilities to customize this 3 step process:

  1. a renderer defines the markup surrounding the form elements,
  2. a view component defines the visual appearance of every form element, and
  3. decorations surround the generated form to add additional functionality.

The Renderer

MATableRenderer (default) and MACssRenderer are complementary. These classes define how the different Magritte components are laid out in the generated XHTML. You can choose a different renderer by overriding the container description of your domain object:

descriptionContainer
^ super descriptionContainer
componentRenderer: MACssRenderer;
yourself

To customize the way CSS classes are assigned to the individual items of the form, add the class names to the respective descriptions.

descriptionFirstName
^ MAStringDescription new
accesssor: #firstName;
cssClass: 'firstname';
yourself

If a completely different markup is needed, a custom subclass of MAComponentRenderer should be created. Below a short description of the two renderer that come with Magritte.

The table renderer

MATableRenderer puts the form elements into a table, this is what traditional web applications mostly do. This looks good without applying any style-sheet.

<table>
    <tr class="group">
        <th colspan="2"><i>Group Label</i></th>
    </tr>
    <tr>
        <th><i>Description Label</i></th>
        <td><i>Description Component</i></th>
    </tr>
    ...
</table>

The CSS renderer

The other renderer, MACssRenderer, uses semantically meaningful XHML markup and requires some CSS tweaking to look fine:

<dl>
    <dt class="group"><i>Group Label</i></dt>
    <dt><i>Description Label</i></dt>
    <dd><i>Description Component</i></dd>
    ...
</dl>

The components

The components (subclasses of MADescriptionComponent) provide the view of the description. Every description has a default component, and some have addition views. In the example below, the boolean value can either be displayed using a checkbox (default), a drop-down box, or a group of radio buttons.

descriptionVegetarian
^ MABooleanDescription new
accessor: #vegetarian;
componentClass: MACheckboxComponent;
"or MASelectListComponent or MARadioGroupComponent" ;
yourself

The list of views that are known to work with a particular description can be found in the class-side method called defaultComponentClasses of the respective description. For MABooleanDescription this method looks like:

defaultComponentClasses
^ Array
with: MACheckboxComponent
with: MASelectListComponent
with: MARadioGroupComponent

To build your own view, simply customize one of the existing views or implement your own Seaside component as a subclass of MADescriptionComponent.

The decorations

The decorations (subclasses of MAComponentDecoration) enable one to customize the form around the components build by Magritte. This is not done automatically from the renderer, because one might want to manually compose multiple components to one big screen. The following decorations are available:

Decoration Class Add Selector Description
MAFormDecoration addForm and addForm: Surrounds the component with a &lt;form&gt; tag and adds save and cancel buttons. Other button actions and labels can be specified with the decoration.
MASwitchDecoration addSwitch Turns the component read-only, but adds an edit button that allows one to switch between view and edit-mode.
MAValidationDecoration addValidation Normally invisible, but in case of validation errors show a list of problems.

Since addForm and addValidation are commonly used together, there are the conveniance methods addValidatedForm and addValidatedForm:. To decorate your Magritte components differently, simply create your own decoration class or refine an existing one.

Posted by Lukas Renggli at 12 August 2008, 9:44 am with tags magritte, seaside, tutorial link

Comments

Thank you for the explanation. I think MASwitchDecoration and MAValidationDecoration are swapped in the table.

Posted by Damien Cassou at 12 August 2008, 1:32 pm link

Thank you, I fixed the bug in the table.

Posted by Lukas Renggli at 12 August 2008, 6:49 pm link