netbeans.apache.org/src/old_content/content/tutorials/70/nbm-xmleditor_zh_CN.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= XML 编辑器扩展模块教程
:jbake-type: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: XML 编辑器扩展模块教程 - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, XML 编辑器扩展模块教程

由 NetBeans 中文社区的  link:mailto:dev@netbeans.apache.org[Solaris_navi] 参考  link:http://gceclub.sun.com.cn/NetBeans/tutorials/plugin/nbm-taghandler.html[NetBeans Editor Extension 模块教程] 翻译

本教程演示如何创建一个继承 IDE 编辑器之一提供的功能的模块。 IDE 有许多模块 —例如，XML 编辑器、Java 编辑器、JSP 编辑器以及 SQL 编辑器。 一般来说所有的 IDE 编辑器共同来自于源编辑器。但是，每个编辑器是完全不同的 —其功能针对于其文件类型。本教程中，您将向 XML 编辑器中添加一个操作。在您创建以及安装模块，并打开 XML 文件之后， 编辑器的语境菜单讲包含一个菜单项，在输出窗口中显示 XML 文件的标签。

*注意：*本文档使用 NetBeans IDE 6.5，如果您使用更早的版本，请参照  link:60/nbm-xmleditor.html[ 6.0/6.1 版本的文档]。







另外，如果您想直接进行调试，您可以  link:http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=14039[下载完整示例]。


== 设定模块项目

在您开始写模块之前，您需要确认您的项目设置正确。IDE 提供了一个向导，用来配置所有模块需要的基本文件。


=== 创建模块项目实例


[start=1]
1. 选择 文件 > 新建项目 (Ctrl+Shift+N)。在分类中选择 Netbeans 模块。在项目中选择模块。单击 下一步。

[start=2]
1. 名称与位置面板上，在项目名称中输入  ``ShowXMLStructure`` 。 将项目位置更改到您的计算机的任意文件夹中。保持 独立模块 选项以及 设置为主项目 选项已选，单击 下一步。

[start=3]
1. 在基本模块设置面板中，在 Code Name Base 中键入  ``org.netbeans.modules.showxmlstructure`` 。

[start=4]
1. 选择“生成 XML 层”， 留出本地化包和 XML 层的位置，以便它们存储在名为  ``org/netbeans/modules/showxmlstructure``  的包中。单击 完成。

IDE 创建  ``ShowXMLStructure``  项目。该项目包含所有资源和项目元数据，如该项目的 Ant 构建脚本。该项目在 IDE 中打开。您可以在 项目 窗口 (Ctrl-1) 中查看其逻辑结构，在 文件 窗口 (Ctrl-2) 中查看其文件结构。


=== 指定模块的依存关系

您需要将几个属于 NetBeans API 的类设为子类。每个类都将被声明为模块依存关系。使用 项目属性 对话框来执行此操作，如下描述。


[start=1]
1. 在 项目 窗口中，右键单击  ``ShowXMLStructure``  项目，然后选择 属性。

[start=2]
1. 对于以下每个 API，在 类库 面板中，单击“添加...”，从 模块 列表中选择名称，然后单击 确定 确认：

*  ``I/O APIs`` 
*  ``Nodes API`` 
*  ``Text API`` 
*  ``Utilities API`` 
*  ``Window System API`` 

单击 确定，退出 项目属性 对话框。

在 项目 窗口中，展开 重要文件 结点，双击 项目元数据 并注意您选择的 API 是否声明为模块依存关系。



== 模块编码



=== 创建操作


[start=1]
1. 右键单击项目结点并选择 新建 > 其他。在 类别目录 下，选择 模块开发（Module Development）。在 项目 下选择 操作，如下图所示：


image::images/taghandler_65-action.png[]

单击 下一步。


[start=2]
1. 在 操作类型 面板中，单击 有条件启用。选择  ``EditorCookie`` ，它是允许 源编辑器 访问该 操作 的类名称，如下所示：


image::images/taghandler_65-action-2.png[]

单击 下一步。


[start=3]
1. 在 GUI 注册 面板中，选择 类别 下拉列表中的“编辑”类别。Category 下拉列表控制操作在 IDE 的 键盘快捷键 编辑器中显示的位置。接下来，选择 编辑上下文菜单项，然后选择  ``text/xml``  MIME 类型，如下所示：


image::images/taghandler_65-action-3.png[]

注意到您可以设置菜单项的位置，并且可以将它与其之前和之后的菜单项分离。单击 下一步。


[start=4]
1. 在 名称与位置 面板中，键入  ``ShowXMLStructureAction``  作为 类名称，并键入  ``Show XML Structure``  作为 显示名称。如下所示：


image::images/taghandler_65-action-4.png[]

上下文菜单提供的菜单项不显示图标。因此，单击 完成，  ``ShowXMLStructureAction.java``  便添加到包中。文件内容如下所示：


[source,java]
----

package org.netbeans.modules.showxmlstructure;

import org.openide.cookies.EditorCookie;
import org.openide.nodes.Node;
import org.openide.util.HelpCtx;
import org.openide.util.NbBundle;
import org.openide.util.actions.CookieAction;

public final class ShowXMLStructureAction extends CookieAction {

    protected void performAction(Node[] activatedNodes) {
        EditorCookie editorCookie = activatedNodes[0].getLookup().lookup(EditorCookie.class);
        // TODO use editorCookie
    }

    protected int mode() {
        return CookieAction.MODE_EXACTLY_ONE;
    }

    public String getName() {
        return NbBundle.getMessage(ShowXMLStructureAction.class, "CTL_ShowXMLStructureAction");
    }

    protected Class[] cookieClasses() {
        return new Class[]{EditorCookie.class};
    }

    @Override
    protected void initialize() {
        super.initialize();
        // see org.openide.util.actions.SystemAction.iconResource() Javadoc for more details
        putValue("noIconInMenu", Boolean.TRUE);
    }

    public HelpCtx getHelpCtx() {
        return HelpCtx.DEFAULT_HELP;
    }

    @Override
    protected boolean asynchronous() {
        return false;
    }

}
----


[start=5]
1. 在 源编辑器 中，在阅读并理解代码中的注释后，如下重写  ``performAction``  方法：

[source,java]
----

protected void performAction(Node[] activatedNodes) {
    EditorCookie editorCookie = activatedNodes[0].getLookup().lookup(EditorCookie.class);
    *//从 Bundle.properties 文件中获得标签页名称：*
    String tabName = NbBundle.getMessage(ShowXMLStructureAction.class, "LBL_tabName");
    *// "XML Structure" 标签页在 输出窗口被创建，用来显示标记列表：*
    InputOutput io = IOProvider.getDefault().getIO(tabName, false);
    io.select(); *//"XML Structure" 标签页被选择*
    try {
        *//从 EditorCookie 获取 InputStream :*
        InputStream is = ((org.openide.text.CloneableEditorSupport) editorCookie).getInputStream();
        *//使用 NetBeans org.openide.xml.XMLUtil 类创建 org.w3c.dom.Document:*
        Document doc = XMLUtil.parse(new InputSource(is), true, true, null, null);
        *//为所有元素创建一个节点列表：*
        NodeList list = doc.getElementsByTagName("*");
        *//通过列表进行迭代:*
        for (int i = 0; i < list.getLength(); i++) {
            *//For each node in the list, create a org.w3c.dom.Node:*
            org.w3c.dom.Node mainNode = list.item(i);
            *//创建所有 org.w3c.dom.Node 的属性的映射：*
            NamedNodeMap map = mainNode.getAttributes();
            *//得到节点名称：*
            String nodeName = mainNode.getNodeName();
            *//为节点属性创建 StringBuilder:*
            StringBuilder attrBuilder = new StringBuilder();
            *//通过属性映射进行迭代:*
            for (int j = 0; j < map.getLength(); j++) {
                *//每一次迭代，创建一个新的节点：*
                org.w3c.dom.Node attrNode = map.item(j);
                *//获得当前属性的名称：*
                String attrName = attrNode.getNodeName();
                *//将当前属性添加到 StringBuilder:*
                attrBuilder.append("*" + attrName + " ");
            }
            *//在 输出窗口 中打印元素及其属性：*
            io.getOut().println("ELEMENT: " + nodeName +
                    " --> ATTRIBUTES: " + attrBuilder.toString());
        }
        *//关闭 InputStream:*
        is.close();
    } catch (SAXException ex) {
        Exceptions.printStackTrace(ex);
    } catch (IOException ex) {
        Exceptions.printStackTrace(ex);
    }
}
----


[start=6]
1. 将显示名称添加到  ``Bundle.properties``  文件中：


[source,java]
----

LBL_tabName=XML Structure
----



== 构建并安装模块

IDE 使用 Ant 构建脚本来构建和安装您的模块。构建脚本是创建模块项目时为您创建的。


=== 安装模块

在 项目窗口 中，右键单击  ``ShowXMLStructure``  项目，选择运行。

模块即在目标 IDE 或平台中构建和安装。目标 IDE 或平台打开后，您可以试用新的模块。默认目标 IDE 或平台是由开发 IDE 的当前实例使用的安装平台。注意到当您运行模块时，您将使用临时测试用户目录，而不是开发 IDE 的用户目录。


=== 使用模块


[start=1]
1. 选择 文件 > 新建工程 (Ctrl-Shift-N) 创建一个新的工程。


[start=2]
1. 在文件窗口(Ctrl-2)中，展开工程结点，并展开  ``nbproject``  结点。 双击  ``build-impl.xml``  打开源编辑器


[start=3]
1. 在源编辑器中任意位置单击右键，注意弹出菜单中叫做“Show XML Structure”的菜单项。 选择该项并注意标签处理器在输出窗口中打印出所有元素以及属性，输出窗口在 IDE 的底部，如下图所示：


image::images/taghandler_65-result.png[]


[start=4]
1. 在源编辑器中打开一个其他类型的文件。例如，打开一个 Java 类文件。在源编辑器中任意位置单击右键并注意到新建的子菜单项并没有被包含在上下文菜单中。这是因为新建操作向导创建了一个只对 XML 文件有效的操作：


[source,xml]
----

<folder name="Actions">
    <folder name="Edit">
        <file name="org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.instance"/>
    </folder>
</folder>
<folder name="Editors">
    <folder name="text">
        <folder name="xml">
            <folder name="Popup">
                <file name="org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.shadow">
                    <attr name="originalFile" stringvalue="Actions/Edit/org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.instance"/>
                    <attr name="position" intvalue="1100"/>
                </file>
            </folder>
        </folder>
    </folder>
</folder>
----


=== 创建可共享的模块二进制文件


[start=1]
1. 在项目窗口中哦能够，右键单击  ``ShowXMLStructure``  项目，选择 创建 Netbeans 模块(NBM)。

NBM 文件则被建立，您可以在文件窗口中看到（Ctrl-2）：


image::images/taghandler_65-nbm-generated.png[]


[start=2]
1. 将其共享给其他人，例如，  link:http://plugins.netbeans.org/PluginPortal/[通过插件入口]。


link:http://netbeans.apache.org/community/mailing-lists.html[请将您的反馈发送给我们]



== 进阶

更多关于创建以及开发 Netbeans 模块的信息，请访问一下资源：

*  link:https://netbeans.apache.org/kb/docs/platform.html[其他相关教程]
*  link:https://bits.netbeans.org/dev/javadoc/[NetBeans API Javadoc]


== 版本控制

|===
|*版本* |*日期* |*变更* 

|1 |2005年7月11日 |初版 

|2 |2005年9月27日 |

* 添加了操作向导
* 重命名本文档，原名为“ Netbeans 标签处理器插件教程”，现为“ Netbeans 源编辑器扩展模块教程”
* 在下面添加了 Issue 7 。
 

|3 |2005年9月28日 |

* 由于“Source Editor”不包含 SQL 编辑器（还可以在本教程中使用一些步骤进行扩展），因此，对该教程进行重新命名。
* 重新编写介绍性段落。
 

|4 |2007年6月11日 |将整个教程更新清理为 Netbeans 6.0 版本，同时更改了截图。 

|5 |2007年11月17日 |修复了步骤间的空行，并尝试附上如其所描述的示例。 

|6 |2008年11月1日 |更新至Netbeans 6.5：徽章，表格等，但通过使用NetBeans XMLUtil类也大大简化了教程， 因此消除了一整个章节和大量的代码。 
|===

|===
|*Issue 序号* |*描述* |*状态* 

|1 |代码以及本身教程需要审核。 |有待解决。 

|2 |阶段 III 和阶段 IV 完成之后，需要更新教程。 |已修复。 

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

|4 |将为所有 API、类和方法添加清晰的解释和到 Javadoc 的链接。还要添加每个依存关系的链接以及本教程需要它们的原因。 |有待解决。 

|5 |应该提到 JSP 编辑器、HTML 编辑器等其他标识符。例如，不使用“xml”（在 layer.xml 中），而使用“html”、“x-properties”、“base”等等。 |有待解决。 

|6 |解释什么是 Cookie 及其操作。 |有待解决。 

|7 |由于当前在可下载的代码中标记句柄和显示 XML 操作是单独的文件，而它们又是相同的文件，因此需要更改可下载代码。由于相同的原因，也必须更改一个文件的屏幕截图，而不是更改上面显示的两个文件的屏幕截图。 |已修复。 
|===