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' is possible). The goal is a freeform field used to identify the contextsource to the user.
<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).
When you finished the [application].xml file of your application, it is possible to make a graphical representation of your application. One remark: it is only possible to see the graphical representation if the MMBase installation you are working with is running on the computer on which you want to view the graphical representation. To view the graphical representation:
Sometimes the MMAppTool does not become the active window. So if you do not see anything happening after clicking "Yes", it might be that the MMAppTool is hidden behind the active window.
It is possible to change the layout of the graphical representation. See for instance the file MyNews/tools/mmapptoolconfig.xml for an overview of the possible settings that can be configured.
There exists a second tool for graphical representations of your application, which is developed by the Publieke Omroepen and provides fancier graphics. This tool is not included in the MMBase 1.6 release. If you would to try it out use the MMBase developers list to get a copy of this alternative tool.
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:
Another 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: documentation@mmbase.org