Magritte for Seaside allows one to automatically build Seaside components from descriptive objects. There are several possibilities to customize this 3 step process:
- a renderer defines the markup surrounding the form elements,
- a view component defines the visual appearance of every form element, and
- 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 <form> 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.
Comments
Thank you for the explanation. I think MASwitchDecoration and MAValidationDecoration are swapped in the table.
Thank you, I fixed the bug in the table.