Using Magritte With Seaside
Comments(26) One of the more tedious things one is faced with while writing web applications is input forms. Forms suck because they’re boring and repetitive. Building them manually is the same thing over and over, but they’re often just different enough that fully automating them is rather difficult. I can’t say I’ve ever seen a perfect solution, but I’ve come to consider Magritte the best solution I’ve used thus far.
For an in depth look at the design of Magritte you should read Lukas’ Master’s thesis, however, it’s a bit much if you’re just trying to get something done and just want to understand how to get going with the basics. Magritte’s capable of more than you’ll likely use if you’re just wanting to build forms with Seaside. I’m going to ignore those other abilities because frankly, I don’t use them and don’t plan to.
The basic design of Magritte involves a few classes that you’ll need to be familiar with and often subclass to extend and customize.
MADescription
With Magritte you describe your objects with subclasses of MADescription, this is where you’ll always start, just describing the fields of your domain objects that you’ll want generated forms for. Descriptions contain the extra metadata necessary to create user interfaces, and which component will be used to render it. A simple description looks like this…
descriptionIsClosed
^ (MABooleanDescription new)
selectorAccessor: #isClosed;
label: 'Is Closed';
priority: 1000;
yourself
Generally speaking you’ll keep these descriptions on the class side of your domain object. On occasion, you’ll want some property of the description to be dynamic and depend on the actual value of an instance side value, so you’ll move the description to the instance side. Strictly speaking, it doesn’t matter where you put them, sometimes you’ll use them to build forms when you don’t even have a domain object, but this isn’t the normal case.
There are two basic ways to create a form dynamically, one is simple and includes all descriptions found on an object…
buildComponentFor: aModel
^aModel asComponent addValidatedForm
The other, a little more complex, but much more useful because you’ll find that rarely do you want “every” described field in a form. Often you’ll have multiple UI representations of a domain object within an app. Descriptions are composable using a comma so you can build a form any subset of the fields…
buildComponentFor: aModel
^((ModelClass descriptionFieldOne, ModelClass descriptionFieldTwo, ModelClass descriptionFieldThree)
asComponentOn: aModel)
addValidatedForm;
yourself
A Magritte form is generally wrapped with a form decoration via #addValidateForm, which by default gives you a #save and #cancel button. Magritte forms don’t directly work on your domain objects. They work on a memento of the values pulled from your object using the descriptions. When you call #save, the values are validated using the descriptions, and only after passing all validation rules are the values committed to your domain object by the momentos via the accessors, which I’ll describe shortly. For those interested, this is a good place to plug in a custom container component and integrate the #commit with Glorp, but that’s another post.
Conditions
Descriptions can have predicates associated with them to validate the input data which it calls conditions. There are two basic kinds of conditions (there are actually more, but the block forms are what I use), both are simply blocks that returns true or false to validate the data. One is the single field condition which is passed the pending value directly and attached directly to your descriptions. It’s as simple as…
addCondition:[:value | value withBlanksTrimmed size > 3]
The other is the multi field validation which works on the memento which I’ll describe below.
addCondition: [:memento | (memento cache at: CAUser descriptionPassword) isNil or: [(memento cache at: CAUser descriptionPassword) = (memento cache at: CAUser descriptionConfirmedPassword)]] labelled: ‘Passwords must match’;
I’ve posted about these previously. They are attached to your containers description which has access to all the fields.
Conditions are one of the few things about Magritte that I’m still iffy on. There are advantages to having your rules outside your domain objects, especially if you’re taking advantage of Magritte as an Adaptive Object Model where users can build rules from the UI. It also allows the mementos to easily test data for validity outside the domain object and gives you a nice place to hook into the validation system in the components. It bothers me a little because it weakens the domain model, I’m still trying to find my balance here and decide just how much I’ll allow as conditions.
Magritte is very pluggable, should I decide I want all my rules in my domain objects, I could plug in my own memento subclass to handle that, but I haven’t felt the need just yet.
MAMemento
When components read and write to domain objects, they do it using mementos rather than working on the objects directly. The default memento is MACheckedMemento, a subclass of MACachedMemento. The mementos give Magritte a place to store invalid form data prior to allowing the data to be committed to the object. It also allows Magritte to detect concurrency conflicts for shared in image objects. By never committing invalid data to domain objects, there’s never a need to roll anything back. Should you feel the need, just override #mementoClass on your domain object to provide your own.
MAAccessor
When a memento writes valid data to its model, it does so through accessors which are also defined by the descriptions. MAAccessor subclasses allow you to define how a value gets written to your class. For example, while I have a read selector for my collections like #users, I prefer to encapsulate #add and #remove on the domain object itself rather than having a writable selector for #users:. When creating a description for that collection, I can specify my custom #accessor: rather than using the default #selectorAccessor: which then writes to my domain object with #addUser: and #removeUser:.
Another valuable use for accessors can be found when you want to flatten several domain objects into a single form. Say you have a User object with an Address object, and a CreditCard object but you want to edit them all as a single form. You can create your form and dynamically wire up some MAChainAccessors like so…
userTemplate
^((((CAUser descriptionEmail, CAUser descriptionPassword , CAUser descriptionConfirmedPassword)
addAll: (CAAddress description collect: [:each |
each copy accessor:
(MAChainAccessor accessor: (MASelectorAccessor selector: #address) next: each accessor)]);
addAll: (CACreditCard description collect: [:each |
each copy accessor:
(MAChainAccessor accessor: (MASelectorAccessor selector: #creditCard) next: each accessor)]))
yourself)
asComponentOn: self session user)
addValidatedForm: { (#save -> ‘Update Profile’)};
yourself.
Which basically just composes the users descriptions with the addresses and credit cards descriptions while chaining the accessors together to allow the addresses fields to be written to the address object rather than directly to the customer object. Any non trivial UI will contain many such forms and this is the ability I’m the most grateful for in Magritte. Also notice in the example above how I changed the label for the save button to “Update Profile”, also something you’ll need to do often that isn’t immediately obvious how to do.
MADescriptionComponent
Components control how your objects display. Magritte widgets are subclasses of this component. Some descriptions have an obvious one to one relationship with a UI component while others could easily be shown by several different components. For example, an MAMemoDescription would be represented by a text area, but a MABooleanDescription could be a checkbox, or a drop down with true and false, or a radio group with true and false.
Each description defaults to a component, but allows you to override and specify any component you choose, including any custom one you may write. For example, suppose I built a special component to render checkboxes as fancy graphics rather than ordinary html checkboxes. I could plug it in by changing the description as follows.
descriptionIsClosed
^ (MABooleanDescription new)
selectorAccessor: #isClosed;
label: 'Is Closed';
priority: 1000;
componentClass: CAFancyCheckbox;
yourself
These are essentially meta components written in standard Seaside. They work on mementos and have access to your descriptions. This is where all that meta data comes in handy. If you’re building a dropdown list, it’ll get its option list from the description. When you render an element’s label, that’s also read from the description.
When you build your own descriptions, you’ll add fields to them for custom data that you’ll want available in your custom components. At first, you’ll mostly use built in descriptions and components, but as you grow comfortable with Magritte you’ll start wanting to build your own descriptions and components because you’ll want to do things beyond the basic framework like Ajax. Magritte provides a solid foundation for extension.
MAComponentRenderer
By default, Magritte forms are rendered using MATableRenderer which renders the fields in a table with errors at the top and labels to the left of input fields. This is the default because it’s the easiest thing to do automatically that looks halfway decent. This can be overridden like so…
buildComponentFor: aModel
^((ModelClass descriptionFieldOne, ModelClass descriptionFieldTwo, ModelClass descriptionFieldThree)
componentRenderer: MACssRenderer;
asComponentOn: aModel)
addValidatedForm;
yourself
This hook allows you to render the form as you please, should you want to display errors differently, or change how elements are wrapped, or how the outer container itself is wrapped. It’s handy to control how container classes are tagged with css classes to have the form dynamically change its appearance for various phases like valid/invalid. If you don’t want your forms to look like auto-generated forms, you will use this.
For each of the classes I just described, you’ll want to pull up a hierarchy browser and explore all the subclasses to see examples of how they are specialized. Find some example projects in SqueakSource that use Magritte to see how others create custom descriptions and components. As with any framework, successful use depends on understanding it, and understanding how the pieces fit together. Magritte will not doing everything you want out of the box, it isn’t meant to, but it’s an excellent foundation to base your application on. It will save you many hours of tedious work building forms by hand. It will also give your objects extra metadata that you may find handy for purposes other than building forms.
Along with Seaside, Magritte is also an excellent example of extremely well written object oriented code that is worth reading to see exactly what it takes to make a truly flexible and pluggable framework. Because it was originally a masters thesis, it’s also far better commented than you’d likely find in a similar “real” world framework.