当前页面: 开发资料首页 → Netbeans 专题 → NetBeans Help System 插件教程
摘要: NetBeans Help System 插件教程 反馈 本教程主要用来演示如何创建帮助系统以及如何在 NetBeans 文件系统中注册。 拥有描述插件的 HTML 文件之后,您必须将它们包装在插件中...
本教程主要用来演示如何创建帮助系统以及如何在 NetBeans 文件系统中注册。
拥有描述插件的 HTML 文件之后,您必须将它们包装在插件中,该插件将它们集成在 NetBeans 文件系统中。要完成此操作,您需要创建一个帮助系统。除了 HTML 文件之外,帮助系统还包含以下文件:
在本教程中您将创建这些文件中的每个文件,以及在 NetBeans 文件系统中注册帮助系统的文件。
您可以将帮助系统打包到包含 HTML 文件描述的代码的插件中,您也可以创建一个仅包含帮助系统的单独插件。本教程假设您想让帮助系统包含在单独的插件中。但是,如果您想让它们包含在 HTML 文件描述的插件中,则可以跳过“创建 Plug-in 项目”部分的前三个步骤。
本教程将介绍以下主题:
如果您在编写和集成帮助系统时有问题,请参阅模块 Helpset 集成常见问题解答。这些常见问题解答提供本教程中未涉及的很多其他详细信息。有关常规使用 NetBeans 插件的详细信息,请参阅 NetBeans 网站上的 NetBeans Development Project 主页。如果有问题,请使用本页顶部的反馈链接。
开始之前,需要在您的计算机上安装以下软件:
采用以下步骤来安装示例:
知道了最终结果后,将从头开始创建模块,并且在创建的同时了解每个部分。
IDE 创建 My Help System 项目。该项目包含所有资源和项目元数据,如该项目的 Ant 构建脚本。该项目在 IDE 中打开。您可以在 Projects 窗口 (Ctrl-1) 中查看其逻辑结构,在 Files 窗口 (Ctrl-2) 中查看其文件结构。例如,现在 Projects 窗口应该如下所示:
在 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 窗口应该显示如下:
jhall.jar=path-to-jhall.jar javahelp.base=org/myorg/myhelpsystem
需要使用这些属性来编译帮助系统。下面对它们进行解释:
jhall.jar—由 JDK 提供的库之一。
javahelp.base—将容纳 helpset .hs 文件的文件夹的完整路径。
有关以上每个文件的基本信息,请参阅 NetBeans 插件模块的快速入门指南。
在您创建目录、上下文敏感的帮助以及索引之前,您必须创建一个映射文件。该映射文件为组成您的 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" />
执行以下操作以创建映射文件:
<?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。
注意,对于上下文敏感的帮助来说,映射 ID 正常情况下是完全限定的类名称。例如,节点或对话框可能具有如下方法:
return new HelpCtx(mydialogbox.class);
在映射文件中,您将指定映射 ID 如下:
<mapID target="org.myorg.mymodule.mydialogbox" url="myhtmlfiles/about_mydialogbox.html"/>
如上所述,您在两个其他文件中使用映射文件中定义的映射 ID:
一个空的 XML 文件在 Source Editor 中打开,它的节点显示在 Projects 窗口中。
<toc version="2.0"> <tocitem text="My Plug-in"> <tocitem text="About My Plug-in" target="about_myplugin" /> </tocitem> </toc>
注意,您必须为要在帮助系统的目录中显示的每个帮助文件创建一个 <tocitem>。
<index version="2.0"> <indexitem text="My Plugin" target="about_myplugin" /> </index>
注意,您必须为要在帮助系统中索引的每个项目创建一个 <indexitem>。由于主 helpset 提供字母分隔符,因此不需要附加的插件来包含它们。
<?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>
注意到以上代码中已经将您在以前部分中定义的每个文件高亮显示。
现在 Files 窗口应该显示如下:
在 NetBeans 文件系统中注册帮助系统涉及以下文件:
helpset 参考文件参考 myplugin.hs 文件并使其可用于 layer.xml 文件。layer.xml 文件在 NetBeans 文件系统中注册帮助系统。
执行以下操作以创建 helpset 参考文件:
<!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"/>
执行以下操作以在 layer.xml 文件中注册 helpset 参考文件:
<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>
如果您想隐藏 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 项目时为您创建的。
插件即在目标 IDE 或 Platform 中构建和安装。打开目标 IDE 或 Platform 以便您可以试用新插件。默认目标 IDE 或 Platform 是由开发 IDE 的当前实例使用的安装平台。注意到当您运行插件时,您将使用临时测试用户目录,而不是开发 IDE 的用户目录。
将创建 NBM 文件并且可以在 Files 窗口中查看它 (Ctrl-2):
有关创建和开发 NetBeans 插件的更多信息,请参见以下资源:
版本
|
日期
|
更改
|
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。 | 有待解决。 |