dacarver | 58ad0f8 | 2008-10-01 03:29:54 +0000 | [diff] [blame] | 1 | <?xml version='1.0'?> |
| 2 | <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3b2/docbookx.dtd"> |
| 3 | <article> |
| 4 | |
| 5 | <articleinfo> |
| 6 | |
| 7 | <title>Vex Editor Design</title> |
| 8 | |
| 9 | <author><firstname>John</firstname><surname>Krasnay</surname></author> |
| 10 | |
| 11 | <revhistory> |
| 12 | |
| 13 | <revision><revnumber>0.1</revnumber><date>2005-01-06</date><authorinitials>jk</authorinitials><revdescription><para>Initial |
| 14 | version.</para></revdescription></revision> |
| 15 | |
| 16 | </revhistory> |
| 17 | |
| 18 | </articleinfo> |
| 19 | |
| 20 | <section> |
| 21 | |
| 22 | <title>Introduction</title> |
| 23 | |
| 24 | <para>This document describes the internal design of the Vex XML |
| 25 | Editor. The components described here describe the higher-level UI |
| 26 | implemented on top of the Eclipse Platform. Internals of the |
| 27 | VexWidget are described in the design document for the <literal> |
| 28 | vex-toolkit</literal> module.</para> |
| 29 | |
| 30 | </section> |
| 31 | |
| 32 | <section> |
| 33 | |
| 34 | <title>Configuration Items</title> |
| 35 | |
| 36 | <para>Vex is an extensible platform for editing XML-based content. |
| 37 | Because Vex is based on the Eclipse Platform, it leverages the |
| 38 | powerful Eclipse extension point mechanism, and extensions to Vex |
| 39 | are indeed implemented as Eclipse extensions. See |
| 40 | <xref linkend="extensionpoints"/> for a list of the supported |
| 41 | extension points. Typically, Vex plugins consist of declarative |
| 42 | information such as DTD files, CSS files, and data in the <filename> |
| 43 | plugin.xml</filename> file, and can usually be implemented with |
| 44 | little or no Java code. Extensions implementing Vex features such |
| 45 | as new document types and styles are hereafter referred to as |
| 46 | "configuration items".</para> |
| 47 | |
| 48 | <para>One problem with Eclipse extensions, however, is that that |
| 49 | they must be installed prior to running the executable. Within the |
| 50 | Eclipse Plug-in Development Environment, plugins are tested by |
| 51 | running another instance of the workbench, the Runtime Workbench. |
| 52 | While this makes sense for Java-based plugins, it is awkward |
| 53 | overkill for the declarative-style plugins used to extend |
| 54 | Vex.</para> |
| 55 | |
| 56 | <para>To solve this problem, we have implemented (as of v1.2) the |
| 57 | concept of Vex Plugin Projects. A Vex Plugin Project is simply a |
| 58 | project with the nature <literal> |
| 59 | net.sf.vex.editor.pluginNature</literal> and configured with the |
| 60 | Vex Plugin Project Builder. When asked to build a Vex Plugin |
| 61 | Project, the builder scans the file <filename> |
| 62 | vex-plugin.xml</filename> looking for extensions implementing Vex |
| 63 | configuration items. Any related resources, such as a document |
| 64 | type's DTD, are parsed. If all is well, each configuration item is |
| 65 | registered with the VexPlugin and is available for immediate use. |
| 66 | Most Vex configuration items (those that do not involve Java code) |
| 67 | can therefore be created, tested, and modified from within Vex |
| 68 | itself, without deferring to a runtime workbench.</para> |
| 69 | |
| 70 | <sidebar> |
| 71 | |
| 72 | <title>Why vex-plugin.xml?</title> |
| 73 | |
| 74 | <para>In the Eclipse SDK, the resource name |
| 75 | <filename>plugin.xml</filename> is mapped to the Eclipse Plug-in |
| 76 | Manifest Editor. In the future, we would like to provide a |
| 77 | special editor for Vex configuration items. By using a different |
| 78 | filename, we can establish this binding without disturbing the |
| 79 | default binding for <filename>plugin.xml</filename>.</para> |
| 80 | |
| 81 | </sidebar> |
| 82 | |
| 83 | <section> |
| 84 | |
| 85 | <title>Data Model</title> |
| 86 | |
| 87 | <para>Each Eclipse plug-in that defines Vex configuration items, |
| 88 | and each Vex plugin project, is associated with an instance of |
| 89 | <classname>net.sf.vex.editor.config.VexConfiguration</classname>, |
| 90 | which contains all configuration items defined by that plugin or |
| 91 | project. Each Vex configuration has a unique identifier, which |
| 92 | for Eclipse plugins is the plugin identifier. The Vex plugin |
| 93 | class, <classname>net.sf.vex.editor.VexPlugin</classname>, |
| 94 | maintains a registry of <classname>VexConfiguration</classname> |
| 95 | objects.</para> |
| 96 | |
| 97 | <para>Configuration items are defined as subclasses of |
| 98 | <classname>net.sf.vex.editor.ConfigItem</classname>, and are |
| 99 | essentially data objects with properties defining the item, for |
| 100 | example, the name and public ID of a document type. Configuration |
| 101 | items are usually associated with a resource; the |
| 102 | <classname>ConfigItem</classname> class tracks the path of this |
| 103 | resource, relative to the defining project/plugin, in the |
| 104 | <literal>resourceUri</literal> property.</para> |
| 105 | |
| 106 | </section> |
| 107 | |
| 108 | <section> |
| 109 | |
| 110 | <title>Configuration Item Factories</title> |
| 111 | |
| 112 | <para>Each type of configuration item is associated with a |
| 113 | configuration item factory, a class that implements |
| 114 | <classname>net.sf.vex.editor.config.IConfigItemFactory</classname>. |
| 115 | The factory has the following responsibilities.</para> |
| 116 | |
| 117 | <itemizedlist> |
| 118 | |
| 119 | <listitem> |
| 120 | |
| 121 | <para>To instantiate and initialize a new configuration item |
| 122 | given an array of |
| 123 | <classname>org.eclipse.core.runtime.IConfigurationElement</classname> |
| 124 | objects. These objects represent the contents of an extension |
| 125 | in <filename>plugin.xml</filename> or |
| 126 | <filename>vex-plugin.xml</filename>.</para> |
| 127 | |
| 128 | </listitem> |
| 129 | |
| 130 | <listitem> |
| 131 | |
| 132 | <para>To parse the resources associated with the |
| 133 | configuration item.</para> |
| 134 | |
| 135 | </listitem> |
| 136 | |
| 137 | <listitem> |
| 138 | |
| 139 | <para>To list the file extensions associated with resources |
| 140 | associated with that kind of configuration item.</para> |
| 141 | |
| 142 | </listitem> |
| 143 | |
| 144 | </itemizedlist> |
| 145 | |
| 146 | <para>For example, the <classname>DoctypeFactory</classname> |
| 147 | produces instances of the <classname>DocumentType</classname> |
| 148 | class, parses DTD files, and specifies that it handles re</para> |
| 149 | |
| 150 | <para /> |
| 151 | |
| 152 | </section> |
| 153 | |
| 154 | </section> |
| 155 | |
| 156 | <section> |
| 157 | |
| 158 | <title id="extensionpoints">Extension Points</title> |
| 159 | |
| 160 | </section> |
| 161 | |
| 162 | </article> |
| 163 | |