NetBeans Platform: Branding the help with layer kung-fu

Since I said that I have to make a proper application and I was too lazy to actually write any complicated code in the weekend I said: ok, let's add the Help. If you're new to NetBeans Platform, this means basically that there is a Wizard to generate a whole bunch of files and configuration: the Java Help-related files and the files to have the integration with the Help system of the Platform.

Since NetBeans 5.5 this Help Wizard has been a real life saver. The was too much wodoo going on there to actually get it done by hand. It was doable just no something you do when you want to feel relaxed.

The deal about the Help System it's that, of course, is designed to take into account the situation where you have multiple modules with their own helpset. But when you develop a standalone platform application you only have one helpset and you get this ugly picture first:
As you see there is an annoying first page.

The nice thing about the NetBeans Platform and IDE is that the sources are available so you can always grep the hell out of them and find what you need. For example, it seems that this page is in core/javahelp (unsurprisingly) and that it's named masterHelpPage, referenced from the masterHelpMap.jhm with MASTER_ID . MASTER_ID pops up in master-help.xml (based on helpcontext-1_0.dtd) which has an option showmaster = true / false. So this must be the guilty thing.

Ok, there it is, but how does one change it ?

Indeed, found the (possible) culprit. So I have to change the showmaster somehow. Since I've always felt that Java Help is unnecessary complex, I first assume I have to patch the build system and modify the damn file. Nasty but doable.

But this looks like some sort of per-application customization, known as branding on the NetBeans Platform. Branding is the same process that lets you change the application splash screen, icon, title, Bundles for localization and more.

And branding usually involves work with the Bundles, the layer.xml file and new resources (icons, etc).

Since I can't possibly imagine how one could brand, I find on the net Geertjan's blog topic on the subject. The solution is unbelivebly short:

<folder name="Menu">
<folder name="Help">
 <file name="master-help.xml_hidden"/>
 <file name="your-master.xml" url="master.xml">
</folder>
</folder>

Read Geertjan's post for more details.

Layer kung-fu

The ideea is simple: all layers on the Platform are placed on a stack with your module's layer on top. So basically you can't only add or hide (with _hidden) new files, but you can also replace them.

Of course ! This is how branding gets done.

So in the XML above you see the existing master-help.xml file is hidden and then replaced by our own (where we set our own MASTER_ID). It's so simple I can't believe it.

I always though the layer ideea was a little over-engineered but now I'm a believer.

Layers: I know kung-fu!
Developer: Show me !

If this was helpful for you then maybe you'll like reading the other NetBeans Platform-related posts.

--
Emilian Bold
Java-loving consulting services from Timisoara, Romania.