Vocabulary Connection Technical Instructions

In order to represent and edit XML documents in xfy technology, we define the architecture of Vocabulary Connection. This chapter provides an overview of Vocabulary Connection.

1. Features of VC

Most XML documents are used for handling text or numeric values. With the editing tools specialized to these XML documents, you fill in pages like Web forms. It means that you can represent most XML documents by use of the presentation system for HTML.

By advancing this concept, you would be able to edit them more easily if you have a tool that allows you to both convert an XML document to an HTML display format document, and edit it by displaying and manipulating the format.

However, if you have an XML document for data other than text and numeric values, such as SVG for graphic data, you need a displaying and editing tool specific to the document.

xfy technology has been developed to provide an environment that allows you edit any XML document, including compound XML documents, without knowing the definitions for elements and attributes, just like editing documents with a word processor. xfy technology provides an optimal displaying and editing environment by applying plug-ins for display or edit to each namespace contained in a compound XML document. Since the features of xfy technology aren't specialized to a single usage, you can use it in any situation where you display or edit XML documents.

To accomplish the objective above, xfy technology provides a system that allows you to manage and use XML vocabularies appropriately.

The architecture of Vocabulary Connection (hereafter VC) has been developed to work with vocabularies on xfy technology.

The main features of VC include:

  1. Converting a source XML document, including a compound XML document, to another destination XML document.
  2. Using a view (canvas) to display the destination XML document.
  3. Allowing you to edit the source XML document by receiving your actions through the canvas.
  4. Reflecting your changes made to the source XML document to the canvas immediately.

To apply VC to XML documents, the scripting language called XVCD is defined. XVCD itself is written in XML. By applying your XVCD to the desired XML document, you can browse and edit the document using the features of VC.

Elements and attributes that build the capability of converting XML documents for VC have been redefined essentially in accordance with those of XSLT 1.0. If necessary for a particular feature, elements of XSLT 2.0 Working Draft or our own elements are included.

The XVCD allows you to specify operations that handle your actions on the canvas to edit XML documents.

1.1. Design Principle of VC

VC has been designed based on the following general rules.

  • Editing actions performed within the VC framework should always be applied to the source XML document.
    The VC framework handles events and invokes commands, responding to user actions on a canvas, to modify the source XML document. Then, it adjusts the destination XML document based on the result of the modified source XML document. Note that this is not a feedback procedure of applying the modification results of the destination to the source XML document.
  • The canvas is dedicated to display the document and send events that occur.
    The canvas is responsible only for simple tasks such as determining the XML element being edited or the type of action. And the actual meaning the action has on the XML element is determined by an inner layer instead of the canvas.
  • VC follows the standardized specifications as much as possible.
    If there are any specifications that are standardized for displaying or editing XML documents and any parts of them have common objectives, they will be used in VC. Also, VC extends those features as needed. Finally, some features may be removed if they are determined to be unnecessary.
  • VC is expandable through plug-ins.
    If an XML document cannot be represented within the existing VC framework, it will be addressed by creating a plug-in and expanding the framework with it. VC itself is created using plug-ins.
  • VC is designed only in the scope of displaying and editing XML documents, without assuming actual usage.
    Assuming actual usage may result in the feature's limitation to a particular use. To avoid it, VC is designed only for displaying and editing XML documents, which makes VC available for wider use.

1.2. Converting XML Documents with VC

Elements and attributes that build the capability of converting XML documents using VC have been redefined essentially in accordance with those of XSLT 1.0, and they have been modified and added to some other elements and attributes to fit the features intended in VC. When processing an XML document, the target nodes are specified by XPath. XPath expressions and available functions are compliant with XPath 1.0, and additional xfy technology-specific functions have been added.

The main differences between XML document conversions in VC and in XSLT 1.0 include:

Namespace, and the Element That Contains the Whole
XVCD defines different namespaces from those in XSLT. Also, it defines the xvcd:xvcd for the element that corresponds to the xsl:stylesheet element containing the whole in XSLT.
Scope of Converting an XML Document
In XSLT, the entire XML document is converted into another format. In VC, the conversion is processed by sub-trees. Each sub-tree is converted as one XML vocabulary.
Elements in XSLT 2.0 Working Draft
XVCD defines some additional elements, based on additional elements suggested in XSLT 2.0 Working Draft:
Converting a Compound XML Document
When you convert a compound XML document, VC chooses appropriate plug-ins based on the namespaces, and uses them to perform the conversion.

The main difference between the functions available in VC and those in XPath 1.0 include:

XPath operation function
A function that expands XPath operations during data conversions has been added to XVCD. When using the extended function, you must prepend to it the prefix for the namespace in which it is defined.

1.3. Building the Editing System for XML Documents with VC

Unlike XSLT, VC provides a system for responding to user actions and editing the source document. It also provides the capability for creating a new XML document based on a template document specified by a URL.

The editing system for XML documents with VC consists of the following mechanisms:

  • Editing Mechanism Provided by Extending Document Conversion Features
  • Events/Actions
  • Command Instruction
  • Commands
  • User Interface Descriptions
  • Manipulation of user data and properties
  • Support Creating New XML Documents
  • Delegation of a Process to Another Plug-in

The following sections describe these mechanisms to edit XML documents.

1.3.1. Editing Mechanism Provided by Extending Document Conversion Features

VC provides the editing mechanism by extending some document conversion features. Those features include:

Separating/Consolidating/Creating Source Element
You can separate an element in the source document by using the xvcd:split command instruction. You can also consolidate an element in the source document by using the xvcd:combine command instruction. You can insert a new element in the source document by using the xvcd:insert command instruction.
Editing Node Data in Source XML Documents
Like XSLT, when converting your XML document in VC, you can use the xvcd:value-of element to output the content of a node specified in its select attribute to the destination document as text. In this case, the output text is still not editable in VC. Instead, VC provides the xvcd:text-of element to edit the content of a node in your source XML document. You can work with the content of your source XML document for editing by using the xvcd:text-of element rather than the xvcd:value-of element. While the xvcd:value-of element is always an empty element, the xvcd:text-of element can have the xvcd:filler element. The xvcd:filler element specifies the alternative string to be used when the output text by the xvcd:text-of element becomes null for the node in your source XML document. The filler attribute of the xvcd:text-of element works just like the xvcd:filler element.

1.3.2. Command Instruction

Command instructions are basic instructions defined for editing XML documents in VC.

Some of them are specified in XVCD, and the others are specified in the platform layer of xfy technology. The command instructions in XVCD are used for edit operations on XML documents. On the other hand, those in the platform layer are used for operations on files and directories, displays of dialog boxes, conditional branches, and so on.

They are defined in a different namespace than that of XVCD.

1.3.3. Events/Actions

VC provides the event element and the xvcd:action element for mapping the user actions on the canvas to the edit operations on the document.

In VC, a user action on the canvas is represented by an XML document fragment written with the event element. The fragments are generated when the user action occurs on the canvas. You don't write an event element to describe your XVCD. The generated event elements are evaluated against the XPath expression described in the event attribute of the xvcd:action element written in your XVCD. Only if it is evaluated as true is the command instruction column described in the xvcd:action element executed.

The event element is defined in a different namespace than that of XVCD.

1.3.4. Commands

A command, which you described in the command instruction column using the xvcd:command element, represents an edit operation on the source XML document.

When invoking one of your commands in XVCD, you specify the command name described in the name attribute of the xvcd:command element. You can also use commands that are defined in the platform layer of xfy technology or expanded through plug-ins. In this case, you will use commands defined in different namespaces than that of XVCD.

1.3.5. User Interface Descriptions

VC provides the mechanism for describing user interfaces such as menus or tool bars. You can describe some user interfaces for each vocabulary. You assign commands to your menus or tool bars. Your user interface descriptions are defined in a different namespace than that of XVCD.

1.3.6. Manipulation of User Data/Properties

In VC, you can attach data such as attributes to each node without modifying the DOM tree structure in the source XML document. This data is called "user data." You can also make use of data that is independent of the documents to be edited, and shared throughout the system. This data is called "property." To retrieve the value of your user data or property, you use one of the functions that expand XPath. To change the value, you use one of the command instructions defined in XVCD.

1.3.7. Support Creating New XML Documents

In order to be considered a correct XML document, your document must have at least the root element conforming to the namespace being used, as well as the XML declaration. Because the root element depends on the namespace, you can only generate a new XML document automatically with some programming support. VC provides you with such programming support to generate a new XML document automatically. When creating a new XML document, you can specify the file or fragment to be used as a template. You can also specify the default location to save your XML documents to.

1.3.8. Delegation of a Process to Another Plug-in

Different vocabularies can be used in an XML document. In XVCD, you specify which vocabulary is used based on the XPath pattern of the sub-tree of the vertex element that is described in the match attribute of the xvcd:vocabulary element.

One vocabulary can contain other vocabularies that can be displayed or edited only with particular plug-ins different from the one in use. In this case, you can usually delegate the processes so that VC can choose appropriate plug-ins. When delegating a process for the vocabulary to another plug-in, you can specify the vertex element of the sub-tree using other vocabulary in the select attribute of the xvcd:apply-vocabularies element.

2. How VC Works

The following chart shows how VC works when you convert and edit XML documents.

How VC Works
How VC Works

The terms of VC are defined as follows:

VC plug-in
xfy technology plug-in that drives VC. They provide the core capabilities of VC.
VC manager
Generates and manages a connector factory and a command factory, following the content of a XVCD file. It is created for each XVCD file.
Source DOM Tree
The DOM tree that is created based on a source XML document. Nodes and elements in the source DOM tree are called "source nodes" and "source elements," respectively. A vocabulary is represented as a sub-tree whose vertex can be any node in the source DOM tree. The sub-tree is called a "zone" (or "source zone").
Source Pane
Contains a source DOM tree and VC canvases.
Destination DOM Tree
The DOM tree that is generated as the result of converting nodes and elements from a source DOM tree, following the content of the XVCD file. Nodes and elements in the destination DOM tree are called "destination nodes" and "destination elements," respectively.
Destination Pane
Contains a destination DOM tree and destination canvases.
Destination Canvas
The view that retrieves nodes and elements from a destination DOM tree, and displays them on the screen. It also sends user actions on the screen to the connectors associated with the destination DOM tree as events.
Connector
Attaches to a node in a source DOM tree, and creates the destination node in the destination DOM tree as needed. It modifies the destination DOM tree when the node in the source DOM tree is modified. The node in the source DOM tree that the connector attaches to is represented by XPath. Connectors form a tree structure.
VC Canvas
The canvas that contains a connector tree.
Connector Factory
Generates connectors for source nodes. A connector factory itself forms almost the same tree structure as the tag structure described in the XVCD file.
Command Factory
Generates commands for events sent from the destination canvas. A command factory itself is built into a mapping format, following the content of the XVCD file. In a command generated by the command factory, the target node in the source DOM tree for the action is represented by XPath.

VC generally processes an XML document in the following workflow:

Converting an XML Document
  1. The VC plug-in parses the XVCD file, and creates the VC manager.
  2. Creating vocabulary service for each vocabulary described in XVCD file
  3. The VC canvas is created for each vocabulary.
  4. The VC canvases generate the root node of the destination DOM tree.
  5. The VC canvas generates the connector for the vertex element of the source zone.
  6. The VC canvas invokes the method on the generated connector to generate the destination node or child connectors as needed.
  7. The connector whose method was invoked generates the destination node or child connectors as needed.
  8. The connector that generated child connectors invokes the method on the generated connectors to generate the destination nodes or child connectors as needed.
  9. Once all elements in the source zone have been processed, by repeating Steps 7 and 8, the document element contained in the root node of the destination DOM tree is set as the vertex element of the destination pane.
Generating Commands
  1. The VC manager creates the command factory by parsing descriptions about commands in the XVCD file and collating them with information from the registered plug-ins.
  2. Once all the descriptions have been processed, the map used by the command factory is created under the control of the VC manager.
Editing XML Documents
  1. The destination canvas notifies the connector for the VC canvas of a user action performed on it.
  2. The connector creates the command from the command factory for the VC manager, and executes it.
  3. The command modifies the source DOM tree.
  4. The modified node in the source DOM tree notifies the connector of its modification.
  5. The connector notified by the source node modifies the corresponding node in the destination DOM tree.
  6. The modified node in the destination DOM tree notifies the destination canvas of its modification.
  7. The destination canvas refreshes its display based on the modified destination DOM tree.
(C)2005 Justsystem Corporation.