HOW TO: Add a custom function to a nodebuilder

Author: Willem Voogd
Date: 2004-04-15

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

Abstract

This How To provides information on how to specialize the MMObjectBuilder class so that custom functionality for a builder can be implemented.

This How-To is based on functionality provided by MMBase 1.7.0

Table of Contents

1. Introduction

2. Implementation

2.1. The node builder
2.2. The Java Class
2.3. The JSP file
2.4. The Application

3. Deployment

4. How does it work?

5. Next Steps

1. Introduction

We are going to implement the 'Hello World' paradigm. Our implementation will take a person object, which has a name, and say 'Hello' to it.

This means we will need an object called Person, which has one attribute called name. Then we want to create a custom function for the builder that greets the person it is called upon.

To implement this functionality we are going to create three files:

person.xml
PersonBuilder.java
helloperson.jsp

2. Implementation

2.1. The node builder

First we are going to take a look at the implementation of our node builder, person.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE builder PUBLIC "-//MMBase//DTD builder config 1.1//EN" "http://www.mmbase.org/dtd/builder_1_1.dtd">

<builder name="persons" maintainer="thedutchrepublic.com" version="0" extends="object">
  <status>active</status>
  <classfile>org.mmbase.examples.howtos.builders.PersonBuilder</classfile>
  <names>
    <singular xml:lang="en">Person</singular>
    <singular xml:lang="nl">Persoon</singular>
    <plural xml:lang="en">Persons</plural>
    <plural xml:lang="nl">Personen</plural>
  </names>

  <descriptions>
    <description xml:lang="en">A Person</description>
    <description xml:lang="nl">Een Persoon</description>
  </descriptions>

  <fieldlist>
    <field>
      <descriptions>
        <description xml:lang="en">The name of the person</description>
        <description xml:lang="nl">De naam van de persoon</description>
      </descriptions>
      <gui>
        <guiname xml:lang="en">Name</guiname>
        <guiname xml:lang="nl">Naam</guiname>
        <guitype>string</guitype>
      </gui>
      <editor>
        <positions>
          <input>2</input>
          <list>2</list>
          <search>2</search>
        </positions>
      </editor>
      <db>
        <name>name</name>
        <type state="persistent" size="255" notnull="false" key="false">STRING</type>
      </db>
    </field>
  </fieldlist>

</builder>

In this builder a person object is specified, with just one attribute, the persons name. Of course there are much more attributes possible for a person object, such as different fields for surname and familyname, infixes, birth date and stuff like that. For this how to however, we just need to know a persons name.

2.2. The Java Class

We want a function on the person object that greets the person, when called. This will be just a simple message as “Hello [NameOfPerson]”.

We will call the file PersonBuilder.java so that it is evident to which builderfile it is related.

/* PersonBuilder.java
 * Created on Apr 8, 2004
 *
 * Reviewed By	| Review date	|Modified By  | Modified date | Modification
 *  - - - - - - +  - - - - -  + -- - - - - -+ - - - - - - - + - - - - - - - -
 *              |             |Willem Voogd | Apr 8, 2004	  | Initial Creation
 */

package org.mmbase.examples.howtos.builders;

import java.util.List;

import org.mmbase.module.core.MMObjectBuilder;
import org.mmbase.module.core.MMObjectNode;
import org.mmbase.util.functions.Parameter;

/**
 * PersonBuilder
 * @author willem
 *
 * The PersonBuilder is the source class voor the Person builder.
 * It suplies a function that says Hello to the person.
 */
public class PersonBuilder extends MMObjectBuilder {
    public static final String F_GREETING="hello";

    /**
     * Says hello.
     *
     * @param node, the node (menuitem) for which the string must be build.
     * @return helloString, the greeting.
     */
    protected String getGreeting(MMObjectNode node) {
        String helloString = "Hello ";
        helloString += node.getStringValue("name");
        return helloString;
    }

    /**
     * overridden from MMObjectBuilder
     *
     * Gets the parameters for the functions.
     * We only have one custom function w/o parameters, so we need an empty array.
     */
    public Parameter[] getParameterDefinition(String function) {
        if (function.equals(F_GREETING)) return new Parameter[0];
        return null;
    }


    /**
     * overridden from MMObjectBuilder
     * executes a given function and returns the result of that particular function.
     *
     * @param node
     * @param function
     * @param arguments
     */
    protected Object executeFunction(MMObjectNode node,String function,List arguments) {
        if (function.equals(F_GREETING)) {
            return getGreeting(node);
        } else {
            return super.executeFunction(node,function,arguments);
        }
    }
}

2.3. The JSP file

In order to call the function we have to use the <mm:function /> tag inside the jsp. When you are already in a node it can be done by just calling the name for the function, as it is wrapped by executeFunction.

<%@taglib uri="http://www.mmbase.org/mmbase-taglib-1.0" prefix="mm" %>
<%@page session="false" %>
<html>
  <body>
    <mm:import externid="person">johndoe</mm:import>
    <mm:cloud   name="mmbase">
      <mm:node number="$person">
        <mm:function name="hello" />
      </mm:node>
    </mm:cloud>
  </body>
</html>

2.4. The Application

Hello.xml:

<?xml version="1.0"?>
  <!DOCTYPE application PUBLIC "-//MMBase/DTD application config 1.0//EN" "http://www.mmbase.org/dtd/application_1_0.dtd">
  <application name="Hello" maintainer="mmbase.org" version="0" auto-deploy="true">
    <neededbuilderlist>
      <builder maintainer="mmbase.org" version="0">persons</builder>
    </neededbuilderlist>
    <neededreldeflist>

    </neededreldeflist>
    <allowedrelationlist>

    </allowedrelationlist>
    <datasourcelist>
      <datasource builder="persons" path="Hello/persons.xml" />
    </datasourcelist>
    <relationsourcelist>

    </relationsourcelist>
    <contextsourcelist>
      <contextsource path="" type="full" goal="fullbackup"/>
    </contextsourcelist>
  </application>

persons.xml:

<?xml version="1.0" encoding="utf-8"?>
<persons exportsource="mmbase://127.0.0.1/builderclass/mm" timestamp="20040408144622">
  <node number="28" owner="admin" alias="johndoe">
    <name>John Doe</name>
  </node>
</persons>

3. Deployment

To deploy the application, first do the normal MMBase install stuff, then create a structure like this:

- Hello.xml
- [Hello]
  - [builders]
    - persons.xml
  - persons.xml

Where the names between brackets ([]) are directories and the persons.xml file directly under the Hello directory is the data file.

Place both the Hello directory and the Hello.xml file directly in the WEB-INF/config/applications directory and put the helloperson.jsp in the home directory of the webapp.

4. How does it work?

The <mm:function /> tag results in a call to executeFunction() on the class specified in the classfile tag in the builderfile for the node the function is called upon. However, before that call takes place, first a call to getParameterDefinition is made, which for PersonBuilder results in an empty List. PersonBuilder.executeFunction(node, “hello”, list) is called, where 'node' is the node in who's scope the function tag is placed.

executeFunction is a wrapper for the function we actually want called, being getGreeting. The result is passed back to the jsp, resulting in 'Hello John Doe'.

5. Next Steps

Of course, the example given in this how to could more easily be implemented, not needing a custom java builderclass. This is the most basic example of how to add custom functionality to your builder. You could also make the greeting intelligent, wishing the person a goodmorning, goodafternoon, goodevening or goodnight, depending on the server's system time, for example.

In the next how to we will deal with parameters.

This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: documentation@mmbase.org