Creating Vocabulary Components with XVCD

This document provides procedures with simple examples to create a vocabulary component using XVCD.

This tutorial teaches you how to operate the following features using XVCD scripts.

1. Content of Tutorial

This tutorial explains the development task of vocabulary component with XVCD, step by step using very simple examples. By working through this tutorial, you can advance your skills in XVCD programming. For knowledge and preparations of the development environment required for working through this tutorial, see "Preparing The XVCD Development Environment."

When working through the tutorial, it is useful to show the Browse Bar in xfy Client. The Browse Bar is not shown immediately following xfy Client installation. To show the Browse Bar, select View - Browse Bar.

Sample Codes

Sample codings in this tutorial are contained doc/samples/developers/tutorial/xvcd_tutorial in xfy Developer's Toolkit  distribution package. Many XVCD samples are provided in xfy Developer's Toolkit in addition to the tutorial. To learn more about XVCD, see these samples.

2. Displaying an XML Document

In the first step, display XML document in xfy Client. This chapter provides you a minimum set to create the vocabulary component running in xfy platform 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. Defining XML Document

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.example.com/developer/tutorial/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 the XML document is created, save it as the file name HelloWorld.xml in an appropriate folder.

2.1.2. Creating Vocabulary Components 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.xfy.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.example.com/developer/tutorial/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 with the file name HelloWorld.xvcd. Save HelloWorld.xvcd in the same folder as HelloWorld.xml.

2.1.3. Associating XVCD Files

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

<?xml version="1.0"?>

<?com.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.example.com/developer/tutorial/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 user agent, you should create an xfy plug-in JAR file and install it in environment of xfy 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 user agent.

However, to check the process of vocabulary component under development, because you must again and again repeat installation and restart xfy 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 user agent. After changing the XVCD file, you do not have to restart the xfy 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 xfy Developer's Toolkit is installed.

2.1.4. Displaying in xfy Client

Now, let's display HelloWorld.xml in xfy Client.

  1. Start xfy Client
  2. Select File - Open
  3. Select HelloWorld.xml and click Open

Is it shown like the following image?

Hello World!
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 Client.

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.xfy.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.example.com/developer/tutorial/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.example.com/developer/tutorial/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 platform 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 can 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.xfy.com/xvcd"            
    xmlns="http://www.w3.org/1999/xhtml"                 
    xmlns:hw="http://xmlns.example.com/developer/tutorial/helloworld" 		
    version="1.0">
    <!--
        xvcd:xvcd  : XVCD apex element
        xmlns:xvcd : XML namespace declaration of XVCD
        xmlns      : XML namespace declaration of XHTML
        xmlns:hw   : XML namespace declaration of the HelloWorld 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
    Apex element of VC core. The namespace URI reference for VC Core is http://xmlns.xfy.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 View - Change Vocabulary Component may increase. For the content of this element, describe vocabulary name, user interface definition such as menu, toolbar.
  • xvcd:template Element
    Describe the mapping from a source XML document targeted for edition to a transformed XML document. It may be nearly the same as an XSLT template element. Essentially, describe the transformed XML document as it is. If necessary, see 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 elements and attributes, see "VC Core Reference: Elements and Attributes."

2.2.3. Process Flow

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

If HelloWorld.xml is opened in xfy Client, xfy platform will process the following:

  1. It refers to the XVCD file associated in processing instruction and temporarily register the vocabulary component defined in the file in xfy platform.
    The description of com.xfy vocabulary-connection processing instruction below registers the vocabulary component described in the HelloWorld.xvcd in xfy platform, allowing you to use it. 
    <?com.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
  2. xfy platform 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 named HelloWorld is applied.
  3. 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 named root is invoked. The root template is a content of xvcd:template element described below: 
    <xvcd:template name="root">
    This template is applied, and transformed XML documents are constructed in sequence.
  4. 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.
  5. 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 transformed XML document. 
    <xvcd:value-of select="."/>

The transformed 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 transformed XML document, xfy platform displays it on the screen using the XHTML vocabulary component.

2.3. Summary

The lesson learned here is summarized below.

  • Target Data
    Describe target data as XML document targeted for edition 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 transformed XML document from the source XML document targeted for edition. XVCD template definition is similar to XSLT.
    Here, the transformed XML document is constructed by XHTML and displayed in xfy Client.

3. Editing String in XML Document

In "Displaying an XML Document", you have now learned how to display "Hello World!" in xfy Client. There is nothing exciting in showing this, because it is also possible with XSLT. This section 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 an XML Document" for example. To edit, the XML document file, like displaying, and XVCD file is required. In "Displaying 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. Defining XVCD

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 characters are changed. 

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfy.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.example.com/developer/tutorial/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 targeted for edition and transformed 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 the evaluation result of this XPath expression 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 characters are changed. 

<?xml version="1.0"?>

<?com.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfy vocabulary-connection href="HelloWorld2.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.example.com/developer/tutorial/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. Displaying in xfy Client

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

Open HelloWorld.xml again
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 an XML Document").

Now let's switch to a component for editing. In order to switch vocabulary components, you can either select Tools - Vocabulary Component Properties and select the vocabulary component in the dialog box shown, or select from View - Change Vocabulary Component. Here, switch it using View - Change Vocabulary Component. By switching it, you can see that the HelloWorld and HelloWorld2 are registered in the View - Change Vocabulary Component. Currently, you should see that "HelloWorld" is selected.

Select Vocabulary Component
Select Vocabulary Component
Switching Vocabulary Components in xfy Client Included in xfy Basic Edition

In the case of xfy Client included in xfy Basic Edition, there is a drop-down list to switch vocabulary components at the top left corner of the Document View Area. By clicking the drop-down list, you can switch the vocabulary component.

Drop-down List for Switching Vocabulary Components
Drop-down List for Switching Vocabulary Components

In the View - Change Vocabulary Component, 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
Vocabulary Component for Editing Is Applied

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

Moved the caret after hello and typed xfy
Moved the caret after Hello and typed xfy

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

Deleted All Characters
Deleted All Characters

"???" is shown. If there is no string referenced by the xvcd:text-of element, xfy platform tells you that "Here is a canvas 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. Defining XVCD

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 characters are changed. 

<?xml version="1.0"?>

<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfy.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:hw="http://xmlns.example.com/developer/tutorial/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.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfy vocabulary-connection href="HelloWorld2.xvcd" ?>
<?com.xfy vocabulary-connection href="HelloWorld3.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.example.com/developer/tutorial/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

3.2.3. Displaying in xfy Client

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

  1. Open HelloWorld.xml in xfy Client.
    If it is already opened, select View - Reload or click Reload in the Browse Bar.
  2. Switch vocabulary component to the HelloWorld3 in the View - Change Vocabulary Component.
  3. Delete all the string "Hello World!".
Effect of filler attribute
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 Client allows you to edit strings. It is of no use if edited data cannot 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:

  1. Open HelloWorld.xml on xfy Client.
  2. Switch vocabulary component to the HelloWorld3 in the View - Change Vocabulary Component.
  3. Edit the string "Hello World!" appropriately.
  4. Select File - Save to save edited XML document.
Saving 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.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
<?com.xfy vocabulary-connection href="HelloWorld2.xvcd" ?>
<?com.xfy vocabulary-connection href="HelloWorld3.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.example.com/developer/tutorial/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 lesson learned here is summarized below.

  • Replacing the XML document referred to by the xvcd:value-of element with the xvcd:text-of element makes a string editable. (Note: some select attribute's content may not be replaced. For more information, see the explanation about the select attribute of the xvcd:text-of element in "VC Core Reference: Elements and Attributes.")
    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 the drop-down list.

4. Adding and Deleting Data Structure to XML Documents

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. Defining XML Data

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.example.com/developer/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 string in ab:person element means person's name.
  • The string in ab:address element means an address.

To make data structure definition clear, the DTD for reference is listed below. You do not have to create a DTD file because xfy technology does not perform validation using DTD.

<!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.xfy vocabulary-connection href="AddressBook.xvcd" ?>
<ab:addressbook xmlns:ab="http://xmlns.example.com/developer/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. Defining XVCD

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.xfy.com/xvcd" 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.example.com/developer/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 Client, the transformed 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. Displaying in xfy Client

Now, display the created address book in xfy Client. Open AddressBook.xml in xfy Client. Is it shown like the following image?

Table view
Table view

Although the XVCD 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. Adding and Deleting 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 XVCD 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 is appended. The highlighted characters indicate added structures. 

<?xml version="1.0"?>

<?com.xfy vocabulary-connection href="AddressBook.xvcd" ?>
<ab:addressbook xmlns:ab="http://xmlns.example.com/developer/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. Specifies the reference node of insertion point in XPath expression for ref attribute of xvcd:insert command instruction. Specifies 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, insert the following XML document fragment as a child element for the 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, toolbar, event, or other command. To specify a command to be invoked by selecting from the main menu, context menu or toolbar, describe the ui:ui element in xvcd:vocabulary element. For more information, see "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 characters are appended and changed. As the description of mapping to the menu is added, so note that XML namespace declaration xmlns:ui="http://xmlns.xfy.com/ui" is appended. 

<?xml version="1.0"?>
<xvcd:xvcd
    xmlns:xvcd="http://xmlns.xfy.com/xvcd" 
    xmlns:ui="http://xmlns.xfy.com/ui"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.example.com/developer/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 Client. Open AddressBook.xml in xfy Client. The Entry is added to the main menu.

Menu item is appended
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
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.

Specifies 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 characters are changed. 

<?xml version="1.0"?>

<xvcd:xvcd xmlns:xvcd="http://xmlns.xfy.com/xvcd" 
    xmlns:ui="http://xmlns.xfy.com/ui"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ab="http://xmlns.example.com/developer/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 Client. Open AddressBook.xml in xfy Client. The screen after opening it remains unchanged. Move the caret to the entry to delete, and right-click it. remove is displayed in the context menu.

remove is appended to 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
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 lesson 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 "Adding and Deleting Data Structure to XML Documents", 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 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 platform. By installing and using the vocabulary component, you can process XML documents even in an environment in which xfy Developer's Toolkit was not installed. You can also process XML documents without processing instructions to associate XVCD files.

To use various components such as vocabulary component in xfy platform, basically you need to create an xfy plug-in JAR file and install it in the runtime environment of xfy platform. The "xfy Plug-in Archiver" is provided to easily make the xfy plug-in JAR file from the vocabulary component created using XVCD.

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. Defining XML Document

We will explain HelloWorld.xml "Displaying 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.xfy vocabulary-connection href="HelloWorld.xvcd" ?>
<hw:document xmlns:hw="http://xmlns.example.com/developer/tutorial/helloworld">
    <hw:message>
        Hello World!
    </hw:message> 
</hw:document>

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

Displaying Vocabulary Component
Displaying Vocabulary Component

In this example,

<?com.xfy 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 Client is installed. In this scripts folder, save HelloWorld2.xvcd and HelloWorld3.xvcd created in "Displaying an XML Document." Installation of the vocabulary component with XVCD is now complete.

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

5.3. Displaying in xfy Client

Now display HelloWorld2.xml in xfy Client. Follow these steps.

  1. Start xfy Client.
    If xfy Client is already started, stop and restart it.
  2. , select File - Open.
  3. Select the folder in which HelloWorld2.xml is saved.
  4. Select HelloWorld2.xml and click Open.

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

Displaying installed vocabulary component
Displaying installed vocabulary component

5.4. Creating xfy Plug-in JAR File

As explained at the beginning of this chapter, to use various components such as vocabulary component in xfy platform, basically you need to create an xfy plug-in JAR file and install it in the runtime environment of xfy platform. When actually creating a vocabulary component in XVCD, it is recommended that you check the operation in XVCD file until the vocabulary component is completed, then create an xfy plug-in JAR file after completion of the vocabulary component.

To create an xfy plug-in JAR file from a vocabulary component created with XVCD, use xfy Plug-in Archiver. The steps to create xfy plug-in JAR file from XVCD using xfy Plug-in Archiver are described in "Creating an xfy Plug-in Using xfy Plug-in Archiver."

5.5. Summary

The lesson 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 platform refers to the XVCD file and registers vocabulary component on startup.
  • Archiving to xfy plug-in JAR file and installing the component
    To use a component in xfy platform, basically you need to create an xfy plug-in JAR file and install it in the runtime environment of xfy platform.
    The "xfy Plug-in Archiver" is provided to easily make the xfy plug-in JAR file from the vocabulary component created using XVCD.

Appendix A. Function List

The elements, functions, and command instructions used in this tutorial and their occurrences are listed below.

VC Core

xvcd:xvcd Element
2.2.2. Details of HelloWorld.xvcd
xvcd:vocabulary Element
2.2.2. Details of HelloWorld.xvcd
2.2.3. Process Flow
xvcd:template Element
2.2.2. Details of HelloWorld.xvcd
2.2.3. Process Flow
xvcd:apply-templates Element
2.2.3. Process Flow
xvcd:value-of Element
2.2.3. Process Flow
3.1.1. Defining XVCD
xvcd:text-of Element
3.1.1. Defining XVCD
3.2.1. Defining XVCD
xvcd:command Element
4.2.2. Adding XML Document Fragment to XML Document Data Structure
xvcd:delete Instruction
4.2.3. Deleting XML Document Fragment from XML Document Data Structure
xvcd:insert Instruction
4.2.2. Adding XML Document Fragment to XML Document Data Structure
xvcd:caret-node Function
4.2.3. Deleting XML Document Fragment from XML Document Data Structure

User Interface Description

ui:ui Element
4.2.2. Adding XML Document Fragment to XML Document Data Structure
ui:main-menu Element
4.2.2. Adding XML Document Fragment to XML Document Data Structure
ui:context-menu Element
4.2.3. Deleting XML Document Fragment from XML Document Data Structure
ui:menu Element
4.2.2. Adding XML Document Fragment to XML Document Data Structure
ui:menu-item Element
4.2.2. Adding XML Document Fragment to XML Document Data Structure
(C)2006 JustSystems Corporation