In Relation To

Back to home

How to create a visual DocBook editor in 10 minutes

Posted by    |      

Ever wanted to see how DocBook documents look like rendered without leaving your IDE ? This blog will explain how you can come from this:

to this:

Yes, that is a two-way visual editor for a DocBook document.

Warning: Before you go on please note that this is a work in progress and the API and file format used in this blog might change in future releases until we get it stabilized.

The easy way

Go to JBIDE-1304 and download the attachment which is a plugin you can unzip into your Eclipse plugins directory with JBoss Tools or JBDS pre-installed.

Run Eclipse with JBoss Tools installed and open your DocBook .xml file with the editor by using Open with > Other > JBoss Tools HTML Editor.

The harder way

The following describes the parts in play and how to write the plugin. First we need to understand how the Visual Page Editor works.

Mechanics of the Visual Page Editor

The Visual Page Editor (VPE) in JBoss Tools is actually more than just an editor for html-like languages like (X)HTML, JSP and JSF/Facelets, it is a general editor that can be adapted to edit (almost) any kind of XML based document in a visual editor. As long as you can define a set of transformation rules that gives you a good approximation of the rendering in HTML then using VPE is an option for you.

The VPE consists of two editor panes, a source part which can be any type of XML document and a visual part which is an embedded Mozilla browser which shows an approximation of how the XML source would look like when rendered to HTML.

The transformation works by running the the input tags through a set of templates and output the result which then will be viewed in the visual part.

An example of these templates is: 

<vpe:template tag='section'>
  <h3>@text</h3>
</vpe>

This template says if a 'section' tag is found transform it into a 'h3' tag with the text of the section as the title.

Create a DocBook VPE extension

You either create a fresh new plugin or add the following to your existing plugin.

The plugin need to implement one extension point: org.jboss.tools.vpe.templates. You can use the plugin wizard if you want or you can add the following to your plugin.xml file: 

 <extension
         point="org.jboss.tools.vpe.templates">
      <templates
            name="DocBook"
            path="templates/docbook.xml"></templates>
   </extension>

This tells VPE to read templates/docbook.vpe and use it for its transformation.

The template file contains the transformation rules and a basic implementation for DocBook would be: 

<?xml version="1.0" encoding="UTF-8"?>
<vpe:templates>
 <vpe:tag name="chapter" case-sensitive="yes">
  <vpe:template children="yes" modify="yes">
   <div/>
  </vpe:template>
 </vpe:tag>

 <vpe:tag name="title" case-sensitive="yes">
  <vpe:template children="no" modify="yes">
   <h1>
    <vpe:value expr="{tagtext()}" />
   </h1>
  </vpe:template>
 </vpe:tag>
	
 <vpe:tag name="para" case-sensitive="yes">
  <vpe:template children="yes" modify="yes">
   <p/>
  </vpe:template>
 </vpe:tag>
	
 <vpe:tag name="section" case-sensitive="yes">
  <vpe:template children="yes" modify="yes">
    <div />
   </vpe:template>
  </vpe:tag>

 <vpe:tag name="imagedata" case-sensitive="yes">
  <vpe:template children="yes" modify="yes">
   <img src="{src(@fileref)}" />
  </vpe:template>
 </vpe:tag>
</vpe:templates>

A more complete version can be found in JBIDE-1304.

Notice how the transformations are just simple mappings from DocBook tags to HTML tags and how we use normal xpath expressions to refer to attributes like fileref.

Some tags might require more than just basic transformation, but that must wait for another blog :)

But otherwise that it is it! It is that simple.

Run Eclipse with the plugin

You should now be able to run your Eclipse directly from PDE or standalone with the plugin installed and open any DocBook .xml file with the editor by using Open with > Other > JBoss Tools HTML Editor

Future

The current version is just a prototype and still has some quirks but it functional for most editing of DocBook files.

We plan on putting this into JBoss Tools when we fix some of quirks described at JBIDE-1304.

Let us know what you think about this feature and consider contributing any enhancements you do back to us. If you want to see more example of possible transformations go look for .vpe files in JBoss Tools or JBDS distribution.

Thanks

This is a write up of the 10 minutes short talk I did at EclipseCon 2008 called How to extend the Visual Page Editor in JBoss tools inspired from what Max Katz, Alexey Kazakov and Sergey Vasilyev taught me about the extensions point in VPE.

The DocBook implementation was done by Denis Golovin.

Thanks Guys!

Back to top