org.eclipse.vex.ui/design.xml

<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3b2/docbookx.dtd">
<article>

  <articleinfo>

    <title>Vex Editor Design</title>

    <author><firstname>John</firstname><surname>Krasnay</surname></author>

    <revhistory>

      <revision><revnumber>0.1</revnumber><date>2005-01-06</date><authorinitials>jk</authorinitials><revdescription><para>Initial 
      version.</para></revdescription></revision>

    </revhistory>

  </articleinfo>

  <section>

    <title>Introduction</title>

    <para>This document describes the internal design of the Vex XML 
    Editor. The components described here describe the higher-level UI 
    implemented on top of the Eclipse Platform. Internals of the 
    VexWidget are described in the design document for the <literal>
    vex-toolkit</literal> module.</para>

  </section>

  <section>

    <title>Configuration Items</title>

    <para>Vex is an extensible platform for editing XML-based content. 
    Because Vex is based on the Eclipse Platform, it leverages the 
    powerful Eclipse extension point mechanism, and extensions to Vex 
    are indeed implemented as Eclipse extensions. See 
    <xref linkend="extensionpoints"/> for a list of the supported 
    extension points. Typically, Vex plugins consist of declarative 
    information such as DTD files, CSS files, and data in the <filename>
    plugin.xml</filename> file, and can usually be implemented with 
    little or no Java code. Extensions implementing Vex features such 
    as new document types and styles are hereafter referred to as 
    "configuration items".</para>

    <para>One problem with Eclipse extensions, however, is that that 
    they must be installed prior to running the executable. Within the 
    Eclipse Plug-in Development Environment, plugins are tested by 
    running another instance of the workbench, the Runtime Workbench. 
    While this makes sense for Java-based plugins, it is awkward 
    overkill for the declarative-style plugins used to extend 
    Vex.</para>

    <para>To solve this problem, we have implemented (as of v1.2) the 
    concept of Vex Plugin Projects. A Vex Plugin Project is simply a 
    project with the nature <literal>
    net.sf.vex.editor.pluginNature</literal> and configured with the 
    Vex Plugin Project Builder. When asked to build a Vex Plugin 
    Project, the builder scans the file <filename>
    vex-plugin.xml</filename> looking for extensions implementing Vex 
    configuration items. Any related resources, such as a document 
    type's DTD, are parsed. If all is well, each configuration item is 
    registered with the VexPlugin and is available for immediate use. 
    Most Vex configuration items (those that do not involve Java code) 
    can therefore be created, tested, and modified from within Vex 
    itself, without deferring to a runtime workbench.</para>

    <sidebar>

      <title>Why vex-plugin.xml?</title>

      <para>In the Eclipse SDK, the resource name 
      <filename>plugin.xml</filename> is mapped to the Eclipse Plug-in 
      Manifest Editor. In the future, we would like to provide a 
      special editor for Vex configuration items. By using a different 
      filename, we can establish this binding without disturbing the 
      default binding for <filename>plugin.xml</filename>.</para>

    </sidebar>

    <section>

      <title>Data Model</title>

      <para>Each Eclipse plug-in that defines Vex configuration items, 
      and each Vex plugin project, is associated with an instance of 
      <classname>net.sf.vex.editor.config.VexConfiguration</classname>, 
      which contains all configuration items defined by that plugin or 
      project. Each Vex configuration has a unique identifier, which 
      for Eclipse plugins is the plugin identifier. The Vex plugin 
      class, <classname>net.sf.vex.editor.VexPlugin</classname>, 
      maintains a registry of <classname>VexConfiguration</classname> 
      objects.</para>

      <para>Configuration items are defined as subclasses of 
      <classname>net.sf.vex.editor.ConfigItem</classname>, and are 
      essentially data objects with properties defining the item, for 
      example, the name and public ID of a document type. Configuration 
      items are usually associated with a resource; the 
      <classname>ConfigItem</classname> class tracks the path of this 
      resource, relative to the defining project/plugin, in the 
      <literal>resourceUri</literal> property.</para>

    </section>

    <section>

      <title>Configuration Item Factories</title>

      <para>Each type of configuration item is associated with a 
      configuration item factory, a class that implements 
      <classname>net.sf.vex.editor.config.IConfigItemFactory</classname>. 
      The factory has the following responsibilities.</para>

      <itemizedlist>

        <listitem>

          <para>To instantiate and initialize a new configuration item 
          given an array of 
          <classname>org.eclipse.core.runtime.IConfigurationElement</classname> 
          objects. These objects represent the contents of an extension 
          in <filename>plugin.xml</filename> or 
          <filename>vex-plugin.xml</filename>.</para>

        </listitem>

        <listitem>

          <para>To parse the resources associated with the 
          configuration item.</para>

        </listitem>

        <listitem>

          <para>To list the file extensions associated with resources 
          associated with that kind of configuration item.</para>

        </listitem>

      </itemizedlist>

      <para>For example, the <classname>DoctypeFactory</classname> 
      produces instances of the <classname>DocumentType</classname> 
      class, parses DTD files, and specifies that it handles re</para>

      <para />

    </section>

  </section>

  <section>

    <title id="extensionpoints">Extension Points</title>

  </section>

</article>