Creating a relation object type with the fields that are necessary in the relation
Assign a role to the in the list of relation definitions (reldef)
Enter the source-relation-destination information into the list of allowed relations (typerel)
This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.
The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license
Table of Contents
MMBase is an object oriented content management system. I.e. text, images and other content are stored in objects, objects are connected by relations, relations are objects themselves. The most basic relation of these, is the relation that can be used to connect two objects, but does not contain any content itself. This relation which does not contain any additional information is normally called "related". Often it is not enough to make a relation between two objects. For instance, when adding news items to a magazine one also needs a way of telling in which sequence the newsitems should occur. In MMBase one can use the "posrel" relation for this purpose. The "posrel" not only connects two objects, but it also allows you to store an integer value in this relation. To this end you use the "pos" field of the relation. In general, you can create relations with whatever fields you need for your content model. For instance, when connecting employees to departments one can use a relation which contains an extra String field to store information on the function(s) an employee has in his/her department(s).
This document provides information on how to create and use relations. Before you can actually start creating relations between MMBase objects, you must assert that this relation can be understood by MMBase. This means that you must assert the following three things.
A relation object type (`builder') with the fields that are necessary in the relation must be created. If a suitable object type already exist, then you can immediately go to the next step. The base type for relation types is called `insrel'.
Assign a `role' to the relation in the list of relation definitions (`reldef'). The same builder could be assigned to more than one role. Normally the role `related' exists and is assigned to the base relation object type (`insrel'). The role `posrel' is normally assigned to a relation object type `posrel' which extends the base relation type insrel, and adds the `pos' field.
It must be defined which source-type/role/destination-type combinations are allowed by MMBase. You do this by entering `typrel' entries. You can define here e.g. that relations from `news' to `people' with the role `author' is possible.
The following image provides a graphical representation of these steps. In the sections that follow the details of each step will be described.
This document assumes that you are familiar with the following concepts:
Objects and and object types (`builders'). If not, please read the "Builder configuration file " in the "Administrators " section.
Applications. If not, please read the "Application " manual in the "Administrators " section.
Like normal objects, relations are of a certain type (`are created by a certain builder'). We will have a closer look at two standard object type definitions used for relations: insrel (defined in insrel.xml) and posrel (defined in posrel.xml).
The insrel.xml builder definition defines the base type for relation objects. A relation object connects to other objects witch each other. One of the other objects is named the source and the other is the destination. Have a look at the insrel.xml builder in /config/builders/core/. The insrel.xml builder differs from builders of regular objects in the following ways.
<classfile>org.mmbase.module.corebuilders.InsRel</classfile>
The functionality of the insrel relation is defined by the Java class InsRel
<field> snumber
Object number of this relation's source object
<field> dnumber
Object number of this relation's destination object
<field> rnumber
Reference to the 'role' object of reldef (see next section).
<field> dir
The `directionality' of this relation, can be uni or bi-directional (0 or 1). This can possibly override the same value which was associated with the role object, but is mainly present here too, to make the SQL queries perform better (because no direct connection to the reldef table is needed then).
Directionality only tells something about the visibility of the relation. A unidirectional relation is not visible from the destination node.
Have a look at the posrel.xml builder in the MyNews application. The posrel.xml builder extends the insrel.xml builder with the field `pos'. When connecting two objects by using the posrel relations, you can use this pos field to store an integer value. The posrel relation also uses the Insrel class for some additional functionality.
By extending the insrel.xml builder with more and different fields, you can construct whatever relation you like to use.
In the previous section we saw what a builder for a relation looks like. You can use these builders to create relations. Every relation instance also has a certain role. The existing roles are defined in the `reldef' table. In this reldef object type you have to set the following fields.
role (sname)
The name of the role which is assigned.
target-role (dname)
The role as seen from the destination node. This can be used in combination with the role, to further specify it.
dir
Whether the relation is visible both from the source and the target (bidirectional) or the relation is only visible from the source (unidirectional). It does not define the direction of the relation.
sguiname
The name of the source node in this role. This is used in (generic) editors.
dguiname
The name of the destination node in this role. This is used in (generic) editors.
builder
The builder which defines the data to store the relation, and optionally adds some specific functionality to it (by the java class).
Example 1. Roles (reldef)
In the screenshot above their are four relations defined.
Related/Related
This is the default relation that can be used to connect two objects
Posrel/Posrel
This is the relation that contains an integer field in the relation. It is based on the posrel.xml builder.
Parent/Child
This relation is based on the insrel.xml builder. Seen from the source the relation is called "child ", seen from the target the relation is called "parent ".
Body
This relation is based on the posrel.xml builder and thus contains an integer field. Seen from the source the relation is called "member ", seen from the target the relation is called "(body) (hidden) "
As you see, a single builder can be used to define more than one relation. In the example above, both the Related and the Parent/Child relation are based on insrel.xml. Defining relations with different names is handy when two objects are connected to each-other for different reasons. E.g. a magazine is connected to a person via an author and via a publisher relation, where both author and publisher are defined by using the insrel.xml.
In the previous section we saw how we can define relation roles in MMBase. Principally you could be ready now to create actual relation instances. You could take two object and connect them by a `role'. The role defines also the relation builder, and therefore the extra fields which can be filled in the relation object itself.
But MMBase enforces us to explicitely define what kind of relations are possible. For example you have to explicitely state that relations between news nodes and people nodes with the role `author' are allowed.
This extra requirement makes generic editors a lot simpler, because MMBase can offer only the possibility to relate people to news articles (and what else is defined), and there is no need to add buttons for every permutation of object types and roles, which would make such editors very complex.
The other advantage is that database queries can be optimized using this information about which relations are possible. So, though it could be tempting to allow the relation from any object to any object (because of `inheritance' this is perfectly possible), it would be inadvisable to do so. Generally you should limit yourself to relation types which you are actually going to use. Using `inheritance' in allowed relation definitions is possible, but use it sparingly.
When `following' relations in the front-end, this on default tries to follow them in `both' directions (if both are possible). If the object type on both sides of your allowed relation type is the same, you could therefore consider making the relations unidirectional. Otherwise in the resulting queries lots of `OR' constraints may arise which is generally very bad for performance. The option is to specify the `search direction' on every query you do between to objects of the same type.
For the same reason you should also avoid to allow the same relation in both directions. It's better to allow the `author' relation only from news to people, and not also from people to news.
If you have a look at the typerel objects, which define the allowed relations, in generic editors, you see that you can set the following fields.
snumber
The builder which objects function as the source for this relation.
dnumber
The builder which objects function as the destination for this relation.
rnumber
The number of the `role' object used to connect the source to the destination.
max
The maximum number of relations between the source and its destination objects.
Although you can set the number of relations, the functionality to check on this maximum and signal a warning if the maximum is reached is not yet implemented in MMBase. You can safely ignore this field.
Example 2. Allowed relations types (typerel)
The image above provides the typerel objects present in an MMBase installation after the Resources and the MyNews applications are installed.
Related/Related
This is the default relation that can be used to connect two objects
Posrel/Posrel
This is the relation that contains an integer field in the relation. It is based on the posrel.xml builder.
Parent/Child
This relation is based on the insrel.xml builder. Seen from the source the relation is called "child ", seen from the target the relation is called "parent ".
Body
This relation is based on the posrel.xml builder and thus contains an integer field. Seen from the source the relation is called "member ", seen from the target the relation is called "(body) (hidden) "
As you see, a single builder can be used to define more than one relation. In the example above, both the Related and the Parent/Child relation are based on insrel.xml. Defining relations with different names is handy when two objects are connected to each-other for different reasons. E.g. a magazine is connected to a person via an author and via a publisher relation, where both author and publisher are defined by using the insrel.xml.
The field names for the builders and relations are called snumber, dnumber and rnumber, because the builders are specified by the object numbers from the typedef table and the relations are specified by the object numbers from the reldef table. In generic editors you should however see nice drop down boxes.
Every interface to the MMBase cloud provides its own way for creating relations. We will have a look at how we can relate people to news in the MyNews application.
In the previous section we saw that after the Resources and the MyNews application are installed, the list of allowed relation types contains for instance the relation from people to news. When selecting somebody from the list of people, the following screen appears. New newsitems can be added to this person by clicking on the plus-signs in the right column in the row which starts with News.
The posrel builder is extended from the insrel builder. This means that each creation of a posrel also means a creation of an insrel.
The following list provides an overview of where to look for information on how to create relations in the other interfaces.
JSP-templates
See the <mm:maycreaterelation /> and <mm:createrelation /> in the MMBase taglib reference in the Templaters and Designers section.
XML-templates
See the <getnewrelation /> in the Dove XML API in the Developers section
Editwizards
See the <action type= "create " /> in the <list /> tag in the Editwizard documentation under the Templaters and Designers section.
Every interface also provides its own way for using relations. In the mmeditors one can use the arrow-signs to view the relation and the related objects. See for instance the image shown in the previous section. When clicking on the arrow-sign before "MMBase goes Open Source " one can view the relation that connects the person "Rob " to the "MMBase goes Open Source " newsitem. When clicking on the arrow-sign after "MMBase goes Open Source " one goes directly to the related newsitem.
Information about using relations in other interfaces to the MMBase cloud is listed below:
JSP-templates
See the <mm:list /> and <mm:listrelations /> in the MMBase taglib reference in the Templaters and Designers section.
XML-templates
See the <getrelations /> in the Dove XML API in the Developers section
Editwizards
See the <list /> tag in the Editwizard documentation under the Templaters and Designers section.
This is part of the MMBase documentation.
For questions and remarks about this documentation mail to: [email protected]