Adding custom parsers

The visual editor API provides interfaces to add custom parsers. This allows developers to inject their custom handlers and gain control over parsing of the document source code performed when preparing the document for display in the visual editor (at the time of loading the document or switching from the source code to the visual mode).

The visual editor API functions enables you to install parsers of the following three types, with which you can efficiently handle documents before they are passed over to the visual editor:

• Source code parser (Content Parser);
• PHP inclusion parser (PHP Parser);
• DOM visual aspect parser (DOM Handler).

Content Parser

Processes documents at the source code level. To add a content parser:

1. declare the handler function;
2. install handler by calling the addContentParser method of oBXEditorUtils.

Handler declaration

The handler function (which is essentially the parser itself) must be visible within the scope of addContentParser. The only argument that the function accepts is the document source code. The function processes the code and returns an altered version of it. Otherwise, false can be returned which indicates that no changes are made to the input code.

Parser installation

To install your parser, call oBXEditorUtils.addContentParser.

Example

<script> function CustomContentParser(str) { //... some changes here return str; } // Add the parser oBXEditorUtils.addContentParser(CustomContentParser); </script>

PHP Parser

Being installed, this parser allows to process PHP islands in the document source code.

When a document is processed, the system passes code portions to all the installed parsers subsequently, in the form of text string. If a parser returns the code unchanged (the system uses case-sensitive comparison) or returns false, the string is passed to the next registered parser. When installing the parser, you can specify its position in the parser queue. However, the built-in parsers of the visual editor have the highest priority and are called in the first turn. To add a content parser:

1. declare the handler function;
2. install handler by calling the addPHPParser method of oBXEditorUtils.

Handler declaration

The parser must be visible within the scope of addContentParser. The only argument that the function accepts is the source code. The function processes the code and returns an altered version of it. Otherwise, false can be returned which indicates that no changes are made to the input code.

You can use helper methods of oBXEditorUtils.PHPParser to create faster and more efficient parsers.

Parser installation

To install your parser, call oBXEditorUtils.addPHPParser.

Example

<script> function CustomPHPParser(str) { //... handle the document code return str; } //Add handler oBXEditorUtils.addPHPParser(CustomPHPParser); </script>

You must ensure that your content and PHP parsers perform correctly and do no damage to the source code. Otherwise, the visual editor may function improperly.

DOM Handler

Creating a document handler to trap code at the DOM level can simplify creation of the element property inspectors, after the element has already been created and rendered in the visual mode. In your DOM parser, you can use any available DOM functions. 

To add a content parser:

1. declare the handler function;
2. install handler by calling the addDOMHandler method of oBXEditorUtils.

Handler declaration

The parser must be visible within the scope of addDOMHandler. The function accepts the document object on input. The function can inspect and alter the document DOM as required. Return values are ignored.

Parser installation

To install your parser, call oBXEditorUtils.addDOMHandler.

Example

<script> function CustomDOMHandler(oDocument) { //... handle the document } //Install parser oBXEditorUtils.addDOMHandler(CustomDOMHandler); </script>