An example of where this functionality might be useful is in an application suite. The application suite may consist of a collection of constituent applications. As constituent applications are purchased and installed, their help information can be merged with help information from the other applications in the suite.
HelpSets can be merged statically or dynamically.
In the following simple example, HelpSet2 is merged with HelpSet1 to produce the unified TOC display shown below:
-HelpSet1.hs- <?xml version='1.0' encoding='ISO-8859-1' ?> <!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" "http://java.sun.com/products/javahelp/helpset_1_0.dtd"> <helpset version="1.0"> <title>HelpSet 1</title> <maps> <homeID>hs1_file1</homeID> <mapref location="hs1.jhm" /> </maps> <view> <name>TOC</name> <label>Table Of Contents</label> <type>javax.help.TOCView</type> <data>hs1TOC.xml</data> </view> <subhelpset location="HelpSet2.hs" /> </helpset>
-HelpSet2.hs- <?xml version='1.0' encoding='ISO-8859-1' ?> <!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" "http://java.sun.com/products/javahelp/helpset_1_0.dtd"> <helpset version="1.0"> <title>HelpSet 2</title> <maps> <homeID>hs2_file1</homeID> <mapref location="hs2.jhm" /> </maps> <view> <name>TOC</name> <label>Table Of Contents</label> <type>javax.help.TOCView</type> <data>hs2TOC.xml</data> </view> </helpset>
The HelpSet that contains the <subhelpset> tag is considered to be the master HelpSet--all HelpSets are merged with (appended to) the master HelpSet. | |
When HelpSets are merged, only views with the same name (<name> tag) as a view in the master HelpSet file are merged. Note that in the example above, both views are named "TOC". Any views in the sub-HelpSets that do not match the views in the master HelpSet are not displayed. | |
Multiple <subhelpset> tags can be included in a HelpSet file. HelpSets are appended in the order in which they occur in the HelpSet file. If a HelpSet specified in a <subhelpset> tag is not found, it is ignored and no error is issued. | |
The <subhelpset> location attribute takes a URL as its argument. | |
Indexes are merged in the same manner as TOCs--by appending the merged indexes to the master HelpSet. | |
Merged search databases are searched sequentially, however, query results are collated and presented together. |
The following example HelpSet file could serve as an
dataless master for a suite of applications. The JavaHelp
system constructs a help display with whichever of the
application sub-HelpSets (app1.hs -
app2.hs) are found installed on the user's
system:
<?xml version='1.0' encoding='ISO-8859-1' ?> <!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" "http://java.sun.com/products/javahelp/helpset_1_0.dtd"> <helpset version="1.0"> <!-- title --> <title>JavaHelp System User's Guide</title> <!-- views --> <view> <name>TOC</name> <label>Table Of Contents</label> <type>javax.help.TOCView</type> </view> <view> <name>Index</name> <label>Index</label> <type>javax.help.IndexView</type> </view> <view> <name>Search</name> <label>Search</label> <type>javax.help.SearchView</type> </view> <subhelpset location="app1.hs" /> <subhelpset location="app2.hs" /> <subhelpset location="app3.hs" /> <subhelpset location="app4.hs" /> </helpset>
The basic API consists of the add(HelpSet) method, and its corresponding remove(HelpSet) method. These methods fire HelpSetEvent events to the HelpSetListeners that have registered interest in them. The ComponentUIs for the TOC, index, and search views register for these events and react to changes.
The semantics of merging is implemented by individual NavigatorViews and JHelpNavigators. There are three basic methods:
For more information about these classes and methods, refer to the JavaHelp API documentation. API information can be viewed using a web browser (doc/api/overview-summary.html) or by using the demos\bin\apiviewer command.
A demonstration program (demos\bin\merge) is
included with the JavaHelp system release. This program
demonstrates how HelpSets can be merged and removed
dynamically. The sources for that program are available in
demos\src\sunw\demo\merge.