Custom Content Parser

Revision as of 14:41, 25 September 2008

Overview

This document will outline the purpose and usage of <cms:parse> tag, which allows the generated content for any part of your template to be parsed with custom parser class in order to manipulate generated content as desired before final page rendering.

Custom Parser and Visitor Class

In order to implement your custom parser you will need to implement two classes: custom parser and custom visitor. Custom parser class is the one that will be referenced with <cms:parse> parserClass attribute. The easiest way is to extend org.opencms.jsp.parse.A_CmsConfiguredHtmlParser which case the only method you will need to implement is createVisitorInstance() returning your custom visitor class. This can be done as below:

import org.opencms.jsp.parse.A_CmsConfiguredHtmlParser;
import org.opencms.main.CmsException;
import org.opencms.util.I_CmsHtmlNodeVisitor;
 
public class MyCustomParser extends A_CmsConfiguredHtmlParser {
	public I_CmsHtmlNodeVisitor createVisitorInstance() throws CmsException{
		return new MyCustomVisitor();
	}
}

Now, your custom visitor is the class that you place all your custom parsing magic. The best way to create your custom visitor class is to extend org.opencms.util.CmsHtmlParser and implement org.opencms.util.I_CmsHtmlNodeVisitor. This can be done as below:

import org.htmlparser.Remark;
import org.htmlparser.Tag;
import org.htmlparser.Text;
import org.opencms.util.I_CmsHtmlNodeVisitor;
import org.opencms.util.CmsHtmlParser;
 
public final class CustomParser extends CmsHtmlParser implements I_CmsHtmlNodeVisitor {
 
     public CustomParser() {
 
         super(true);
     }
 
 
     public void visitStringNode(Text text) {
 
         text = doStuffToHtml(text);
         super.visitStringNode(text);
     }
 
     public void visitTag(Tag tag) {
 
         tag = doStuffToTag(tag);
         super.visitTag(tag);
     }
 
     public void visitRemarkNode(Remark remark) {
 
         remark = doStuffToRemark(remark);
         super.visitRemarkNode(remark);
     }
}

Now, you do not have to overwrite all of the above methods, but only the ones which content you would like to manipulate. The types are explained below:

visitStringNode(Text text) - This parses trough all text content line at the time.

visitTag(Tag tag) - This parses through all non text nodes such as IMG, A, SPAN... line at the time.

visitRemarkNode(Remark remark) - This parses through all comment nodes line at the time.

Tag Usage

The tag can be used just by surrounding the part of the template you would like to apply your custom parser for with the following syntax:

<cms:parse parserClass="YourCustomParserClassName">
        ... the part of the template you want to parse...
</cms:parse>

Please note that if your template part between the parse tags includes any cms:include tags you must set the cacheable attribute to false for all your cms:includes in order for the custom parser to work.