MMBase Applications
Example: the MyNews Application
The Application Configuration Files
How to Backup an MMBase Application
How to Install a MMBase application
Example: the MyNews Application
The Application Configuration Files
How to Backup an MMBase Application
How to Install a MMBase application
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 provides functionality to package an entire website build on top of MMBase. To package an entire website can be necessary. For instance, if you need to:
migrate your website from one database to another,
migrate your website from one MMBase version to another,
want to clean-up your object-cloud during or at the end of implementing a website in MMBase.
An MMBase application consists of:
configuration files: description of the cloud-structure, builders used in the cloud and the backup/export scenario,
the website's content exported in XML-format,
necessary Java functionality contained in MMBase modules,
the frontend of your website: a set of JSP-templates, XSLT, flash-animations, etc.
The term "application" is often only used for the configuration files and the website's content. Since a website is not complete without its templates and the necessary modules, this documentation also describes how you take care that templates and modules are also added to the package.
A number of demo applications are included in the MMBase release, like MyNews (an example of a magazine with news articles) and MyYahoo (an example of a page like the topic/url/search kind of interface first shown on yahoo and in the Netherlands known as startpagina.nl). You can easily install the MyNews application via the /mmexamples/install.jsp and have a look at the application in action at /mmexamples/jsp/mynews/index.jsp. In this document we will have a close look at the MyNews application and and use it to show how you can package your own MMBase applications.
All configuration files of the applications present in your MMBase installation are located in the directory /WEB-INF/config/applications. If you have a look at this directory, you will see that it contains a file called MyNews.xml and a directory MyNews. All MMBase applications follow this structure: an XML-file with the name of the application and a directory with the name of the application.
The XML-file with the name of the application contains the description of the cloud-structure used by that application. We will have a closer look at MyNews.xml to see the different parts:
<?xml version="1.0"
encoding="UTF-8"?> <!DOCTYPE
application PUBLIC "-//MMBase/DTD application config 1.0//EN"
"http://www.mmbase.org/dtd/application_1_0.dtd">
Every xml-document must have a reference to its document type
definition or dtd. For the applications version as implemented in
MMBase 1.6, the application_1_0.dtd is
used.
<application name="MyNews" maintainer="mmbase.org"
version="1" auto-deploy="false"> ...
</application>
The whole description of the cloud-structure is enclosed by
the application tag. The attributes name, maintainer, and version can be used to label the
application. The preferred way of writing names of applications is
to use capitalized words. The maintainer is the domain name of the
organization or person who takes the responsibility for updating
this application. The version number can be used to distinguish
different versions of your application. The property auto-deploy is important. The
application will automatically be installed the next time MMBase is
restarted, when auto-deploy is set to "true" and the application was
not already present in your MMBase installation. When auto-deploy is
"false" you can install the application manually via the MMBase
administrator pages (See the chapter "How to install an MMBase
application" for more information on this topic).
<neededbuilderlist><builder
maintainer="mmbase.org" version="1">mags</builder> ....
</neededbuilderlist>
The neededbuilderlist tag
contains a list of all the builders that are necessary to run this
application. Both the builders of regular objects and the builders
used to create relations have to be listed here.
<neededreldeflist><reldef source="related"
target="related" direction="bidirectional" guisourcename="Related"
guitargetname="Related" builder="insrel" /> ...
</neededreldeflist>
The neededreldeflist tag
contains a list of all relation roles that have to be defined for
this application. When you use the MMBase editors to have a look at
the RelationDefinition objects in your MMBase installation, you will
see how closely the <reldef ...
/> descriptions follow these objects.
The most import attributes of every reldef tag below neededreldeflist are `source' and
`builder', and the function of a `reldef' is actually to connect
those two. Another word for 'source' is 'role' (as it is called
often for example in taglib attributes). The `builder' refers to the
actual database table in which the relations can be stored, and
therefore defines which fields the relations of this type
have.
<allowedrelationlist><relation from="mags"
to="news" type="posrel" /> ...
</allowedrelationlist>
The allowedrelationlist list what type of
relation (what roles) should be used to relate two object of
specified type. When you use the MMBase editors to have a look at
the RelationType objects in your MMBase installation, you will see
how closely the <relation...
/> descriptions follow these objects.
The `from' and `to' attributes both refer to builder names
(and could also have been called `sourcebuilder' and
`destinationbuilder' or `sourcenodetype' and `destinationnodetype').
The `type' attribute then actually defines the role for this allowed
relation, so these correspond to the `source' attributes of the
reldef tags.
<datasourcelist><datasource builder="mags"
path="MyNews/mags.xml" /> ...
</datasourcelist>
The datasourcelist tag
specifies where MMBase has to look for the content to fill each
object when case the application is installed. The datasourcelist only contains the
datasources of regular objects and does not contain relations. When
images or attachments are included in the application, MMBase will
use subdirectories of the MyNews directory to store the images and
attachments. The MyNews/images.xml and the MyNews/attachments.xml
contain the handles to these files.
<relationsourcelist><relationsource
builder="insrel" path="MyNews/insrel.xml" /> ...
</relationsourcelist>
The relationsourcelist
tag specifies where MMBase has to look for the content to fill each
relation in case the application is installed.
<contextsourcelist><contextsource
path="MyNews/backup.xml" type="depth"
goal="backup"/></contextsourcelist>
The contextsource tag
specifies where MMBase has to find the backup (export) scenario for
this application. The path
specifies where to find the file. the type attribute specifies the export
algorithm to use. Currently, only 'depth' and 'full' (see below) are
supported. The goal is a
freeform field used to identify the contextsource to the user
<contextsourcelist><contextsource type="full" goal="backup"/></contextsourcelist>
Using type="full" provides the possibility of making a full backup of your objectcloud in XML.
<description><![CDATA[MyNews is ...]
]></description>
The description is used
as an introduction to the application in the MMBase install pages
and the MMBase admin interface.
<install-notice><![CDATA[The MyNews
application is installed ...]
]></install-notice>
The install-notice is
shown in the MMBase install pages and the MMBase admin interface
after successful installation of the application. It is not possible
to add messages to the application configuration file, which are
shown in case the application fails to install.
The builders specified in the neededbuilderlist
can be found in the application folder under
[applicationname]/builders. I.e., for the MyNews
application, the builders can be found in the directory
MyNews/builders/.
The contextsource specifies where the file with
the backup scenario for this application is located - specified in its
path attribute. For MyNews we saw
that this is "MyNews/backup.xml".
Most applications come with a 'backup.xml' file that describes the
startpoint for exporting data (as described below). It is not necessary
to specify a file - i.e. if an application is only meant to be installed
and not exported. You can also use other filenames (though 'backup.xml'
is the convention) or specify multiple contextsources. In the latter
case, the administration pages require the user to choose the
contextsource with which to make the export, using the freeform goal attribute to give user-feedback on the
intention of the contextsource.
While we speak about "backup" here, the system can also be used to simply export certain parts of your cloud, for instance for sharing with others, or porting data from a test environment to a production environment.
The way MMBase makes a backup of the content in an application in
the form of XML-files needs special attention. To be able to determine
which objects are necessary for an application and have to be
incorporated in the backup and which objects are not, MMBase uses a
backup algorithm. The backup algorithm to use is specified in the
type attribute. Currently, the only
algorithm available for export is 'depth' (Future implementations may
involve more algorithms).
The 'depth' backup algorithm starts at the startnode specified in the context source (i.e. "backup.xml") file. The startnode is written to the appropriate XML backup file and MMBase searches for nodes related to this startnode, which are not already included in the backup. These new nodes are now taken as the startnodes and the whole process repeats as long as their are nodes found that have not already been included in the backup or until the maximum depth as specified in backup.xml is reached.
The backup scenario that MMBase uses is a very elegant way to clean up the content in your application from objects that are not used anymore or that have been the result from mistakes in the development process. However a drawback of this scenario is that objects that can not be reached from the startnodes specified in the context source file will not be incorporated in the backup.
If you have a look at this file you see that it consists of the following tags:
<contextdepth>
The tag <contextdepth> encloses the specification of the backup scenario.
<startnode>
The startnode specifies which node should be used by MMBase as the start of the backup algorithm. The startnode can be specified in one of two ways:
<builder>mags</builder><where>title=='MyNews
magazine'</where>
The backup algorithm starts at the mags object with the title "MyNews magazine". If there are multiple objects that fit the algorithm, the first one found is chosen. It is not possible to determine which object that will be.
<startnode alias="mynewsmagazine"
/>
The backup algorithm starts at the object with the objectalias "mynewsmagazine".
<depth>5</depth>
Specifies the depth of the search (the maximum number of nested searches) used in the backup algorithm (in the example this is 5 levels deep).
The application configuration files can be used to backup the
content of the website in XML-files. When you look at the
/WEB-INF/applications/MyNews/ directory, you see the
XML files with the content of the MyNews application. If you open for
instance mags.xml with a text-editor, you
find:
<mags
exportsource="mmbase://www.mmbase.org/mmexamples/mynews"
timestamp="20020516170724">
The mags tag encloses the
content of the mag objects. The attributes of the mags tag give an
indication from where the backup of the application is made (TODO the
semantic of exportsource is not clear) and specifies the time when the
backup of the application has been made.
<node number="8495" owner="system"
alias="default.mags">
The node tag specifies a node
with its number, owner and aliases (if any). It also includes tags and
content for each field in the node (using the fieldname as the name of
the tag).
MMBase renumbers the objects in the application when restoring the application. This means that for example the node with alias "default.mags" is very likely to have a different node number than "8495". This is another reason to not use numbers of objects in your templates.
Ones you finished the [application].xml of your MMBase application, you can use it to make a backup of the content in your website in XML. To this end:
After you clicked the "Yes" button, MMBase shows some statistics of the backup procedure. When using the configuration files of your application for the first time, it is recommended to examine these statistics closely. It might be that you forgot to specify a relation or that some parts of the content can not be reached from the startnodes. This is the first spot to notice such errors!
Instead of installing an MMBase application the term "restoring" (for a backup) or "loading" an MMBase application is frequently used.
You can install (or restore) a MMBase application as follows:
/WEB-INF/config/applications/
directory/WEB-INF/config/applications/[applicationname]
directory/WEB-INF/config/builders/ or one of its
subdirectories. You can also place the builders in the
/WEB-INF/config/applications/[applicationname]/builders
directory, and let the application install your builders. Note that
this requires that MMBase has the right to write in the
configuration directoryAnother way to restore an MMBase application is set auto-deploy to "true " after step (3) and restart MMBase. You can view the log file to see of the restore of the application was carried out correctly.
Some MMBase applications need additional functionality contained in one of the MMBase modules. For instance, it might be possible that your application requires the MMBase sendmail module to send email or that it is using the communityprc module for the forum. When packaging your application be sure to notice all necessary modules in the install instructions.
The frontend of your website (a set of JSP-templates, XSLT, flash-animations, etc.) will be located in the default-web-app directory and/or in one or more subdirectories. For example the templates of the MyNews application are located in /mmexamples/jsp/mynews/ If you package your application be sure to add these files and directories to the package.
This is part of the MMBase documentation.
For questions and remarks about this documentation mail to: [email protected]