It's hard to explain the issue addressed in this blog entry without setting it up. So, bear with me, and follow the steps below, and before you know it we'll all be on the same page.
- Create module suite project: "JugglingCalculator". (I dunno. Call it whatever you like. That's just the name that came up on the spur of the moment. Go ahead and be boring. Call it "MyApplication", if that's what turns you on.)
- Right-click the module suite, choose Properties. Choose "Application" category. Select "Create Standalone Application". Click "Exclude". Click OK. You've now excluded all the IDE's modules, which includes all the help sets that accompany some of them.
- Run the application. Look under the "Help" menu. All you see is... "About". See? No help files. Close the application.
- Back in the IDE, right-click the "Modules" node and choose "Add New..." Call the module "JugglingUI". (Yes, this is going to contain the imaginary user interface of the imaginary application.)
- Use the "JavaHelp help set" wizard in the New File wizard to generate a new help set. Don't touch or change anything yet. Run the application again.
Now look under the "Help" menu again. Choose "Help Contents". Now you see this:
Oh no! Do you see what I see? (Answers on the back of a postcard to the usual address.) Did we create that topic up there, the one that goes: "This window contains the blablabla"? No! We didn't. We're control freaks and we even want to control that innocent, innocuous, harmless looking topic. Let's go ahead and do that then.
- In "JugglingUI", find the layer.xml file. In the same folder as where the layer.xml file is, add a file called master.xml, with this content:
<!DOCTYPE helpctx PUBLIC
"-//NetBeans//DTD Help Context 1.0//EN"
<helpctx id="org.yourorghere.jugglingui.about" showmaster="true"/>
Note that the "id" attribute above above could be ANY help id registered in the jugglingui-map.xml file (or any other help id provided by any other module). In this case, I just put in the id that was generated for me by the wizard, which will show the default topic that was generated for me by the wizard.
- Now we need to make sure that the master.xml file that we have in our module will actually be used. Only if this master.xml file, and not the one that is used by default, is used, will the correct topic be shown. So, first we need to hide the default master.xml file. Then we need to show our own instead. Add this to the layer.xml:
<file name="org-yourorghere-jugglingui-master.xml" url="master.xml">
<attr name="SystemFileSystem.localizingBundle" stringvalue="org.yourorghere.jugglingui.Bundle"/>
<attr name="org-yourorghere-jugglingui-master.xml/Separator1.instance" boolvalue="true"/>
- Build everything, run it, go to the Help menu. You will see a menu item with a weird name. Don't worry about that yet. Choose the menu item. Now you will see your new default help topic:
Finally, you can localize the menu item name in the <this layer> or the <this layer in context> node within the Important Files node. Expand either of those nodes, expand the Menu Bar node, expand the Help node, right-click the weirdly named node, choose Localize Name, and type "Help Contents" (or whatever you want to appear as the label of the menu item). This will change your Bundle.properties file.
Hurray, you've now branded the help set's default topic.