26.1Basic Principles
In this section we present the key principles. With such knowledge you can get 80% of the power of Magritte without knowing all its possible customizations. The key idea behind Magritte is the following: given one object with a set of values, and a description of this information, we will create automatically tools that treat such information and for example automatically create Seaside components. Figure 159 shows that a person address’, John’s address, instance of the class Address, is described by a description object which is attached to the class Address. A program (i.e., database query, generic UI, seaside component builder) will interpret the value of the instance by using its descriptions.
Here are the basic description assumptions:
- An object is described by adding methods named
description
(naming convention) to the class-side of its class. Such description methods create different description entities. The followingAddress
class method creates a string description object that has a label ’Street’, a priority and two accessors street and street: to access it.
Address class>>descriptionStreet
^ MAStringDescription new
accessor: #street;
label: 'Street';
priority: 100;
yourself
Note that there is no need to have a one to one mapping between the instance variables of the class and the associated descriptions.
- All descriptions are automatically collected and put into a container description when sending
description
to the object (see Figure 160). - Descriptions are defined programmatically and can also be queried. They support the collection protocol (
do:
,select:
...).
Obtaining a component. Once an object is described, you can obtain a Seaside component by sending to the object the message Object>>asComponent
. For example to get a component for an address: anAddress asComponent
.
It is often useful to decorate the component with buttons like cancel and Ok. This can be done by sending the message WAComponent>>addValidatedForm
to the component. Note that you can also change the label of the validating form using addValidatedForm:
and passing an array of associations whose first element is the message to be sent and the second the label to be displayed.
A Magritte form is generally wrapped with a form decoration via WAComponent>>addValidatedForm
. 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.
anAddress asComponent addValidatedForm.
anAddress asComponent addValidatedForm: { #save -> 'Save'. #cancel -> 'Cancel' }.
A description container is an object implementing collection behavior (collect:
, select:
, do:
, allSatisfy:
, ...). Therefore you can send the normal collection messages to extract the parts of the descriptions you want. You can also iterate over the description or concatenate new ones. Have a look at the MAContainer
protocol.
You can also use the message MAContainer>>asComponentOn:
with aModel to build or select part of a description and get a component on a given model. The following code schematically shows the idea: two descriptions are assembled and a component based on these two descriptions is built.
((Address descriptionStreet , Address descriptionPlace)
asComponentOn: anAddress) addValidatedForm