The Richtext Functional Reference

Abstract

This functional reference contains a description of the richtext xml format, the richtext editor based on kupu and the use of richtext in your (xslt) templates.


Richtext is text which contains (links to) other objects. For instance a text that contains images, links to pages in the same web application, or links to external web pages. This text is saved in MMBase as XML. The nice thing about saving text as XML is that all references to other objects are real MMBase relations. So when the referred object is deleted, the link in the richtext is also automatically removed. Another advantage is that with XSLT (xml-style sheets) the conversion to HTML is straightforward (and some say easier than JSP).

Richtext should not be confused with the html-area, used in the editwizard. The text of html-area in the editwizard is saved in MMBase as HTML. Links in the HTML are urls. This means that when the referred object is deleted, the link will not automatically be removed. Another disadvantage is that the HTML can contain undesirable code, like Microsoft Word styles that are copied into the html-area.

Throughout this document the MyRichText application is used as the example application for the richtext editor. So to experiment with the examples in this document both the richtext editor has to be installed in your webapp and the MyRichText application has to be deployed. All the path in this document assume that the webapp which you are using has the name richtext.

The database definition of the richtext field with the name body in the texts.xml builder looks like:

<datatype base="mmxf" xmlns="http://www.mmbase.org/xmlns/datatypes" />
<db>
   <name>body</name>
   <type key="false" notnull="false" size="64000" state="persistent">XML</type>
</db>

The richtext editor is based on kupu. MMBase use kupu to show the richtext field in your builder, with all the richtext functionality. The present implementation of the richtext editor assumes that there is at most one richtext field in an MMBase node. After saving the object in the richtext editor, the HTML produced by kupu is translated into XML by MMBase.

The text in the richtext editor shown in the previous section is saved as the following XML.

<mmxf xmlns="http://www.mmbase.org/xmlns/mmxf" version="1.1">
<p>
   <a id="_1134140609"/>
   Richtext is text which contains (links to) other objects.
</p>
<p>
   Richtext should not be confused with the html-area, used in the editwizard.
</p>
<p>
   <table class="plain">
      <tr>
         <td> </td>
         <td>TEXT</td>
         <td>HTML</td>
         <td>XML </td>
      </tr>
      <tr>
         <td>Link to another object</td>
         <td>tags </td>
         <td>hyperlink </td>
         <td>real relation </td>
      </tr>
      <tr>
         <td>Templating</td>
         <td>JSP </td>
         <td>JSP</td>
         <td>XSLT </td>
      </tr>
   </table>
</p>
<p><a id="_1134140611"/></p>
</mmxf>

When you look in one of the default MMBase you will see that the objects, linked in the text, are related to the object containing the text field.

This XML can parsed by an XML style sheet (XSLT) to generate an HTML page.

One of the basic things that have to be done when creating HTML from XML to create hyperlinks from the idrels in the XML. To make this possible we have to tell MMBase how a link to a related object looks like. The mapping from idrels to hyperlinks is done in the

<functionlist>
  <function 
    name="url"
    key="{REQUEST.getContextPath}/{INITPARAM.npbsales.home}?article={NODE.number}&amp;template=article"
    >
    <class>org.mmbase.util.functions.PatternNodeFunctionProvider</class>
  </function>
</functionlist>

Most of the parameters used in the function definition are generated automatically, the INITPARAM.xyz are specified in the /richtext/WEB-INF/web.xml. The parameters are handled by the org.mmbase.util.functions.PatternNodeFunctionProvider.java.

You can use the list.jsp which is also used by the editwizards to open the richtext editor. The request parameters that are new as compared to the use of list.jsp for the editwizards are: wizardjsp, kupu_back, tools and link_nodetypes. The entire url is explained in the following table. Please have a look at the editwizard documentation to learn more about the request parameters of list.jsp.

Table 1. Example of request parameters in the link to list.jsp

<a href="/richtext/mmbase/edit/wizard/jsp/list.jsp?the list.jsp from the edit/wizard application is used
&wizardjsp=/richtext/mmbase/kupu/mmbase/the editor that is opened by the list.jsp (of course for using the richtext editor this should be mmbase/kupu/mmbase). This could as well be /richtext/mmbase/kupu/mmbase/index.jsp
&kupu_back=/richtext/edit/used for the backbutton in the richtext editor. This could as well be /richtext/edit/index.jsp
&tools=relatedtools can be used to dynamically include extra functionality in the richtext editor. When you want to add more tools you can add them in a comma seperated list. In this example the tool is: /mmbase/kupu/mmbase/tools/related.jspx. The tools are shown in the leftpanel of the richtext editor.
&link_nodetypes=urls,attachments,products,newsin the link_nodetypes you can specify the type of objects that can be linked to in the richtext
&wizard=kupu/news This is the editwizard definition used by list.jsp. This editwizard are located in the directory of the calling page, /richtext/edit. The only actions in the kupu/news.xml that are relevant when using the richtext editor are the create and delete action.
&nodepath=categories,related,newsthe path that should be followed from the startnode
&searchdir=destinationthe direction in which the nodepath should be used
&startnodes=347the node for which the related objects have to be shown
&origin=347the node number that can be used in the create statement of the editwizard
&orderby=news.numberthe field on which the list is ordered
&directions=downthe direction in which to sort the list, up or down
&search=yeswhether or not a search box should be displayed on top of the list
&title=Hometitle of the list
&referrer=/edit/index.jspxnot in use for the richtext editor
&language=enthe language to be used in list.jsp and the richtext editor
">NewsItems</a>the word to click on (but if you didn't know this you probably need some other documentation before continuing this one)

In the example application the link to list.jsp is generated by ROOT\edit\cat.template.as.jspx. The entire include path from the index.jspx is: index.jspx -> content.div.jspx -> cat.li.jspx -> cat.template.as.jspx.

The richtext editor contains a three panels:

  • the left panel: with the tool list controlled by the "tools=" parameter and the none richtext fields of the object

  • the middle panel: with the richtext field of the object. The link icon in the header of this panel uses the object types from link_nodetypes. The present implementation assumes that there are images and blocks related to the richtext object via idrel.

  • the right panel: with the rich text functionalities like link-editting, images, tables and blocks

The chapter first shows how the MyRichNews generates HTML from the XML stored in the richtext field. Then an example shows how to reuse parts of the example to build your own HTML pages.

Although it has nothing to do with richtext, this section starts with an overview of the templating mechanism used in MyRichNews. This is introduction is only there to show you where to find the files which are actually showing the richtext fields. The HTML is generated by richtext/index.jspx, which includes the file specified by the url field from the template object related to the selected category. It passes the subcat@cat and class id to this include as request parameters. The file included for the Home category is texts.div.jspx.

<mm:include referids="subcat@cat,class" page="${_node.url}" escape="none" debug="html" />

The include texts.div.jspx generates a list of links for the texts related to the category. The template parameter in these links is set to "article". Bij clicking on these links the following piece of code in index.jspx is used to show the include article.div.jspx.

<mm:present referid="template">
  <mm:include  page="search.div.jspx"><mm:param name="class" value="left" /></mm:include>
  <mm:include  referids="subcat@cat" page="${template}.div.jspx" escape="none" debug="html" />
</mm:present>

The include article.div.jspx uses /util/body.jspx to show the richtext field.The body.jspx looks like:

<mm:formatter 
  xmlns:mm="http://www.mmbase.org/mmbase-taglib-2.0" 
  xslt="xslt/2xhtml.xslt" escape="none">
   <mm:listrelationscontainer role="idrel" searchdir="destination">
     <mm:listrelations>
       <mm:relatednode>
         <mm:listrelations role="idrel" searchdir="destination">
           <mm:relatednode />
         </mm:listrelations>
       </mm:relatednode>
     </mm:listrelations>
   </mm:listrelationscontainer>
   <mm:field name="body" />
</mm:formatter>

The formatter tag is used to add layout to the objects listed inside the formatter tag. The xslt used is xslt/2xhtml.xslt. This file can be found in the /richtext/xslt directory. The file /richtext/xslt/2xhtml.xslt extends the file mm:xslt/2xhtml.xslt by using the <xsl:import /> tag. The file mm:xslt/2xhtml.xslt is part of the mmbase-richtext.jar in your distribution. If you have a archiving tool which can uncompress jar-files you will find the file in the /config/xslt directory of this jar. In the MMBase CVS the file is located in applications/richtext/config/xslt.

The mm:xslt/2xhtml.xslt contains extends from mmxf2xhtml.xslt. In the mm:xslt/2xhtml.xslt the link to objects related to the richtext object is generated by using the node function with the name 'url': node:function($cloud, string(@id ), 'url', $request).

The HTML generated from the XML in section 2 is:

<div class="block article">
   <h1>Richtext !!!</h1>
   <div class="intro">
      <p></p>
   </div>
   <div class="objects">
      <div class="mmxf">
         <p>
            <a onclick="window.open('/richtext/mmbase/images/1193', 'MMBeest', 'width=404,height=720');"
               href="javascript: void(0);"
               title="MMBeest"
               id="_1134211110">
               <img src="/richtext/mmbase/images/1183"
                    alt="MMBeest"
                    class="image-right"
                    height="100" width="54"/>
            </a>
            Richtext is text which contains (links to) other objects.
         </p>
         <p>Richtext should not be confused with the html-area, used in the editwizard.</p>
         <table class="plain">
            <tr><td></td><td>TEXT</td><td>HTML</td><td>XML</td></tr>
            <tr><td>Link to another object</td><td>tags</td><td>hyperlink</td><td>real relation</td></tr>
            <tr><td>Templating</td><td>JSP</td><td>JSP</td><td>XSLT</td></tr>
         </table>
         <p>
            <div id="" class="float note left">
               <div class="mmxf"><p>You should use Tomcat 5.5 and JDK 1.5</p></div>
            </div>
         </p>
      </div>
   </div>
   <div class="outtro">
      <p><a href=".?cat=347" class="navigate">&lt; back</a></p>
   </div>
</div>

This is part of the MMBase documentation.

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