![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Developers have long realized that building modular systems makes it easy to upgrade one part of the system without affecting the other parts. Modularity also makes it easy to extend the original system in new and novel ways. This is the motivation for building Eclipse as a set of plug-ins, allowing other developers to replace and enhance the modules that are already there.
Help in Eclipse, like the rest of the environment, is built with a plug-in architecture. This article discusses taking advantage of this helpful architecture to externalize the help contents. It assumes a working knowledge of the Java™ programming language, Eclipse, and Web topics. It does not assume that you already know anything about how help is organized in Eclipse or how plug-ins work. The goal of the article is to show you how and why you can host the help for the Eclipse environment on a centralized server (either on an intranet or the Internet) and access it from within the environment.
Help in Eclipse is not a monolithic entity. It is a series of plug-ins that merge together to provide the impression of unity. But even this doesn't really answer the question: "Why would I want to centralize help in Eclipse? If I download the Java version of Eclipse, I'm doing Java development, and I have all the help I need locally." This is true for your entire development team as well. Each of you can have your own local copy of help, which works fine until the day the extra plug-ins come to town.
On a realistic project, the day will come when you realize you -- and the other members of your development team -- need the services of a plug-in or two (or, because they are plentiful and cheap, a couple of dozen). For any nontrivial team development, you want to make sure that everyone's environment is the same, from the build process to the third-party JAR files you are using. This is simply a project best practice: making sure everyone on the team is building the same thing. In fact, a large number of third-party tools have spawned just to handle this practice: Ant, the Java Make tool; CruiseControl, for enabling continuous integration; and a host of others. Experienced Java developers realize that it is a good thing to make sure that the development environment and process is reproducible across the entire team. Why should help be any different?
When you install plug-ins in Eclipse, the more sophisticated ones also install their own help, and, because of the way help is organized, it seems to merge right into the existing help infrastructure. Here is where having an externally accessible help repository pays off. Just like the other parts of the development process you want to keep consistent, wouldn't you want the same for your help? Help encompasses the existing Eclipse help, but also the help merged in via additional plug-ins.
To make the best use of the help system, you should add your own content to it, with project- and team-specific notes added to the standard help entries. You can download a plug-in that makes your job easier, but you need to make sure that everyone on the team uses it in the same way and has access to the same notes about it. If you put all that information in one place, you cut down on the potential for information falling out of sync. This, too, is a best practice, codified in The Pragmatic Programmer, by Dave Thomas and Andy Hunt (see Resources). They explain the Don't Repeat Yourself (DRY) principle: If you have the same information in more than one place, it will get out of sync, and you no longer can trust any particular instance of it. If you "don't repeat yourself," you know that the single copy is the canonical copy. This applies to help, as well.
Before you can start externalizing the help in Eclipse, you must understand how help is organized by the environment. To that end, you are going to take a little side trip into the help organization in Eclipse.
The easiest way to see the internal structure of help is to build a plug-in with a help extension point. Eclipse ships with the Plug-in Development Environment (PDE), so building a new plug-in is easy. First, create a new plug-in project in one of several ways: choose File > New Project File > New Plug-in Project..., or use the gallery approach with the Control-N combination. If you chose either of the two generic project creation options, you are greeted with the New Project dialog shown in Figure 1.
Figure 1. Creating a new plug-in project from the generic project gallery
The next step in the wizard allows you to specify the details for your project, such as name and directory structure. This dialog appears in Figure 2.
Figure 2. Specifying physical attributes of the project
In this case, you are only creating a help plug-in extension point. However, PDE comes with a variety of pre-built extension points, including the one for a help extension. To see the list of extension points, choose to "Create a Java Project" in Figure 2's Project Settings, otherwise the sample extension points won't appear in a subsequent wizard dialog. In this case, you will eventually create Java code, so the option is selected. If you want to create just a help extension and you want to use the pre-defined extension points, leave this option checked.
The next wizard page allows you to specify meta-information about your plug-in; it appears in Figure 3.
Figure 3. Meta-information page about your plug-in
To make building plug-ins easier, the PDE comes with a variety of templates, including pre-defined types of plug-ins. You're going to take advantage of these templates to create the infrastructure around the help plug-in. Figure 4 shows the wizard page that allows the choice of template.
Figure 4. Plug-in templates
The custom plug-in wizard provides a variety of extension points, one of which is your help extension, which appears in Figure 5.
Figure 5. The help extension plug-in template
Last, you choose what type of content our help plug-in will provide, which appears on the last wizard page and in Figure 6.
Figure 6. Selecting table of contents categories
The end result of this trip through the PDE wizard is a collection of files, including XML, Java source, and build infrastructure.
The last page of the PDE wizard (shown in Figure 6) creates a TOC.XML file, the table of contents (TOC) for the help files you are including with the plug-in. This TOC format is used for Eclipse's internal help and for plug-ins; it is consistent throughout. The TOC file generated by default looks like Listing 1.
Listing 1. The TOC file generated by default
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Repository Table of Contents" topic="html/toc.html">
<topic label="Getting Started">
<anchor id="gettingstarted"/>
</topic>
<topic label="Concepts">
<anchor id="concepts"/>
</topic>
<topic label="Tasks">
<anchor id="tasks"/>
</topic>
</toc>
|
Notice that the title created in Figure 6 appears at the top of the <toc> tag, and this points to the topic of html/toc.html. This TOC entry is the top level of the help directory structure for this set of help. In other words, the physical help HTML files will appear in the directory structure specified here, from a root directory down. Generally, for space considerations, these HTML files appear in a zip file (traditionally called doc.zip). If you search through your Eclipse plug-ins directories, you will see a number of doc.zip files, each containing help that is merged into the main help in Eclipse whenever help is invoked.
The other entries in the TOC file point to other TOCs generated at the same time as the primary TOC. You have "gettingstarted," "concepts," and "tasks." Each of these secondary TOC entries has a corresponding table of contents XML file in the project. Also within the project, the PDE has created the proper directory structure for the content HTML files, as made evident by the snippet borrowed from the package explorer in Figure 7.
Figure 7. The PDE builds XML configuration files and directory structures.
Because of this structure, you can create as many help files as you like, with the appropriate structure, and put them in zip files to be merged together as one seamless whole by the help system browser in Eclipse.
Building an external repository
Now that you know how help files are structured in Eclipse, you will examine how to externalize this to an independent server. Eclipse facilitates this by providing a tool called the Infocenter with the Eclipse installation. As you have probably guessed, the help system in Eclipse is actually driven by an embedded Web server/servlet engine. In fact, it uses a stripped-down version of Apache Tomcat as the help application server. One of the plug-ins that comes with Eclipse is org.eclipse.help.appserver_3.0.0, which encapsulates the Web server. The Infocenter externalizes the application server so you can manipulate it outside the Eclipse environment.
To set up the Infocenter on an external server, install the Eclipse Runtime Binary (which you can download from Eclipse as a zip file. Extract this into a directory structure on your server (note that this is exactly the same as installing Eclipse, which is what you are doing on the server). All the features of internal help are supported by the Infocenter, except infopops (the context-sensitive tool tip pop-ups) and Active Help (which performs commands for you from a help view, like creating a new file). These advanced help features would be impossible to implement from an external server. The Infocenter is included with the Runtime Binary as a set of Java classes, invoked from the command line.
To start the Infocenter on your server, you issue a command like this, where [ehome] is the installation directory for your Eclipse install (broken up onto multiple lines for readability; this should be a single command line, as shown in Listing 2).
Listing 2. Starting the Infocenter on your server
java -classpath [ehome]\plugins\org.eclipse.help.base_3.0.1\helpbase.jar org.eclipse.help.standalone.Infocenter -eclipsehome [ehome] -port 8081 -command start |
This command sets the classpath to point to the Infocenter JAR file, tells it where Eclipse is installed, sets the port number, and issues the start command. To stop the server, you issue the same command with shutdown instead of start. Once you have started the Infocenter, you can now use a browser and issue a URL like http://localhost:8081/help/index.jsp.
You will see the standard Eclipse help in your browser, as shown in Figure 8.
Figure 8. Eclipse help running externally
The Infocenter is a stand-alone server, so it doesn't require an additional Web server. However, in a realistic environment, you want to control important issues like access control, visibility, and other aspects best handled by a normal Web server. You can easily set up your Web server to forward commands to the Infocenter based on a certain URL pattern.
For example, you can set up a proxy module in Apache to redirect requests in the form of http://bigsprawlingcompany.com/eclipsehelprepo to an Infocenter URL that looks like http://internalhelpserver:8081/help using the following changes to Apache's conf/httpd.conf file:
LoadModule proxy_module modules/ApacheModuleProxy.dll ProxyPass /eclipsehelprepo http://internalhelpserver:8081/help ProxyPassReverse /eclipsehelprepo http://internalhelpserver:8081/help |
Now that you can externalize your help, you need a way from within Eclipse to access it. There are several ways to go about this. In this article, you're going to create a new top-level menu item that leads to the new remote repository. You could replace the existing help behavior by rewiring the existing menu items, but that isn't advisable. It is generally a bad idea to break something that already exists, especially in this case. You don't want to remove the ability for the developer to get to local help if for some reason your help server is down. It is best to use a variation of part of the Hippocratic Oath when developing plug-ins: first, do no harm.
The easiest way to create a new menu item is to let the PDE wizard build the infrastructure for you. To create this help repository menu item, the same sequence was followed as before with a change to one of the wizard pages. For the template selection page, which appeared in Figure 5, a new Sample Action was added, as shown in Figure 9.
Figure 9. Adding a sample action to our help repository
This creates the infrastructure for a new menu item. Because you're creating a new action, you also get a new wizard page that allows you to specify the name of the action. This page is shown in Figure 10.
Figure 10. The Sample Action class wizard page
This page allows you to name -- and will subsequently create -- an Action class. This Action class contains the boilerplate code for adding a new action in Eclipse, in this case bound to a menu item. The only code you need to add is the code to invoke the help viewer, which can be the standard Eclipse help viewer or a browser. In this case, you're going to invoke the user's default browser. Using a full-fledged browser provides all the same benefits as using the help viewer, but also allows the user to create bookmarks to the help repository code alongside bookmarks found on the Web that might also pertain to development. The code in the run() method is one line:
public void run(IAction action) {
Program.launch("http://localhost:8081/help");
|
Of course, you would put the URL to your help repository here. With a bit more effort, you could add a setting in the Preferences dialog that allows you to specify the address, so you wouldn't have to hard-code it into the plug-in. However, that topic is best left to an article on building plug-ins that modify the Preferences dialog.
Once you have created the menu plug-in, you can attach to your externalized Infocenter help from the main Eclipse menu bar. Figure 11 shows this new menu.
Figure 11. The new Help Repository menu item in Eclipse
When you click on this menu item, it launches the Infocenter help in whatever external browser you have configured on your computer. The end result appears in Figure 12.
Figure 12. The externalized help browser launched from the Eclipse menu plug-in
Voila! You now have an external help repository where you can start consolidating the help system for your entire application development team. Once you grow accustomed to having this resource at your fingertips, you'll wonder how you ever got along without it.
Now that you've tied all the strands discussed in this article together, you have a sum greater than the parts. You can create a highly customized set of help for your developers, with all the appropriate plug-in help and even your own content. Wouldn't it be nice to place the company's coding standards in the help, right alongside the other reference material?
If you create your help outside the development environment, it is also available to developers at home or at a remote client site. The help environment becomes an invaluable reference resource. In fact, externalizing your help allows you to treat it as much more than a static grouping of information that rains down on you from vendors. You can make help a dynamic, integral part of your development environment.
Learn
-
Apache Ant is a Java-based build tool. In theory, it is like Make, but without Make's wrinkles.
-
CruiseControl is a framework for a continuous build process.
-
The Pragmatic Programmer: From Journeyman to Master, by Dave Thomas and Andy Hunt (Addison-Wesley Professional, 1999), explains the DRY principle and dozens of other important concepts.
-
For an in-depth view of the architectural pattern for building an application from constituent parts embodied by Eclipse plug-ins, see Notes on the Eclipse plug-in architecture.
-
For an IBM developerWorks article on creating, debugging, and installing Eclipse plug-ins, see "Developing Eclipse plug-ins."
-
See the WebSphere Application Developer Infocenter resource.
-
Check out the "Recommended Eclipse reading list."
-
Browse all the Eclipse content on developerWorks.
-
Users new to Eclipse should look at the Eclipse start here.
-
Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
-
To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
-
For an introduction to the Eclipse platform, see "Getting started with the Eclipse Platform."
-
Stay current with developerWorks' Technical events and webcasts.
-
Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
-
Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
Get products and technologies
-
Check out the latest Eclipse technology downloads at IBM alphaWorks.
-
Innovate your next open source development project with IBM trial software, available for download or on DVD.
Discuss
-
The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
-
The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
-
Participate in developerWorks blogs and get involved in the developerWorks community.
Neal Ford is an application architect at ThoughtWorks, a revolutionary IT professional services company that leverages gifted people from around the world to create more value from software. He is also the designer and developer of applications, instructional materials, magazine articles, courseware, video/DVD presentations, and author of the books Developing with Delphi: Object-Oriented Techniques, JBuilder 3 Unleashed, and Art of Java Web Development. His primary consulting focus is the building of large-scale enterprise applications. He is also an internationally acclaimed speaker, having spoken at numerous developers conferences worldwide. He welcomes feedback and can be reached at: nford@thoughtworks.com.
