Dynamic Web Development with Seaside

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.

An object is described by a description which is defined on its class

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 following Address 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:...).

Describing an Address

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

Copyright © 19 March 2024 Stéphane Ducasse, Lukas Renggli, C. David Shaffer, Rick Zaccone
This book is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 license.

This book is published using Seaside, Magritte and the Pier book publishing engine.