Developing Vocabulary Component with XVCD Tutorial

Provides procedures with simple examples to create a vocabulary component using XVCD.

1. Before Starting Tutorial

This tutorial explains in detail the development task of vocabulary component with XVCD in sequence using very simple examples. By working through this tutorial, you can advance your skills in XVCD programming.

Sample codings in this tutorial are contained doc/dev/samples/features/tutorial/ in xfy Developer's Toolkit distribution package. Many XVCD samples are provided in the xfy Developer's Toolkit in addition to the tutorial. Be sure to see the samples.

Incidently, xfy Basic Edition is used as the xfy technology user agent.

1.1. Prerequisite information

In this tutorial, it is assumed that you are familiar with the following items, and have the skill to work out simple examples:

XML
XML Namespace
XPath Expression
XSLT
XHTML

1.2. Preparation

Now, let's install the xfy Developer's Toolkit before starting the tutorial with xfy Basic Edition. If xfy Developer's Toolkit is not installed, you are unable to load vocabulary component developed with XVCD.

If you use xfy Basic Edition 1.0, you don't need to install xfy Developer's Toolkit since xfy Basic Edition 1.0 already includes xfy Developer's Toolkit.

For the installation procedure of xfy Developer's Toolkit, see the installation procedure document (installation_dev.ja.html) in the xfy Developer's Toolkit distribution package.

It is useful to show the Browse Bar in xfy Basic Edition. The Browse Bar is not shown immediately following xfy Basic Edition installation. To show the Browse Bar, select [View - Browse Bar].

2. Displaying an XML Document

In the first step, display XML document in xfy Basic Edition. This chapter provides you a minimum set to create the vocabulary component running in xfy Basic Edition using XVCD.

2.1. Displaying "Hello World!"

This section provides the time-honored "Hello World!" example for your understanding. XML document file to display and the vocabulary components with XVCD are required.

2.1.1. XML Document Definition

First of all, create the XML document file to display. Here, create the following XML document:

<?xml version="1.0"?>

<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

This XML document has hw:message element as a child element of hw:document element. The string "Hello World!" is in hw:message element.

After XML document is created, save it as the file name HelloWorld.xml in an appropriate folder.

2.1.2. Creating Vocabulary Component with XVCD

Then, create a vocabulary component with XVCD. The XVCD which displays the XML document above:

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld"
    version="1.0">

    <xvcd:vocabulary name="HelloWorld" match="hw:document" call-template="root"/>

    <xvcd:template name="root">
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xvcd:apply-templates/>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="hw:message">
        <p>
            <xvcd:value-of select="."/>
        </p>
    </xvcd:template>
</xvcd:xvcd>

Creation of the minimum vocabulary component with XVCD is now completed. This vocabulary component is so simple only to display content of hw:message element.

Here, save the created XVCD as the file name HelloWorld.xvcd. Save HelloWorld.xvcd in the same folder as HelloWorld.xml.

2.1.3. XVCD File Association

Here, associate the HelloWorld.xml with HelloWorld.xvcd. Open HelloWorld.xml in a text editor and change it as follows: The highlighted strings are changed.

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

After HelloWorld.xml is changed, save it and exit the text editor.

XVCD File Association by Processing Instruction

There are two ways to create the xfy technology vocabulary component: using Java and using XVCD. In general, to use vocabulary component in xfy technology user agent, you should create a JAR file and install it in environment of xfy technology user agent. (With the vocabulary component of XVCD, you can easily install and use it as the vocabulary component by placing XVCD file under the scripts folder. ) After installing component, you must restart the xfy technology user agent.

However, to check the process of vocabulary component under development, because you must again and again repeat installation and restart xfy technology user agent, it greatly takes time and effort.

Therefore, in order to efficiently develop vocabulary component with XVCD, you can specify the XVCD file to associate with the XML document file in a Processing Instruction and temporarily register the vocabulary component. You can use the XVCD vocabulary component registered in this manner without installing the xfy technology user agent. After changing the XVCD file, you don't have to restart the xfy technology user agent. By reloading the XML document file, the XVCD file's changes also are reflected and displayed.

In addition, association of XVCD file and temporary registration of vocabulary components by processing instruction are effective only when the xfy Developer's Toolkit is installed.

2.1.4. Display in xfy Basic Edition

Now, let's display HelloWorld.xml in xfy Basic Edition.

Start xfy Basic Edition
Select [File-Open]
Select HelloWorld.xml and click [Open]

Is the file shown as follows?

Hello World!

2.1.5. Hello xfy world!

You have now created the XML document file to display and the vocabulary components with XVCD. You have now learned how to associate XML document file with XVCD file and register vocabulary component. And, you checked the sentence "Hello World!" is displayed in xfy Basic Edition.

2.2. Understanding HelloWorld.xvcd

In [Creating Vocabulary Component with XVCD], HelloWorld.xvcd is described as a simple XVCD only to display content of hw:message element. Here, we explain the content of HelloWorld.xvcd in detail.

2.2.1. Template

Again, let's look at HelloWorld.xvcd.

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld"
    version="1.0">

    <xvcd:vocabulary name="HelloWorld" match="hw:document" call-template="root"/>

    <xvcd:template name="root">
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xvcd:apply-templates/>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="hw:message">
        <p>
            <xvcd:value-of select="."/>
        </p>
    </xvcd:template>
</xvcd:xvcd>

If you are astute, you'll notice XVCD has similar notation to XSLT. The following XSLT provides the same result:

<?xml version="1.0"?>

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld"
    version="1.0">

    <xsl:output method="html"/>

    <xsl:template match="/">
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xsl:apply-templates/>
            </body>
        </html>
    </xsl:template>

    <xsl:template match="hw:message">
        <p>
            <xsl:value-of select="."/>
        </p>
    </xsl:template>
</xsl:stylesheet>

The sections of each template element have nearly the same content. The specifications of XVCD template more or less comply with XSLT 1.0. Functions required to edit XML document are also extended.

xfy Basic Edition creates a view by converting target source XML document in accordance with the rule (template) defined in XVCD. In the HelloWorld.xvcd example, HelloWorld.xml is displayed by converting to XHTML. Those who understand XSLT will be able to learn XVCD easily.

2.2.2. Details of HelloWorld.xvcd

Now, let's look into HelloWorld.xvcd more closely.

<?xml version="1.0"?>
<!-- As XVCD is a kind of XML, it begins with an XML declaration. -->

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd"            
    xmlns="http://www.w3.org/1999/xhtml"                 
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld" 		
    version="1.0">
    <!--
        xvcd:xvcd  : XVCD vertex element
        xmlns:xvcd : XML namespace declaration of XVCD
        xmlns      : XML namespace declaration of XHTML
        xmlns:hw   : XML namespace declaration of the HellowWorld vocabulary
        version    : XVCD version number
    -->

    <xvcd:vocabulary name="HelloWorld" match="hw:document" call-template="root"/>
    <!-- Declaration to be registered as vocabulary component -->
   
    <xvcd:template name="root">
    <!-- Template named root -->
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xvcd:apply-templates/>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="hw:message">
    <!-- template to be applied when matching to hw:message -->
        <p>
             <xvcd:value-of select="."/>
        </p>
    </xvcd:template>
</xvcd:xvcd>

xvcd:xvcd Element
Vertex element of VC core. The namespace URI reference for VC Core is http://xmlns.xfytec.com/xvcd .
xvcd:vocabulary Element
Element to declare a vocabulary component that handles a sub-tree with its tip at the element matching the pattern specified as match attribute value. If multiple xvcd:vocabulary elements match to an element, switchable components displayed by [Tools - Change Vocabulary Component] may increase. For the content of this element, describe vocabulary name, user interface definition such as menu, tool bar.
xvcd:template Element
Describe the mapping from target source XML document to destination XML document. It may be nearly the same as an XSLT template element. Essentially, describe destination XML document as it is. If necessary, refer to source XML document in xvcd:value-of element or xvcd:text-of element, or invoke other template in xvcd:apply-templates element or xvcd:call-template element.

For detailed specifications of VC core, see the VC Core Reference.

2.2.3. Process Flow

We will continue to follow the process flow of HelloWorld.xvcd.

If HelloWorld.xml is opened in xfy Basic Edition, xfy Basic Edition will process the following:

It refers to the XVCD file associated in processing instruction and temporarily register the vocabulary component defined in the file in xfy Basic Edition.
The description of com.xfytec vocabulary-connection processing instruction below registers the vocabulary component described in the HelloWorld.xvcd in xfy Basic Edition, allowing you to use it.
```
<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
```
xfy Basic Edition searches for vocabulary components that are able to handle the root element of an XML document.
In this case, the following description matches:
```
<xvcd:vocabulary match="hw:document" name="HelloWorld" call-template="root"/>
```
The vocabulary component HelloWorld is applied.
It refers to the value set in the call-template attribute in xvcd:vocabulary element and invokes a template to apply.
In this case, the template root is invoked. The root template is a content of xvcd:template element described below:
```
<xvcd:template name="root">
```
This template is applied, and destination XML document is constructed in sequence.
The process of a context node is delegated to a template defined elsewhere by xvcd:apply-templates element described in root template.
This process is the same as xsl:apply-templates element.
A template defined for hw:message is applied.
This template is a content of xvcd:template element described below:
```
<xvcd:template match="hw:message">
```
After the following description of this template is processed, "Hello world!" described as content in hw:message element is added to the destination XML document.
```
<xvcd:value-of select="."/>
```

The destination XML document is constructed as follows:

<?xml version="1.0"?>

<html xmlns="http://www.w3.org/1999/xhtml" >
    <head>
        <title>HelloWorld example</title>
    </head>
    <body>
        <p>
            Hello world! 
        </p>
    </body>
</html>

based on destination XML document, xfy Basic Edition displays it on the screen using the XHTML vocabulary component.

2.3. Summary

The lessons learned here is summarized below:

Target Data
Describe target data as XML document in XML format. Here, describe a processing instruction to associate XML document with developing XVCD file.
Vocabulary Component with XVCD
Also describe vocabulary component with XVCD in XML format. Based on template definition in XVCD, construct a destination XML document from the source XML document. XVCD template definition is similar to XSLT.
Here, the destination XML document is constructed by XHTML and displayed by xfy Basic Edition.

3. Editing String in XML Document

In [Displaying and Editing an XML Document], you have now learned how to display "Hello World!". There is nothing exciting in showing this, because it is also possible with XSLT. This chapter explains about XML document editing which features xfy technology.

3.1. Editing "Hello World!"

We will continue to explain HelloWorld.xml and HelloWorld.xvcd [Displaying and Editing an XML Document] for example. To edit, the XML document file, like displaying, and XVCD file is required. In [Displaying and Editing an XML Document], we used the example to display "Hello World!". Here, we use it again to make it possible to edit string.

3.1.1. XVCD Definition

To make it possible to edit string, it is only required to replace <xvcd:value-of select="."/> with <xvcd:text-of select="."/>. How simple it is.

Open HelloWorld.xvcd in a text editor and edit it as follows: The highlighted strings are changed.

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld"
    version="1.0">

    <xvcd:vocabulary name="HelloWorld2" match="hw:document" call-template="root"/>

    <xvcd:template name="root">
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xvcd:apply-templates/>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="hw:message">
        <p>
            <xvcd:text-of select="."/>
        </p>
    </xvcd:template>
</xvcd:xvcd>

After editing is complete, save it as the file name HelloWorld2.xvcd.

xvcd:value-of element, like value-of of XSLT, is to display the result of executing XPath function specified in select attribute. It can display the information described in XML document, but it cannot edit the information. xvcd:text-of element joins source XML document and destination XML document. The displayed string is editable. The edited string is applied to a source XML document. In xvcd:text-of element, like xvcd:value-of element, specify XPath expression in select attribute. However, it differs from xvcd:value-of element in the fact that this XPath expression's evaluation must refer to either of a text node, an attribute, an element which contains only one text node

3.1.2. Referring Vocabulary Component

In HelloWorld.xml, a processing instruction is described to associate HelloWorld.xvcd. You may change the file name, but here we shall append a processing instruction. Open HelloWorld.xml in a text editor and edit it as follows: The highlighted strings are changed.

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfytec vocabulary-connection href="HelloWorld2.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

Thus, you can describe multiple processing instructions to specify an association with XVCD.

3.1.3. Display in xfy Basic Edition

After modification is complete, let's display it in xfy Basic Edition. Open HelloWorld.xml in xfy Basic Edition. If it is already opened, select [View - Reload] or click in the Browse Bar.

Open HelloWorld.xml again

Although changed, the change is not applied to the current display. What's the story?

Because, there are multiple vocabulary components to process HelloWorld.xml, in this status, the HelloWorld.xvcd specified by first processing instruction is applied (display-only vocabulary component created in [Displaying and Editing an XML Document]).

Now let's switch to a component for editing. In order to switch vocabulary components, there exists a way to select [Tool - Change Vocabulary Component] to toggle it in the shown dialog box, and a way to switch it using drop-down list in the Document View Area. Here, switch it using the drop-down list. Now, see xfy Basic Edition screen. There is a drop-down list to switch vocabulary components at the top right corner of the Document View Area. Currently, you should see "HelloWorld". By clicking it, you can see HelloWorld and HelloWorld2 are registered in the drop-down list.

Select Vocabulary Component

In the drop-down list, the string specified in name attribute of xvcd:vocabulary element is shown. As "<xvcd:vocabulary name="HelloWorld2"..." is specified in HelloWorld2.xvcd, select HelloWorld2.

Vocabulary Component for Editing Is Applied

Applied by Vocabulary Component for Editing

Now, Blue Caret Is Shown. You can move the caret using cursor keys, and input characters at the caret position.

Moved the Caret after Hello and Input xfy

By using the Delete key and the Back space key, you can delete characters. What happens when you delete all the characters? Let's try.

Deleted All Characters

"???" is shown. If there is no string referenced by xvcd:text-of element, xfy Basic Edition tells you that "Here is an area to edit." You can change the "???" string to any preferred message. Next section will provide the explanation.

3.2. Filler Attribute

Here, we explain the filler attribute of xvcd:text-of element that specifies a guidance message displayed when there is no string referenced by xvcd:text-of element.

3.2.1. XVCD Definition

To make it possible to edit text data, it was only required to replace <xvcd:value-of select="."/> with <xvcd:text-of select="."/>. Further, append an attribute filler="Enter any text here" to xvcd:text-of element.

Open HelloWorld2.xvcd in a text editor and edit it as follows: The highlighted strings are changed.

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.xfytec.com/samples/helloworld"
    version="1.0">

    <xvcd:vocabulary name="HelloWorld3" match="hw:document" call-template="root"/>

    <xvcd:template name="root">
        <html>
            <head>
                <title>HelloWorld example</title>
            </head>
            <body>
                <xvcd:apply-templates/>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="hw:message">
        <p>
            <xvcd:text-of select="." filler="Enter any text here."/>
        </p>
    </xvcd:template>
</xvcd:xvcd>

After editing is complete, save it as the file name HelloWorld3.xvcd.

3.2.2. Referring Vocabulary Component

Like HelloWorld2.xvcd, append a processing instruction that associates HelloWorld3.xvcd to the XML document file.

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfytec vocabulary-connection href="HelloWorld2.xvcd" ?>
<?com.xfytec vocabulary-connection href="HelloWorld3.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

3.2.3. Display in xfy Basic Edition

After modification is complete, let's make sure to display it in xfy Basic Edition as follows:

Open HelloWorld.xml in xfy Basic Edition.
If it is already opened, select [View - Reload] or click in the Browse Bar.
Switch vocabulary component to the HelloWorld3 in the drop-down list for switching the vocabulary component.
Delete all the string "Hello World!".

Effect of filler attribute

In HelloWorld2, "???" is displayed when there is no string referenced by xvcd:text-of element. In HelloWorld3, "Enter any text here." is displayed.

3.3. Saving Edited XML Document

In the former section, we explained that using xfy Basic Edition allows you to edit strings. It is of no use if edited data can not be saved. In this section, we shall save an edited XML document.

3.3.1. Save

Perform the following steps to make sure XML document is saved:

Open HelloWorld.xml in xfy Basic Edition.
Switch vocabulary component to the HelloWorld3 in the drop-down list for switching the vocabulary component.
Edit the string "Hello World!" appropriately.
Select [File - Save] to save edited XML document.

Saving Edited XML Document

Check the saved content. Open HelloWorld.xml in a text editor. Here is an example that changed the "Hello World!" to "Here is the New XML World.".

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfytec vocabulary-connection href="HelloWorld2.xvcd" ?>
<?com.xfytec vocabulary-connection href="HelloWorld3.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Here is the New XML World.
    </hw:message> 
</hw:document>

The edited content is reflected to the content of hw:message element.

3.4. Summary

The lessons learned here is summarized below:

Replacing the XML document referred by xvcd:value-of element with xvcd:text-of element makes the text editable. (Note: some select attribute's content may not be replaced. For more information, see select attribute of xvcd:text-of element of VC Core Reference.)
When there is no string referenced by xvcd:text-of element, guidance message may be displayed.
You can specify association with multiple XVCD files in XML documents. If an XML document can be processed by multiple vocabulary components including associated XVCD file, you can switch to a vocabulary component in the menu or drop-down list.

4. Addition and Deletion of XML Document's Data Structure

In [Editing String in XML Document], you have learned how to edit only string without changing fixed structure of XML document. This chapter explains how to dynamically edit the data structure of XML document.

4.1. Address Book

Here, create the data structure of target XML document using simple address book.

4.1.1. XML Data Definition

Consider the example of simple address book, managing name and address only. As an address book, it is necessary to deal with multiple pairs of someone's name and address. Defining the data structure of XML document below allows you to meet this requirement:

<?xml version="1.0"?>
<ab:addressbook xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"> 
    <ab:entry>
        <ab:person>George Adams</ab:person>
        <ab:address>Rochester, NY, USA</ab:address>
    </ab:entry>
    <ab:entry>
        <ab:person>Betty Jackson</ab:person>
        <ab:address>Denver, Colorado USA</ab:address>
    </ab:entry>
</ab:addressbook>

The data structure of address book XML is as follows:

The ab:addressbook element has multiple ab:entry elements as a child element.
The ab:entry element has a pair of ab:person element and ab:address element as a child element.
The text in ab:person element means person's name.
The text in ab:address element means an address.

To make data structure definition clear, the DTD definition for reference is listed below. Xfy technology incidently does not check validation etc., using DTD definition. A DTD file does not have to be created.

<!DOCTYPE addressbook [ 
<!ELEMENT addressbook entry+>
<!ELEMENT entry person,address>
<!ELEMENT person (#PCDATA)>
<!ELEMENT address (#PCDATA)>
]>

Although the XVCD file is not created yet, specify the XVCD file to associate with this XML document in advance. Let's assume the XVCD file name to create is AddressBook.xvcd.

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="AddressBook.xvcd" ?>
<ab:addressbook xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"> 
    <ab:entry>
        <ab:person>George Adams</ab:person>
        <ab:address>Rochester, NY, USA</ab:address>
    </ab:entry>
    <ab:entry>
        <ab:person>Betty Jackson</ab:person>
        <ab:address>Denver, Colorado USA</ab:address>
    </ab:entry>
</ab:addressbook>

After the address book XML document is successfully created, save it as the file name AddressBook.xml.

4.1.2. XVCD Definition

Then, create a vocabulary component with XVCD which displays address book. The XVCD which displays the AddressBook.xml:

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"
    version="1.0">

    <xvcd:vocabulary name="AddressBook" match="ab:addressbook" call-template="root"/>

    <xvcd:template name="root">
        <html>
            <body>
                <table border="1" width="100%">
                    <tr>
                        <th width="150">
                            Name
                        </th>
                        <th>
                            Address
                        </th>
                    </tr>
                   <xvcd:apply-templates select="ab:entry"/>
                </table>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="ab:entry">
        <tr>
            <td>
                <xvcd:apply-templates select="ab:person"/>
            </td>
            <td>
                <xvcd:apply-templates select="ab:address"/>
            </td>
        </tr>
    </xvcd:template>

    <xvcd:template match="ab:person">
        <xvcd:text-of select="." filler="Enter the name here."/>
    </xvcd:template>

    <xvcd:template match="ab:address">
        <xvcd:text-of select="." filler="Enter the address here."/>
    </xvcd:template>
</xvcd:xvcd>

Display the data, using a table, in table format. We have already learned about XVCD content, so it will not be covered here. Here, save it as the file name AddressBook.xvcd.

When you open AddressBook.xml in xfy Basic Edition, the destination XML document is constructed and displayed in XHTML as follows:

<?xml version="1.0"?>

<html xmlns="http://www.w3.org/1999/xhtml">
<body>
    <table border="1" width="100%">
        <tr>
            <th width="150">Name</th>
            <th>Address</th>
        </tr>
        <tr>
            <td>George Adams</td>
            <td>Rochester, NY, USA</td>
        </tr>
        <tr>
            <td>Betty Jackson</td>
            <td>Denver, Colorado USA</td>
        </tr>
    </table>
</body>
</html>

4.1.3. Display in xfy Basic Edition

Now, display the created address book in xfy Basic Edition. Open AddressBook.xml in xfy Basic Edition. Is the file shown as follows?

Table view

Although the VCD can be displayed, you cannot call it an address book. In an address book, it needs to allow you to append new address entries. The following section explains how to append address entries. It also explains how to delete an entry from the address book.

4.2. Addition and Deletion of Address Entry

To append or delete address entry, free manipulation of data structure of XML document is required. Also, a user needs to be able to instruct the VCD to append or delete address entries.

4.2.1. Address Book Data Image

First, imagine how data structure of XML document needs to be changed. If AddressBook.xml looks like the following, an address entry will be appended. The highlighted strings indicate structures.

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="AddressBook.xvcd" ?>
<ab:addressbook xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"> 
    <ab:entry>
        <ab:person>George Adams</ab:person>
        <ab:address>Rochester, NY, USA</ab:address>
    </ab:entry>
    <ab:entry>
        <ab:person>Betty Jackson</ab:person>
        <ab:address>Denver, Colorado USA</ab:address>
    </ab:entry>
    <ab:entry>
        <ab:person/>
        <ab:address/>
    </ab:entry>
</ab:addressbook>

4.2.2. Adding XML Document Fragment to XML Document Data Structure

To append an XML document fragment (XML sub-tree structure) to the data structure of an XML document, define the command using a vocabulary component with XVCD and describe a command instruction in it to insert the XML document fragment into the data structure of an XML document. In the command, describe and define xvcd:command element as a child element of xvcd:xvcd element.

The command instruction to append XML document fragment to the data structure of XML document is xvcd:insert command instruction. Describe this xvcd:insert command instruction in the command definition. Specify the reference node of insertion point in XPath expression for ref attribute of xvcd:insert command instruction. Specify the reference node of insertion point for position attribute of xvcd:insert command instruction.

Describe XML document fragment to insert for content of xvcd:insert command instruction. In this case, as child element of ab:addressbook element,

<ab:entry>
    <ab:person/>
    <ab:address/>
</ab:entry>

you only need to insert the above, so the command definition to append a new address entry is as follows: In addition, you need to name a command. Here, we call it AddEntry. To invoke a command, specify the command name.

<xvcd:command name="AddEntry">
    <xvcd:insert ref="/ab:addressbook" position="last-child">
        <ab:entry>
            <ab:person/>
            <ab:address/>
        </ab:entry>
    </xvcd:insert>
</xvcd:command>

The defined command cannot be executed so far. You can run the command when it is invoked from the main menu, context menu, tool bar, event, or other command. To specify a command to be invoked by selecting from the main menu, context menu or tool bar, describe the ui:ui element in xvcd:vocabulary element. For more information, see the User Interface Description Reference.

Here, let's create "Entry" menu in the main menu and make it possible to append an address entry in the "Add" sub-menu.

<xvcd:vocabulary name="AddressBook" match="ab:addressbook" call-template="root">
    <ui:ui version="1.0">
        <ui:main-menu>
            <ui:menu label="Entry">
                <ui:menu-item label="add" command="AddEntry"/>
            </ui:menu>
        </ui:main-menu>
    </ui:ui>
<xvcd:vocabulary>

The result of applying these content to AddressBook.xvcd is listed below. The highlighted strings are appended and changed. As the description of mapping to the menu is added, so note that XML namespace declaration xmlns:ui="http://xmlns.xfytec.com/ui" is appended.

<?xml version="1.0"?>
<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns:ui="http://xmlns.xfytec.com/ui"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"
    version="1.0">

    <xvcd:vocabulary match="ab:addressbook" name="AddressBook" call-template="root">
        <ui:ui version="1.0">
            <ui:main-menu>
                <ui:menu label="Entry">
                    <ui:menu-item label="add" command="AddEntry"/>
                </ui:menu>
            </ui:main-menu>
        </ui:ui>
    </xvcd:vocabulary>

    <xvcd:command name="AddEntry">
        <xvcd:insert ref="/ab:addressbook" position="last-child">
            <ab:entry>
                <ab:person/>
                <ab:address/>
            </ab:entry>
        </xvcd:insert>
    </xvcd:command>

    <xvcd:template name="root">
        <html>
            <body>
                <table border="1" width="100%">
                    <tr>
                        <th width="150">
                            Name
                        </th>
                        <th>
                            Address
                        </th>
                    </tr>
                    <xvcd:apply-templates select="ab:entry"/>
                </table>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="ab:entry">
        <tr>
            <td>
                <xvcd:apply-templates select="ab:person"/>
            </td>
            <td>
                <xvcd:apply-templates select="ab:address"/>
            </td>
        </tr>
    </xvcd:template>

    <xvcd:template match="ab:person">
        <xvcd:text-of select="." filler="Enter the name here."/>
    </xvcd:template>

    <xvcd:template match="ab:address">
        <xvcd:text-of select="." filler="Enter the address here."/>
    </xvcd:template>
</xvcd:xvcd>

When editing is complete, save AddressBook.xvcd.

Now let's display it in xfy Basic Edition. Open AddressBook.xml in xfy Basic Edition. The [Entry] is added to the main menu.

Menu item is appended

Run [Entry-Add]. An address book entry is appended at the last row, "Enter the name here."/"Enter the address here." are displayed.

Address entry is appended

4.2.3. Deleting XML Document Fragment from XML Document Data Structure

To delete XML document fragment from data structure of XML document, define the command just like when appending. The command instruction to delete XML document fragment from the data structure of XML document is xvcd:delete command instruction. Describe this xvcd:delete command instruction in the command definition.

Specify the range or node set to delete in XPath expression for select attribute of xvcd:delete command instruction. In the address book, you need to specify address entries to delete. Here, let's delete the entry at the caret. It is possible to get the node at the caret by executing xvcd:caret-node() function. As the caret is at ab:person element or ab:address element, find the ab:entry element from the ancestor of the node at the caret. This is described as xvcd:caret-node()/ancestor-or-self::ab:entry in XPath expression.

Thus, the command definition to delete an address entry at the caret is as follows: Here, we name the command to delete an address entry RemoveEntry.

<xvcd:command name="RemoveEntry">
    <xvcd:delete select="xvcd:caret-node()/ancestor-or-self::ab:entry"/>
</xvcd:command>

Next, we make it possible for user to run the command. Here, create a "remove" menu item in context menu so that an address entry can be deleted when RemoveEntry is invoked.

<ui:ui version="1.0">
   <ui:context-menu>
      <ui:menu-item label="remove" command="RemoveEntry"/>
   </ui:context-menu>
</ui:ui>

The result of applying these content to AddressBook.xvcd is listed below. The highlighted strings are appended.

<?xml version="1.0"?>

<xvcd:xvcd xmlns:xvcd="http://xmlns.xfytec.com/xvcd" 
    xmlns:ui="http://xmlns.xfytec.com/ui"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.xfytec.com/tutorial/addressbook"
    version="1.0">

    <xvcd:vocabulary match="ab:addressbook" name="AddressBook" call-template="root">
        <ui:ui version="1.0">
            <ui:main-menu>
                <ui:menu label="Entry">
                    <ui:menu-item label="add" command="AddEntry"/>
                </ui:menu>
            </ui:main-menu>
            <ui:context-menu>
               <ui:menu-item label="remove" command="RemoveEntry"/>
            </ui:context-menu>
        </ui:ui>
    </xvcd:vocabulary>

    <xvcd:command name="AddEntry">
        <xvcd:insert ref="/ab:addressbook" position="last-child">
            <ab:entry>
                <ab:person/>
                <ab:address/>
            </ab:entry>
        </xvcd:insert>
    </xvcd:command>

    <xvcd:command name="RemoveEntry">
        <xvcd:delete select="xvcd:caret-node()/ancestor-or-self::ab:entry"/>
    </xvcd:command>

    <xvcd:template name="root">
        <html>
            <body>
                <table border="1" width="100%">
                    <tr>
                        <th width="150">
                            Name
                        </th>
                        <th>
                            Address
                        </th>
                    </tr>
                    <xvcd:apply-templates select="ab:entry"/>
                </table>
            </body>
        </html>
    </xvcd:template>

    <xvcd:template match="ab:entry">
        <tr>
            <td>
                <xvcd:apply-templates select="ab:person"/>
            </td>
            <td>
                <xvcd:apply-templates select="ab:address"/>
            </td>
        </tr>
    </xvcd:template>

    <xvcd:template match="ab:person">
        <xvcd:text-of select="." filler="Enter the name here."/>
    </xvcd:template>

    <xvcd:template match="ab:address">
        <xvcd:text-of select="." filler="Enter the address here."/>
    </xvcd:template>
</xvcd:xvcd>

When editing is complete, save AddressBook.xvcd.

Now let's display it in xfy Basic Edition. Open AddressBook.xml in xfy Basic Edition. The screen after opening it remains unchanged. Move the caret to the entry to delete, and right-click on it. "remove" is displayed in the context menu.

"remove" is appended to the context menu

Run "remove". The address entry at the caret is deleted.

Execute address entry's deletion

4.2.4. To Add Function Further

The command allows you to perform many actions besides changing data structure of an XML document. For information, see the following:

4.3. Summary

The lessons learned here is summarized below:

Defining a Command
You can define a command by using xvcd:command element. Describe command content using a command instruction.
Changing Data Structure of an XML Document
You can add an XML document fragment to an XML document by using xvcd:insert command instruction. You can delete an XML document fragment from an XML document by using xvcd:delete command instruction.
Invoking a Command from the Menu
A command defined by xvcd:command element can be invoked from the menu.
Further Functional Enhancement
The command allows you to perform something else.

5. Installing Vocabulary Component

In [Addition and Deletion of XML Document's Data Structure], we described a processing instruction that specifies an XVCD file to associate with an XML document. This can however be accomplished only if you install the xfy Developer's Toolkit. You should also describe processing instructions in all XML documents that you want to process in vocabulary component creation with XVCD. Thus there is a problem whereby an XML document without processing instructions cannot be processed directly.

This chapter explains how to install the vocabulary component created by XVCD in xfy Basic Edition. By installing and using the vocabulary component, you can process XML documents even in an environment in which the xfy Developer's Toolkit was not installed. You can also process XML documents without processing instructions to associate XVCD files

Under ordinary circumstances, to use various component such as vocabulary component in xfy Basic Edition, you need to create a Jar file and install it in the running environment of xfy Basic Edition. A tool to easily create a Jar file of the vocabulary component with XVCD will be provided later.

A way to place XVCD file under scripts folder is provided as a simple way to install the vocabulary component created with XVCD. Here we explain how to place an XVCD file under this scripts folder.

5.1. XML Document Definition

We will explain HelloWorld.xml [Displaying and Editing an XML Document] for example. Delete processing instruction to associate HelloWorld2.xvcd with HelloWorld3.xvcd from HelloWorld.xml and leave processing instruction to associate HelloWorld.xvcd, and then save it as HelloWorld2.xml. The content of HelloWorld2.xml is as follows:

<?xml version="1.0"?>

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.xfytec.com/samples/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

When you open this HelloWorld2.xml in xfy Basic Edition, HelloWorld is shown as vocabulary component as the figure below:

Displaying Vocabulary Component

In this example,

<?com.xfytec vocabulary-connection href="HelloWorld.xvcd"?>

with the processing instruction above, when HelloWorld.xml is loaded, Helloworld.xvcd is associated, and based upon the description of xvcd:vocabulary element in it, vocabulary component is temporarily registered. Now, without describing processing instruction, let's register the vocabulary component.

5.2. Installing Vocabulary Component

The scripts folder is located in the folder where xfy Basic Edition is installed. In this scripts folder, save HelloWorld2.xvcd and HelloWorld3.xvcd created in [Displaying and Editing an XML Document]. Installation of the vocabulary component with XVCD is now complete.

On startup, xfy Basic Edition refers to HelloWorld2.xvcd and HelloWorld3.xvcd and registers vocabulary components based on the description of xvcd:vocabulary element in it.

5.3. Display in xfy Basic Edition

Now display HelloWorld2.xml in xfy Basic Edition. Process an object using the following procedures:

Start xfy Basic Edition.
If xfy Basic Edition is already started, stop and restart it.
Select [File-Open].
Select the folder in which HelloWorld2.xml is saved.
Select HelloWorld2.xml and click [Open].

Are HelloWorld2 and HelloWorld3 shown as vocabulary component as the figure below?

Displaying installed vocabulary component

5.4. Summary

The lessons learned here is summarized below:

XVCD File Association by Processing Instruction
When an XML document is loaded, the XVCD file is associated and the vocabulary component is registered. This manner is only effective when xfy Developer's Toolkit is installed.
Installing in scripts Folder
If the XVCD file is saved under scripts folder, xfy Basic Edition refers to the XVCD file and registers vocabulary component on startup.
Converting to Jar and installing the component
Under ordinary circumastances, to use a component in xfy Basic Edition, you need to create a Jar file and install it in the running environment of xfy Basic Edition.
A tool to easily create a Jar file of the vocabulary component with XVCD will be provided later.