Help

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!

14 comments:
 
23. Apr 2008, 09:52 CET | Link

Very cool Max!

 
23. Apr 2008, 15:09 CET | Link
Adrian Mitev

Very good feature and very good article! I hope it become a part of the jboss ide soon.

Congratulations to the JBoss Tools team!

 
23. Apr 2008, 16:33 CET | Link
Remo

This tiny plugin should defenatly be part of JBoss Tools, or better, be a standalone component that also can be used with installed VPE only ;-) Thanks Max, Remo

 
23. Apr 2008, 17:24 CET | Link

Very cool!

Btw the <literal> tag doesn't have a visual representation in the preview.

24. Apr 2008, 06:39 CET | Link
Ronald van Kuijk | ronald(AT)jbpm.org

Cool indeed.... Would this also be the way to create a visual editor for e.g. xforms without having e.g. a real xforms-jsf taglib ?

24. Apr 2008, 07:16 CET | Link
Joshua Wulf | jwulf(AT)redhat.com

I copied the plugin directory into jbdevstudio/eclipse/plugins

However, I can't find an Open With menu item in the JBDS IDE... what to do?

 
24. Apr 2008, 13:31 CET | Link

Pete: contribute a patch ;) something like:

<vpe:tag name="literal" case-sensitive="yes">
  <vpe:template children="no" modify="yes">
   <code>
    <vpe:value expr="{tagtext()}" />
   </code>
  </vpe:template>
 </vpe:tag>
</code>

Ronald: Yes - I guess so. If the xml follows the normal layout flow it should be doable. You might bump into some of the same bumps as we have.....so let us know ;)

Jwulfi: Right click on the .xml file and the context menu should have a Open With... option.

 

--max

 
09. May 2008, 11:36 CET | Link

Max, that is so useful...

 
29. May 2008, 04:43 CET | Link

Nice post Max !!! Can you plz explain if CSS files can be used for formatting the xml files and also edit the xml files in the Stylesheet mode?

 
27. Jul 2008, 17:22 CET | Link
Nils Cordes | nils.cordes(AT)yahoo.de
Great Jop! I really like this idea.
It would be great to have a DocBook Palette for DocBook tags in the JBoss Tools Palette.
Is anyone out there who knows how to enable an association for other filetypes than jsp and xhtml to the JBoss Tools Palette for example xml?
Best regards
Nils
 
29. Sep 2008, 15:09 CET | Link
singh

I was not able to download the following file. https://jira.jboss.org/jira/secure/attachment/12319745/org.jboss.tools.vpe.docbook.zip

 
25. Mar 2009, 20:30 CET | Link
Stefan Baramov | stefan.baramov(AT)infor.com

In case you are wondering how to actually install JBoos Tools, here is a quick step-by-step:

  • Install JBoss Tools RichFaces from http://download.jboss.org/jbosstools/updates/stable/
  • Download the zip of the plug-in from https://jira.jboss.org/jira/browse/JBIDE-1304
  • Copy the file to the eclipse/dropins
  • Restart eclipse
 
30. Mar 2010, 22:19 CET | Link

Is it possible to do something like this, but with xslt instead of vpe? I expect there is a java library to allow for that, but don't know my way around the language well enough to know what it is...

 
20. Jul 2014, 07:58 CET | Link

Coco Chanel once said, The best things existence are free and no cost best are costly! On that latter half of her statement she just isn't any doubt debating her exquisite replica chanel handbags. It is a given fact her handbags are prohibitively expensive for that average person. That is why there have been numerous cottage industries of online outlets selling Chanel handbags. Or are you? That cheap prada handbags is a very important issue. To save you any further headaches, if in order to an authentic Chanel handbag you be obliged to buy one at her Chanel Boutique either in Paris, New York, West Palm Beach, Beverly Hills, or elsewhere in turmoil.

Coach purses have a truly unique longchamp outlet finish and good quality can be easily recognized. You will be able to notice the difference between your original as well as the chanel replica coach purse.

Is it the very? - Many people will only run in the sneaker Air Max 90, but pertaining to which is better is a legitimate personal preference. Stands out because it is chanel replica handbags very comfortable and of course is valuable for wearers. It also fits well and light. All these are important factors that runners need and shoes missing. So what is the best running shoe available? We are say fantastic feature in ideas 10.