X

Geertjan's Blog

  • July 6, 2006

Branding the Default Help Topic for NetBeans Platform Applications

Geertjan Wielenga
Product Manager
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.
  1. 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.)
  2. 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.
  3. Run the application. Look under the "Help" menu. All you see is... "About". See? No help files. Close the application.
  4. 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.)
  5. 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.

  1. 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"
    "http://www.netbeans.org/dtds/helpcontext-1_0.dtd">
    <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.

  2. 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:

    <folder name="Menu">
    <folder name="Help">
    <file name="master-help.xml_hidden"/>
    <file name="org-yourorghere-jugglingui-master.xml" url="master.xml">
    <attr name="SystemFileSystem.localizingBundle" stringvalue="org.yourorghere.jugglingui.Bundle"/>
    </file>
    <attr name="org-yourorghere-jugglingui-master.xml/Separator1.instance" boolvalue="true"/>
    </folder>
    </folder>
  3. 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.

Join the discussion

Comments ( 10 )
  • Stephen Cowx Saturday, July 29, 2006
    Hi Geertan

    I was very interested to read this blog entry because I want to put Help into the app that I am porting over to the netbeans platform. However I was not able to find the helpset wizard that you mentioned above

    Use the "JavaHelp help set" wizard in the New File wizard

    I have looked everywhere for it and I cannot find it. I can find no mention of it on the internet, nor can I find it in the IDE help. I was hoping you could clear this up for me. I am probably being thick and looking in all the wrong places, but I have tried. I am using netbeans 5.0. I would appreciate your assistance if you have time.


    Thanks, Stephen
  • Stephen Cowx Saturday, July 29, 2006
    Hi Geertan

    I was very interested to read this blog entry because I want to put Help into the app that I am porting over to the netbeans platform. However I was not able to find the helpset wizard that you mentioned above

    Use the "JavaHelp help set" wizard in the New File wizard

    I have looked everywhere for it and I cannot find it. I can find no mention of it on the internet, nor can I find it in the IDE help. I was hoping you could clear this up for me. I am probably being thick and looking in all the wrong places, but I have tried. I am using netbeans 5.0. I would appreciate your assistance if you have time.


    Thanks, Stephen
  • Geertjan Sunday, July 30, 2006
    Get "Module Development Update 1" or get NetBeans IDE 5.5 (any build, Beta or Beta 2 or whatever). The JavaHelp help set wizard ins't part of the standard NetBeans IDE 5.0, but was provided in a later module and then integrated into 5.5.
  • Geertjan Sunday, July 30, 2006
    By the way: "Module Development Update 1" is in the update center and is specifcally for NetBeans IDE 5.0.
  • Stephen Cowx Tuesday, August 1, 2006
    Hi Geertan

    Thanks a lot for your response. The update worked and I now have a branded help topic :)

    Regards, Stephen

  • Geertjan Wednesday, August 2, 2006
    Fantastic! I'd be very interested in interviewing you (via e-mail) about your experiences with NetBeans module development (and the NetBeans APIs and so on). Your key learnings, main difficulties, favorite bits, etc would be very good to know about (and the result would be published as an interview on http://platform.netbeans.org, like the other interviews you can find there in the left navigation bar). What do you think? Please feel free to drop me an e-mail at geertjan.wielenga@sun.com
  • Jesse Glick Monday, August 21, 2006
    I would recommend you brand the actual HTML page,
    modules/org-netbeans-modules-javahelp.jar!/org/netbeans/modules/javahelp/resources/masterHelpPage.html
    rather than replacing the master XML file, which gets you into trouble with menu ordering etc.
  • baldman Thursday, December 6, 2007

    Thanks Geertjan , but what about link topComponent elements to a java help page?


  • Geertjan Thursday, December 6, 2007

    baldman, everything you have asked so far about JavaHelp is referred to in the NetBeans Developer FAQ. Just go there and search for 'javahelp':

    http://wiki.netbeans.org/wiki/view/NetBeansDeveloperFAQ


  • guest Monday, November 7, 2011

    Thanks Jesse! Your comment saved me!

    []'s


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha