UML2MMBase User's Guide

Objects in the MMBase cloud are modeled with class files and attributes. In the following figure a sample MMBase object cloud is shown that represents a simple web site with menus, pages, articles, images etc. This model will be used to demonstrate the different possibilities of UML2MMBase. The following two figures show the UML model from which an MMBase application can be generated and a figure of the resulting edit wizards.

Figure 1. The sample UML model of an MMBase object cloud

Figure 2. The Edit wizards generated from the sample UML model

The class name specifies the name of a MMBase builder. The name should be specified in lowercase and no spaces can be used. The class has te be marked with the <<MMBase>> stereotype (that is case sensitive!). It is also possible to define classes without the <<MMBase>> stereotype if no builder has to be generated. This is the case for the core builders like images and attachments and can be used to implement search functionality to the basic builders. In the next figure the "article" object is shown.

Figure 3. The class definition of an article MMBase object

So in this sample class, 2 string attributes have been defined: title and author. The title field has been specified as public (this is displayed as a + sign in front of the attribute name). The author field has been specified as private (this is displayed as a - sign in front of the attribute name). Public and private is the visibility of an attribute and will be used to define which fields of an object should be used for searching and displaying information in lists in the edit wizards. Since the article class has been given de MMBase stereotype, which is displayed as <<MMBase>>, a builder will be generated for this class.

The following visibilties have been defined for attributes: public: visible in edit wizard, wizard list and search field. protected: visible in edit wizard and wizard list. private: visible in edit wizard. In some case you don't want to see a field in the wizard, but should be available in the builder file. In that case on a field, the system tagged value can be set to true.

The visibility of the class itself can be used to determine if the wizards should be accesible from the menu list. De class should be set to public to be in de list. Both protected and private classes will delete the wizard from the menu list.

The fields of a cloud object are specified with attributes. Both a field type and field name should be specified for the object fields. the fieldname is used to create a database table, so no special characters should be used. For the field types a list of all possible values is defined in the following table. Also the default sizes are specified that are used in the GUI (this may deviate from the database size).

The UML field type mappings to MMBase database types, gui types and sizes can be changed by editing a property file in the conf directory. This file is called: uml2mmbase-fieldtypes.properties. For example the key "html.gui.size" means that for the uml type "html" will be mapped in the edit wizards on the gui size of 1024. An example can be found in the following code fragment:

# Define the mappings of the fieldtypes to the gui sizes.
html.gui.size           =1024
float.gui.size          =20
double.gui.size         =20
string.gui.size         =40

For the article class two string attributes have been defined which will show up in the builder file as a gui name and type, editor positions and db name and type.

Gui name and type for the title field.

<gui>
   <guiname xml:lang="nl">title</guiname>
   <guiname xml:lang="en">title</guiname>
   <guitype>string</guitype>
</gui>

Editor positions for the title field.

Because the title field was set to public, the list and search positions are set to 4 which means they will be shown as a search or list fields in the 4th position.

<!-- editor related -->
<editor>
   <positions>
      <!-- position in the input area of the editor -->
      <input>4</input>
      <!-- position in the list area of the editor -->
      <list>4</list>
      <!-- position in the search area of the editor -->
      <search>4</search>
   </positions>
</editor>

Editor positions for the author field.

Because the author field was set to private, the list and search positions are -1. The means that this field won't show up as a search or list field.

         <editor>
            <positions>
              <!-- position in the input area of the editor -->
               <input>5</input>
               <!-- position in the list area of the editor -->
               <list>-1</list>
               <!-- position in the search area of the editor -->
               <search>-1</search>
            </positions>
         </editor>

Since the author of an article was set to private, in the edit wizards list the author won't show up.

Figure 4. A list of articles in the edit wizard for an article

Database name and type for the title field.

The database column name will be the attribute name converted to lowercase.

<db>
   <!-- name of the field in the database -->
   <name xml:lang="nl">title</name>
   <!-- MMBase datatype and demands on it -->
   <type key="false" notnull="true" size="50"
            state="persistent">STRING</type>
</db>

If a field in the object is mandatory, the <<required>> stereotype can be added to the field. This will result in a notnull="true" in the builder definition. In the edit wizard the input field will be mandatory and the object can't be save before the field is set.

In the sample model in the article object a <<required>> stereotype has been set on the title:

Figure 5. The stereotypes on the article title attribute

So in the builder for article for the title field the notnull attribute of the db type element is set to "true":

<type key="false" notnull="true" size="50"
 state="persistent">STRING</type>

The size of a a field can be specified using the tagged values minsize and maxsize. If these sizes are not defined the default sizes in the previous table will be used. For the title field of article the minsize has been set to 3 and the maxsize has been set to 50. As shown in the previous code snippet, the size attribute has been set to 50.

Figure 6. The tagged values on the article title attribute

The minsize and maxsize settings will also show up in the edit wizard xml files. If a new article is created with the edit wizards, the title field will be red because it is a required field and the save button will be inactive until all required fields have been filled.

Figure 7. En empty edit wizard form for an article

If a maxsize is specified for a string field the gui type in the edit wizard will be a text line if the maxsize <= 40. Otherwise a text area will be generated for the GUI. So for the title a text area is generated in the edit wizard. For the author field no maxsize has been specified so the default gui size of 40 will be used which results in a text line in the edit wizard. In the next picture a filled edit wizard form for article is shown where the title is a text area and the author is a text line. The save button has been activated.

Figure 8. A filled edit wizard form for an article

If a HTML field is specified, a required stereotype will be ignored due to a bug in the editwizards. If required is set, it is impossible to save an object since the validation on html fields will fail and the save button will never be activated.

The tagged value prompt can be used to overrule the prompt name in front of an input field in the edit wizards. By default the field name will be used as the prompt name. If a tagged value prompt is specified on a field, that value will be used as the prompt. It is also possible to specify tagged values on a class. Currently it is possible to specify the tagged values "title" and "subtitle". These values will appear in the Edit Wizards. For example for the teaser wizard in the UML model the title tagged value has been set as "Teaser" and the subtitle has been set to "A catchy phrase". This is shown in the following figure:

Figure 9. Tagged values title and subtitle on teaser class

These tagged values on the uml class will appear in the edit_teaser.xml file as 2 xml elements. These values will be displayed in the Edit Wizards, which can be seen in the following figure. In that figure is also shown that the prompt for the status field has been changed into: "Workflow status".

Figure 10. Edit Wizard of teaser with set Tagged values title and subtitle

A dependency between two objects defines a 0..1 to 0..N relation. The name of a dependency is used as the type of the relation. If the name isn't specified, the name of the dependency will be changed into "related".

Relations that are specified by a dependency are normally implemented by the insrel builder. If the name of the dependency is set to "posrel", the builder that is used to implement the relation is posrel. The posrel differs from the insrel builder in a way that also the order of the related objects can be specified. In the next figure an example of a dependency relation is shown between a report and a paragraph. This dependency has the name posrel because a report has an ordered set of paragraphs. The dependency also has the stereotype <<required>> because at least one paragraph has to be associated with a report.

Figure 11. A required posrel dependency relation between a report and a paragraph

A dependency can be given the stereotype <<required>>. If this stereotype is specified, the relation will be implemented as a 0..1 to 1..N relation. In the editwizards this will result in the requirement that at least one relation to the related object will have to be created before the object itself can be saved. In the generated XML files this will show up as a minoccurs="1" for the list element.

<list role="posrel" destination="paragraph" minoccurs="1" maxoccurs="*"
      orderby="field[@name='pos']" ordertype="number">

Figure 12. The required relation in the edit wizard

When using custom relations, it is also possible to define an option list in the relation. In the generated edit wizard it is possible to add both the relation fields and the fields of the related object. See for example the "menu_relation" between menu and menu_item. In the wizard the title field of the related menu_item can be edited, and the relation fields: "menu_type" and "option_list_test" can be also edited.

Figure 13. The relations and related object can be edited, including option lists.

An association between two objects defines a relation which can be specified in more detail than a dependency.

Relations that are specified by an association are normally implemented by the insrel builder. If the name of the association is set to "posrel", the builder that is used to implement the relation is posrel. The posrel differs from the insrel builder in a way that also the order of the related objects can be specified.

The upper and lower cardinality of the association can be specified on both the source as the target of the association. If the lower cardinality is set to a value above 0, the editwizards requires that at least one reference to an object is defined before the object itself can be saved.

The way an relation is navigable can be specified by the navigable properties of the association. If the navigable property is turned of, the relation to the object will not be displayed in the editwizard.

An association can be given two role names. When a role name is specified, this text will be displayed in the editwizard of the object. If no rolename is specified, the name of the object refered to will be displayed.

In the following example the association between a page and a report is shown. The rolename has been specified as "Publish this report on the page". The cardinality of the association is 0..1 which means that the relation is not required and at most 1 relation can be created.

Figure 14. Association relation between a page and a report

In the edit wizard of page the relation to the report is shown in the next figure.

Figure 15. Association relation between a page and a report in the edit wizard

The previous discussion about relations, assumes existing relation types are used like insrel and posrel. It is also possible to model a cusom relation type in UML. To define a custom relation type the <<Relation>> stereotype has to be used on a class diagram. The relation is assumed to inherit from the insrel builder, unless another object is explicitly used. In the following example a relation type: menu_relation has been model with a menu_type field which extends from the posrel relation. After the custom relation type has been defined, it can be used as the name of dependencies or assocations to use this relation type. In the example the menu_relation type has been used as the relation type on the association between menu and menu_item.

UML2MMBase will generate the builder for the custom relation type.

Figure 16. Custom MMBase relation type: menu_relation

The fields of the custom relation can be edited in the Edit Wizards. In the example it is possible to edit the pos field and menu type field in the relation between a menu and menu_item.

Figure 17. Custom MMBase relation fields in the edit wizard

It is also possible to create a relation definition for a custom relation. This way the same builder will be used for the specified relation. The relation can be modeled using a object class with the <<RelDef>> stereotype. The class should use a dependency relation to the custom relation type. In the following figure a reldef is modeled with an object class with name "menu_relation_reldef". The class has a dependency relation to the menu_relation object class. This will result in using the menu_relation builder for the menu_relation_reldef relation.

Figure 18. Reldef using a custom MMBase relation