主页 > 社区 > 项目 > platform

向他人学习

Tom Wheeler

项目主页
成员
通告
论坛
邮件列表
文档和文件
版本控制
事件跟踪

NetBeans Help System 插件教程

反馈

本教程主要用来演示如何创建帮助系统以及如何在 NetBeans 文件系统中注册。

拥有描述插件的 HTML 文件之后，您必须将它们包装在插件中，该插件将它们集成在 NetBeans 文件系统中。要完成此操作，您需要创建一个帮助系统。除了 HTML 文件之外，帮助系统还包含以下文件：

映射文件。 指定映射 ID 的列表，每个 ID 都链接到特定的 HTML 文件。
目录文件。 使用映射 ID 将帮助文件安排到目录中。
索引文件。 使用映射 ID 将帮助文件安排到索引中。
Helpset 文件。 通过参考映射文件、目录文件和索引文件定义帮助系统。

在本教程中您将创建这些文件中的每个文件，以及在 NetBeans 文件系统中注册帮助系统的文件。

您可以将帮助系统打包到包含 HTML 文件描述的代码的插件中，您也可以创建一个仅包含帮助系统的单独插件。本教程假设您想让帮助系统包含在单独的插件中。但是，如果您想让它们包含在 HTML 文件描述的插件中，则可以跳过“创建 Plug-in 项目”部分的前三个步骤。

本教程将介绍以下主题：

安装软件
创建 Plug-in 项目
创建 Help System
注册 Help System
构建和安装插件

安装完软件之后，本教程可以在 20 分钟之内完成。

如果您在编写和集成帮助系统时有问题，请参阅模块 Helpset 集成常见问题解答。这些常见问题解答提供本教程中未涉及的很多其他详细信息。有关常规使用 NetBeans 插件的详细信息，请参阅 NetBeans 网站上的 NetBeans Development Project 主页。如果有问题，请使用本页顶部的反馈链接。

安装软件

开始之前，需要在您的计算机上安装以下软件：

NetBeans IDE 5.0（下载）
Java Standard Development Kit (JDK™) version 1.4.2（下载）或 5.0（下载）

安装示例

采用以下步骤来安装示例：

解压缩附加的文件。
在 IDE 中，选择 File > Open Project，然后浏览到包含已解压缩文件的文件夹。打开模块项目。其形式如下：
右键单击项目节点并在 Target Platform 中选择 Install/Reload。将打开目标平台并安装该模块。
选择 Help > Help Contents。在 IDE 帮助左侧的 Contents 窗格的底部，您可以选择新的“About My Plugin”主题：

知道了最终结果后，将从头开始创建模块，并且在创建的同时了解每个部分。

创建 Plug-in 项目

选择 File > New Project (Ctrl-Shift-N)。在 Categories 下，选择 NetBeans Plug-in Modules。在 Projects 下，选择 Module Project 并单击 Next。

在 Name and Location 面板中，在 Project Name 中键入 MyHelpSystem。将 Project Location 更改为您计算机上的任何目录，如 c:\mymodules。选择 Standalone Module 单选按钮和 Set as Main Project 复选框。单击 Next。
在 Basic Module Configuration 面板中，用 myorg 替换 Code Name Base 中的 yourorghere，从而整个代码的 Code Name Base 为 org.myorg.myhelpsystem。向默认的 Module Display Name 中添加空格，将它更改为 My Help System。留出本地化包和 XML 层的位置，以便它们存储在名为 org/myorg/myhelpsystem 的包中。单击 Finish。
IDE 创建 My Help System 项目。该项目包含所有资源和项目元数据，如该项目的 Ant 构建脚本。该项目在 IDE 中打开。您可以在 Projects 窗口 (Ctrl-1) 中查看其逻辑结构，在 Files 窗口 (Ctrl-2) 中查看其文件结构。例如，现在 Projects 窗口应该如下所示：
在 Projects 窗口中，右键单击该项目节点，并选择 New > File/Folder。在 New File 向导中，选择 Categories 下的 Other 和 File Types 下的 Folder。单击 Next。将该文件夹命名为 javahelp/org/myorg/myhelpsystem，然后单击 Finish。
在 Files 窗口中，右键单击 javahelp 节点并创建一个名为 org/myorg/myhelpsystem/myhtmlfiles 的子文件夹。将所有描述插件的 HTML 文件放到 myhtmlfiles 文件夹中。如果您在没有 HTML 文件的情况下使用本教程，请右键单击 myhtmlfiles 节点并选择 New > File/Folder。在 Categories 下选择 Other，在 File Types 下选择 HTML File。单击 Next。将该 HTML 文件命名为 about_myplugin，然后单击 Finish。用以下内容替换默认内容：
```
<html>
    <head>
        <title>About My Plug-in</title>
        <link rel="StyleSheet" href="nbdocs:/org/netbeans/modules/usersguide/ide.css" type="text/css">
    </head>
    <body> 
        <h2>About My Plug-in</h2> 
        <p>This is the greatest plug-in in the world!</p>
    </body>
</html>
```
注意，HTML 文件使用的样式表与标准 NetBeans 帮助系统使用的样式表相同。如果您想将您的帮助系统与标准的 NetBeans 帮助系统集成，建议您使用相同的样式表。
现在 Files 窗口应该显示如下：
在 Projects 窗口中，展开 Important Files 节点，双击 NetBeans Platform Config 将它在 Source Editor 中打开。添加以下属性：
```
jhall.jar=path-to-jhall.jar
javahelp.base=org/myorg/myhelpsystem
```
需要使用这些属性来编译帮助系统。下面对它们进行解释：
jhall.jar—由 JDK 提供的库之一。
javahelp.base—将容纳 helpset .hs 文件的文件夹的完整路径。

有关以上每个文件的基本信息，请参阅 NetBeans 插件模块的快速入门指南。

创建 Help System

在您创建目录、上下文敏感的帮助以及索引之前，您必须创建一个映射文件。该映射文件为组成您的 helpset 的每个 HTML 文件声明一个映射 ID。映射 ID 由是映射 ID 的目标以及指向 HTML 文件位置的 URL 组成：

<mapID target="about_myplugin" url="myhtmlfiles/about_myplugin.html"/>

您在目录文件和索引文件中使用映射 ID。例如，在目录文件中您将使用上面声明的映射 ID 如下：

<tocitem text="About My Plug-in" target="about_myplugin" />

创建映射文件

执行以下操作以创建映射文件：

在 Files 窗口中，右键单击 javahelp/org/myorg/myhelpsystem 节点，并选择 New > File/Folder。在 New File 向导中，选择 Categories 下的 Other 和 File Types 下的 Empty File。单击 Next。将该文件命名为 myplugin-map.jhm，然后单击 Finish。

将以下内容复制并粘贴到空文件中：

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN"
                     "http://java.sun.com/products/javahelp/map_1_0.dtd">

<map version="1.0">

   <mapID target="about_myplugin" url="myhtmlfiles/about_myplugin.html"/>

</map>

注意，您必须为要在帮助系统中显示的每个帮助文件创建一个映射 ID。

按 Ctrl-S 保存文件。

注意，对于上下文敏感的帮助来说，映射 ID 正常情况下是完全限定的类名称。例如，节点或对话框可能具有如下方法：

return new HelpCtx(mydialogbox.class);

在映射文件中，您将指定映射 ID 如下：

<mapID target="org.myorg.mymodule.mydialogbox" url="myhtmlfiles/about_mydialogbox.html"/>

使用映射文件

如上所述，您在两个其他文件中使用映射文件中定义的映射 ID：

目录文件
索引文件

执行以下操作以创建目录文件：

在 Files 窗口中，右键单击 javahelp/org/myorg/myhelpsystem 节点，并选择 New > File/Folder。在 New File 向导中，选择 Categories 下的 XML 和 File Types 下的 XML Document。单击 Next。将该文件命名为 myplugin-toc，单击 Next，然后单击 Finish。
一个空的 XML 文件在 Source Editor 中打开，它的节点显示在 Projects 窗口中。
用以下内容替换默认 <root> 元素：
```
<toc version="2.0">
    <tocitem text="My Plug-in">
       <tocitem text="About My Plug-in" target="about_myplugin" />
    </tocitem>
</toc>
```
注意，您必须为要在帮助系统的目录中显示的每个帮助文件创建一个 <tocitem>。
按 Ctrl-S 保存文件。

执行以下操作以创建索引文件：

在 javahelp/org/myorg/myhelpsystem 包中创建名为 myplugin-idx 的 XML 文档。
用以下内容替换默认 <root> 元素：
```
<index version="2.0">
	
  <indexitem text="My Plugin" target="about_myplugin" />
	
</index>
```
注意，您必须为要在帮助系统中索引的每个项目创建一个 <indexitem>。由于主 helpset 提供字母分隔符，因此不需要附加的插件来包含它们。
按 Ctrl-S 保存文件。

创建 Helpset 文件

在 Files 窗口中，右键单击 javahelp/org/myorg/myhelpsystem 节点，并选择 New > File/Folder。在 New File 向导中，选择 Categories 下的 Other 和 File Types 下的 Empty File。单击 Next。将该文件命名为 myplugin.hs，然后单击 Finish。

将以下内容复制并粘贴到空文件中：

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
                     "http://java.sun.com/products/javahelp/helpset_2_0.dtd"">

<helpset version="2.0">
  
   <title>My Plugin Help</title>
  
   <maps>
     <homeID>myplugin</homeID>
     <mapref location="myplugin-map.jhm"/>
   </maps>
  
   <view mergetype="javax.help.AppendMerge">
     <name>TOC</name>
     <label>Table of Contents</label>
     <type>javax.help.TOCView</type>
     <data>myplugin-toc.xml</data>
   </view>
	
   <view mergetype="javax.help.AppendMerge">
      <name>Index</name>
      <label>Index</label>
      <type>javax.help.IndexView</type>
      <data>myplugin-idx.xml</data>
   </view>
	
   <view>
      <name>Search</name>
      <label>Search</label>
      <type>javax.help.SearchView</type>
      <data engine="com.sun.java.help.search.DefaultSearchEngine">JavaHelpSearch</data>
   </view>

</helpset>

注意到以上代码中已经将您在以前部分中定义的每个文件高亮显示。

按 Ctrl-S 保存文件。
现在 Files 窗口应该显示如下：

注册 Help System

在 NetBeans 文件系统中注册帮助系统涉及以下文件：

Helpset 参考文件（.xml 扩展名）。
层文件（.xml 扩展名）。

helpset 参考文件参考 myplugin.hs 文件并使其可用于 layer.xml 文件。layer.xml 文件在 NetBeans 文件系统中注册帮助系统。

执行以下操作以创建 helpset 参考文件：

在 org/myorg/myhelpsystem 包中创建名为 helpset 的 XML 文档。

用以下内容替换默认 <root> 元素：

<!DOCTYPE helpsetref PUBLIC
          "-//NetBeans//DTD JavaHelp Help Set Reference 1.0//EN"
          "http://www.netbeans.org/dtds/helpsetref-1_0.dtd">
<helpsetref url="nbdocs:/org/myorg/myhelpsystem/myplugin.hs"/>

按 Ctrl-S 保存文件。

如上所示，您在 layer.xml 文件中使用 Services/JavaHelp 文件夹结构以注册 helpset 参考文件以及指定顺序属性。该顺序属性指定在现有帮助系统中放置该帮助系统的位置。例如，下例中的 helpset 文件放置在 org-netbeans-modules-usersguide-below-regular.txt 之后。

执行以下操作以在 layer.xml 文件中注册 helpset 参考文件：

在 Projects 窗口中，展开 Source Packages 节点，展开 org.myorg.myhelpsystem 节点，双击 layer.xml 文件将它在 Source Editor 中打开。在 layer.xml 文件中的 <filesystem> 标记之间添加以下条目：

<folder name="Services">
    <folder name="JavaHelp">
      <file name="org-myorg-myhelpsystem-helpset.xml" url="helpset.xml"/>
      <attr name="org-netbeans-modules-usersguide-below-regular.txt/org-myorg-myhelpsystem-helpset.xml" boolvalue="true"/>
    </folder>
</folder>

按 Ctrl-S 保存文件。

如果您想隐藏 IDE 的现有 helpset，则可以在 layer.xml 文件的 JavaHelp 文件夹中添加以下内容：

<file name="com-sun-enterprise-tools-studio-j2ee-helpset.xml_hidden"/>
<file name="org-netbeans-modules-j2ee-helpset.xml_hidden"/>
<file name="org-netbeans-modules-usersguide-helpset.xml_hidden"/>
<file name="org-netbeans-modules-apisupport-project-helpset.xml_hidden"/>
<file name="org-netbeans-modules-web-monitor-resources-helpset.xml_hidden"/>
<file name="org-netbeans-modules-db-helpset.xml_hidden"/> 
<file name="org-netbeans-modules-tomcat5-helpset.xml_hidden"/> 
<file name="org-netbeans-modules-dbschema-helpset.xml_hidden"/> 
<file name="org-netbeans-modules-versioning-system-cvss-resources-helpset.xml_hidden"/>

构建和安装插件

IDE 使用 Ant 构建脚本来构建和安装您的插件模块。构建脚本是在您创建 Plug-in 项目时为您创建的。

安装 NetBeans 插件

在 Projects 窗口，右键单击项目节点并在 Target Platform 中选择 Install/Reload。
插件即在目标 IDE 或 Platform 中构建和安装。打开目标 IDE 或 Platform 以便您可以试用新插件。默认目标 IDE 或 Platform 是由开发 IDE 的当前实例使用的安装平台。注意到当您运行插件时，您将使用临时测试用户目录，而不是开发 IDE 的用户目录。

使用 NetBeans 插件

选择 Help > Help Contents。
选择新的“About My Plugin”主题：
单击 Index 选项卡，向下滚动到“M”部分，然后选择您创建的索引：

创建可共享的插件二进制文件

在 Projects 窗口中，右键单击项目节点，并选择 Create NBM。
将创建 NBM 文件并且可以在 Files 窗口中查看它 (Ctrl-2)：
通过电子邮件使其他人也可以使用。

下一步

有关创建和开发 NetBeans 插件的更多信息，请参见以下资源：

插件开发者资源

NetBeans API 列表（当前开发版本）

新的 API 支持建议

版本控制

版本

日期

更改

1 2005 年 7 月 17 日初始版本

2 2005 年 10 月 20 日已包含源代码。已添加新部分“安装示例”。解决了 helpset 参考文件中的问题（doctype 和 dtd 版本号错误）。

3 2005 年 11 月 29 日添加了有关隐藏现有 helpset 的信息。

事件编号 描述状态

1 代码和教程本身需要检查。有待解决。

2 阶段 III 和阶段 IV 完成之后，需要更新教程。有待解决。

3 本教程中使用的一些 API 拥有已废弃的方法。这将在 Output 窗口中产生错误，但是不应该影响模块的功能。有待解决。

4 将源包含在一个 ZIP 文件中，以便用户可以下载它并将其与它们自己的代码相比较。包含用于下载源的链接。添加了介绍性部分，该部分解释了如何安装源并告诉您安装之后所要执行的操作。已解决。

5 通过链接解释 JavaHelp。有待解决。

6 在“创建映射文件”部分中提到了与上下文有关的帮助，但是可能不需要更详细的信息。有待解决。

7 添加一些评论和一个到样式指南的链接。有待解决。

8 什么是主文件？有待解决。

9 为什么需要 jhall.jar 而不需要 JavaHelp Integration 模块？有待解决。

10 提供其他帮助部分的名称列表，以便用户可以看到如何安排它们自己的帮助系统。究竟什么是 org-netbeans-modules-usersguide-below-regular.txt。有待解决。