RCP dynamic help

Document directory

• Content producer
• Dynamic Content
• Template
• Transforming Dita on-the-fly
• Widgets

Creating Dynamic documentation plugins for the eclipse help system using Java

 

Did you know that your eclipse documentation plugins can contain Java for creating dynamic content? If you 've ever felt limited by the eclipse help system, this post will show you the basics of creating a dynamic plugin by taking advantage of the org. Eclipse. Help. contentproducer extension point.

Skill Level

I wocould call this an intermediate topic. attached is a sample project that provides a simple framework for getting started with your own plugin. if you have a very basic level of Java experience or other coding experience, you should be able to follow along. I am definitely not an expert in Java either.

I know from experience that figuring out how to extend the eclipse help system is difficult and supporting information is sparse. my goal is to give you a head start. I hope that someone out there, who is a better programmer than I, can use this information and contribute something really cool back to the community.

Getting started

I am using eclipse 3.5 IDE for Java EE developers (Galileo), but you can use previous versions that contain the plugin Development Environment (PVDF). screenshots and process might differ for other versions.

1. Install eclipse by extracting the downloaded ZIP file and launching the eclipse executable.
2. Download the sample Eclipse project for a dynamic documentation plugin.
3. Import the ZIP file as an archived project:File->Import->Existing projects into Workspace(Screenshot). ChooseSelect archive fileOption and browse to the downloaded sample project ZIP file. ClickFinishAnd you shoshould see com.mrscripter.dynamicsample.doc listed in your project explorer view.

This sample provides a very basic example of producing dynamic content using Java and eclipse extension points.

Run the sample project

Compiling and creating the output plugin eclipse seems a bit odd and not obvious. you can think of your sample project as a source file project that is contained within your eclipse workspace. the compiled version of the plugin will go into your eclipse/Plugins directory so that we can test it in the help system.

1. Right-click the project folder in the project explorer view and selectExport.
2. SelectPlug-in development-> deployable plug-ins and fragments(Screenshot ).
3. Browse to your the directory you extracted your eclipse download. You shocould select the folder that contains your eclipse.exe file. The export wizard creates the output JAR file in the Plugins subfolder, for example:My_dir/Eclipse/plugins/com.mrscripter.dynamicsample.doc _ 1.0.0.jar.
4. Restart eclipse to register this new plugin with the help system.
5. After eclipse restarts, clickHelp->Help ContentsTo display the help system.

You shoshould see a top-level navigation entry named "Dynamic documentation sample. "each table of contents entry in this section links to the same resource but passes in a different querystring parameter that the sample uses in the title and body.

The links might look confusing at first. i'll walk through each of the different aspects of the plugin to explain how the plugin works. if you're adventurous and have a good understanding of Java, you can probably stop here and just must e the source code.

If you modify the plugin code, you'll have to re-export and restart eclipse each time. You can run eclipse in infocenter mode to do this more quickly and easily.

Dissecting the plugin

The plugin. xml file contains the instructions that instruct eclipse how to process the files contained within a directory or jar file that is in the Plugins directory. These instructions take the form of extension points.

The Org. eclipse. help. contentproducer extension point in the plugin. XML is the key to creating dynamic output. you add this extension point to your plugin. XML and register a content producer by specifying the name of the Java class that you want to control the dynamic processing:

<extension   id="com.mrscripter.dynamicsample.doc"   name="Dynamic documentation sample plugin"   point="org.eclipse.help.contentProducer">     <contentProducer producer="HelloDynamicWorld"/> </extension>

Content producer

In my sample, I point the content producer to my hellodynamicworld. java. This class must contain the required getinputstream method, which allows the plugin to send its content to the browser:

public InputStream getInputStream(String pluginID, String href, Locale locale)

You return an inputstream from your own Java code back to eclipse for display. An inputstream is a byte representation of your text.

Dynamic Content

Your typical helloworld application is not dynamic so I added a little more code to demonstrate changing the output based on some simple input. this sample looks for a query string parameter named "title" and gets the value of the parameter and then inserts that value into a template. the result is returned as an inputstream for display.

The URL that is called is http ://..... /Help/topic/com.mrscripter.dynamicsample.doc/Something.html? Title = testing + A + title. The content producer class intercepts all URL requests for the plugin. You can changeSomething.htmlTo just about anything and it will still work as long as you provide the title in the querystring.

One issue, I have not solved yet is that if you specify an extension other. HTML, Some browsers won't display the result as HTML but rather as plain text. I still need to figure out how to specify the content type in the response.

Template

I figured most people wanting to create some kind of output wocould likely need to do something with a template so I have ded an extremely basic example of variable replacement. the createmydynamicoutput method gets the title from the querystring and then replaces the % title % from the template/template.html file with the value of the query string title parameter.

What kind of useful things can be done with this?

I see these Java capabilities in most cases as a method of providing services in the help system. by services, I mean things like feeds, utilities, accessing external information, and lastly Simple Dynamic HTML output. I think the following areas wowould provide the best return:

Transforming Dita on-the-fly

The most obvious wocould be to dynamically transform Dita on-the-fly and make use of the metadata to create custom documentation. you cocould create XML output for dynamic TOC files for use in the Navigation Pane. if you created a front-end application using Ajax, you cocould allow for help system customization by tracking preferences. A user cocould mark that they have product A on Windows and you cocould use that information to exclude information about product B or Linux.

Widgets

You cocould connect to and receive Twitter feeds by integrating the tweet4j library and display the results as a widget in your help system homepage or in each page of your help system. I think a lot of mashup options are possible when you consider Web services that might be available to you. you cocould integrate other social media tools into your documentation such as integrating with your forums or otherwise create a method for commenting on your topics.

You 've long been able to include Javascript in your help topics, but javascript can only do so much. you run into cross-domain limitations when trying to use ajax to different servers for security reasons. java can allow you to proxy and cleanse the remote data before displaying it. this cocould allow you to display RSS feed widgets in your help system. if you controlled that remote RSS feed, that might provide you a mechanic for including real time, relevant information in your help system that you might not be able to otherwise include without your product team releasing a new version of your product.

What next?

Get coding! I'm working on some projects myself to make use of what I 've learned while putting this together. i'll post those projects in the future. if this post or sample are useful to you, please leave a comment. if you develop a project of your own, I 'd love to hear about it.

 

Http://mrscripter.com/2009/12/creating-dynamic-documentation-plugins-for-the-eclipse-help-system-using-java/eclipse-help-system

 

Http://help.eclipse.org/help32/index.jsp? Topic =/org.eclipse.platform.doc. isV/reference/extension-points/org_eclipse_help_contentproducer.html