Saturday Dec 06, 2008

Overriding a CSS Reference from a Different NetBeans Module

Let's say your application incorporates a module's helpset that has CSS references in each of its help topics such as this:

<link rel="stylesheet" href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/modules/usersguide/ide.css" type="text/css">

I believe, but could be wrong, that the above is not very good. Why? Because the CSS reference is to a DIFFERENT module, so that the module that includes the reference above is not self-contained. Instead of that, it depends on another module. What if you want to include the module that includes the reference above, but not the module where the referenced CSS stylesheet is found?

Practical example: you want to include the NetBeans "db" module (because your application includes database functionality). Therefore, you also want to include the "db" helpset. However, the "db" helpset has CSS references exactly as above (in fact, I copied the above from a "db" help topic). However, you're not interested in the "usersguide" module, which is where the referenced CSS stylesheet is found. You have, in fact, excluded that module. So all the references point nowhere.

While you wait for the NetBeans Docs team to make the "db" module self-contained (i.e., they [we] should copy the ide.css into the "db" module and then reference that CSS, which breaks the "single source" concept but at least makes the module self-contained, which is more important than "single source"), you can do the following:

  1. Make sure that your application includes the "usersguide" module, even though your application doesn't need its help topics. Check in the application's that "usersguide" has not been excluded!

  2. Hide the "usersguide" help topics (even though you're including the module itself), using the application branding module's Services/JavaHelp folder.

  3. Override the "usersguide" module, in the application's "branding" folder, pasting in your own CSS stylesheet in the place where the original CSS stylesheet used to be.

That's all. Now, when you run the application, your own stylesheet will be used, overriding the one referenced by the help topics in the module (in this case, the "db" module). Big donwside: you're including a module with many help topics, even though you're only interested in overriding one single file: the CSS stylesheet. You're hiding all the help topics in the module... so the module is a complete waste to you and to your users. The upside, though, is that the user won't notice that at all (a few more bits to download/startup doesn't make all that much difference) and, instead, will experience the helpset as one single document, because all of the topics will be styled in exactly the same way, which is especially valuable if the help topics are styled in a very special way, e.g. using a standard color for all headings, etc.


Geertjan Wielenga (@geertjanw) is a Principal Product Manager in the Oracle Developer Tools group living & working in Amsterdam. He is a Java technology enthusiast, evangelist, trainer, speaker, and writer. He blogs here daily.

The focus of this blog is mostly on NetBeans (a development tool primarily for Java programmers), with an occasional reference to NetBeans, and sometimes diverging to topics relating to NetBeans. And then there are days when NetBeans is mentioned, just for a change.


« December 2008 »