Introduction

The IBM WebSphere Studio Application Developer is an application development product that supports the building of a large spectrum of applications using different technologies, such as JSPs^TM, servlets, HTML, XML, Web services, databases, and EJBs^TM.

This is Part 4 of a series of articles focusing on the XML tools provided with WebSphere Studio Application Developer. Part 4 explores the XML Editor, a visual tool for creating and editing XML documents. By guiding you through a simple tutorial, I will demonstrate some of the useful features that the XML Editor provides to make XML document editing easier and more productive.

We recommend that you read the other articles in this series:

• Part 1 Learn how to use Application Developer to develop XML Schema.
• Part 2 Learn how to create an SQL query using Application Developer's SQL Builder.
• Part 3 Learn about the Application Developer features available to incorporate data access and XML in your application.
• Part 4 Learn how to use the XML Editor, a visual tool for creating and editing XML documents.
• Part 5 Learn how to use the RDB to XML Mapping Editor to create DAD files for use with DB2 XML Extender.
• Part 6 Learn how to use the XML Schema Editor and the XML Editor together to develop XML applications that make use of XML namespaces.

Back to top

Getting started

Before we get started with the XML Editor tutorial, we'll need to create a project in Application Developer and then import some example files.

First, download the xml-tutorial.zip file provided below, and unzip it into a temporary folder, for example, C:\temp\tutorial.

Next, launch Application Developer and follow these steps to create a project.

1. Select Perspective => Open => Other => XML to switch to the XML perspective.
2. Select File => New => Project => Simple => Project to bring up the New Project wizard to create a simple project, for example, XMLProject.
3. In the project name field, enter XMLProject.
4. Click Finish.

Now, follow the steps below to import the example files into the project.

1. Select File => Import.
2. Select File System as the import source. Click Next.
3. Click Browse to locate the temporary folder where you unzipped xml-tutorial.zip.
4. Click Select All, and then click Finish.

Back to top

Creating an XML document

To edit an XML document, we first have to create one. There are two ways to go about doing this. First, the obvious way, you can create a blank XML document from scratch. The second, and more interesting way, is to generate a skeleton XML document for a given DTD or XML Schema. We'll use the file University.xsd to demonstrate how to generate a skeleton XML document from an XML Schema.

1. Locate the University.xsd file in the Navigator view.
2. Right-click on the file's icon to invoke the context menu.
3. Select Generate => XML File to bring up the New XML File wizard.
4. Click Next to accept the default file name, University.xml.
5. Ensure that the university element is selected in the Root element combo box.
6. Click Finish. The University.xml file is created and the XML Editor is automatically opened for you.
7. Click Validate on the tool bar to see if the generated file is valid.

Back to top

Editing an XML document

The XML Editor has four main views: Source View, Design View, Outline View, and Task View. The Source View is a text editor that lets the user directly edit the source of the XML document. The Design View displays the XML document as a tree enabling the user to manipulate the document by adding, removing, and editing tree nodes. The Outline View provides an overview of the XML document that can be useful when navigating large documents. The Task View displays error messages that may be associated with the XML document.

Note the editor's page tabs at the bottom of the top right pane . These tabs are used to switch between the Design View and the Source View of the XML Editor. The views are synchronized so that a change made in one view will be automatically reflected in the other view.

Back to top

Guided editing

The XML Editor will make use of any grammar rules associated with an XML document to provide smart editing features. These grammar-aware editing features are collectively named as guided editing. Currently, the XML Editor supports DTD or XML Schema to provide guided editing. It is important to note that although this tutorial makes use of XML Schemas, the XML Editor will work just as well with DTDs.

We will demonstrate some of the guided editing features below.

Editing with the Source View

Click on the Source tab to see the Source View. As well as providing the typical features of a text editor, the Source View provides XML-specific features such as content assist. When editing an XML document, content assist can be invoked to prompt the user with a list of possible elements or attributes. This is one example of how the XML Editor makes use of grammar rules to provide guided editing.

1. From the Source View, position the cursor after the name element.
2. Press Ctrl and space to invoke content assist. Notice that the list of available elements corresponds to the content model for the university element as specified in the schema. See Listing 1 below.
3. Select student from the list.
4. Position the cursor within the start tag of the student element just before the character.
5. Type a space, and then press Ctrl and space to invoke content assist. Notice that the list of available attributes corresponds to the content model for the student element as specified in the schema. See Figure 3 below.
6. Select the id attribute from the list.
7. Position the cursor between the start and end tag of the student element.
8. Press Ctrl and space to invoke content assist. Notice that the list of available elements corresponds to the content model for the student element as specified in the schema. See Listing 2 below.
9. Select the name element from the list.
   

The source should now look like Figure 4 below.

Listing 1. The schema's type definition for the university element

<complexType name="University">  
 
   <sequence>  
 
      <element name="name" type="string"></element>  
 
      <element name="student" type="University:Student"  
 
         minOccurs="0" maxOccurs="unbounded"></element>  
 
      <element name="misc" type="University:Misc"></element>  
 
   </sequence>

Listing 2. The schema's type definition for the student element.

<complexType name="Student">  
 
   <sequence>  
 
      <element name="name" type="string"></element>  
 
      <element name="faculty" type="University:Faculties"  
 
         minOccurs="0"></element>  
 
      <element name="major" type="string" minOccurs="0"></element>  
 
      <element name="minor" type="string" minOccurs="0"></element>  
 
   </sequence>  
 
   <attribute name="id" type="string" use="optional"  
 
      default="00000"></attribute>  
 
   <attribute name="type" type="University:StudentType"></attribute>  
 
</complexType>

Editing with the Design View

Click on the Design tab to see the Design View. The Design View presents the user with a tabular tree view of the XML document. The view is divided into two columns. In the left column, we see the elements, attributes, and other nodes of the XML document's tree. The right column is used to display the values associated with these nodes, for example, the value 00000 of the id attribute. The right column is also used to display content model information (in green text) associated with elements.

Adding and editing attributes

1. Left-click in the right column next to the id attribute.
2. Type the value 12345 into the cell and press Enter.
3. Right-click on the student element and select Add Attribute=> type.
4. Left-click in the right column next to the type attribute.
5. Notice the drop down control that appears at the right of the cell .
6. Click the drop down control. Note the list of values corresponds to the enumerated values specified in the type element's schema definition. See Figure 5 below.
7. Select part-time from the drop down list.

Listing 3. The schema's type definition for the student element's type attribute

<simpleType name="StudentType">  
 
   <restriction base="string">  
 
      <enumeration value="full-time"></enumeration>  
 
      <enumeration value="part-time"></enumeration>  
 
   </restriction>  
 
</simpleType>

Adding elements

If we right-click on an element in the tree, a context menu will appear with several editing options. See Figure 3 below. Depending on the state of the XML document and the associated grammar, different options will become available in the context menus. This is another example of how the XML Editor makes use of grammar rules to provided guided editing.

1. Right-click on the student element.
2. Select Add Child. Note that the available elements in the list are: faculty, major, and minor.
3. Select the major element.
4. Select Add Child.
5. Note the available elements in the list are: faculty and minor.
6. Select the faculty element.

Notice, in the exercise above, that the XML Editor considers the current content of an element as well as its grammar rules (defined in University.xsd) to produce a list of guided editing options. Here, the Design View only displays those options that will maintain the validity of the XML document. For example, in step 3 above, the elements faculty, major, and minor were available. After adding the major element, we notice in step 6 that major is no longer displayed as an available child element. This is because the grammar specifies that the student element can have at most one major element.

Also, notice that the XML Editor automatically inserted the child elements into the proper positions. In this case, the faculty element was inserted before the major element. The Add Before and Add After menu options are available in the case where there are multiple positions that an element may be legally inserted.

Removing an element

1. Right-click on the student's major element.
2. Select Remove from the pop-up menu.

As we stated above, the Design View only provides editing options that will maintain the validity of the XML document. We'll demonstrate this below by attempting to remove an element that is required by the grammar.

1. Right-click on the student's name element.
2. Note that the Remove item is not available in the pop-up menu.

In this case, the grammar rules specify that the name element must appear at least once as the first child element of the student element. Hence, the option to remove the name element is not made available.

Editing modes

In the examples above, we demonstrated how the Design View only presents editing options that will maintain the validity of the XML document. In other words, the Design View constrains the editing options according to the grammar rules. In most cases this is a useful feature, but there are times when a user may require more flexibility. The XML Editor provides this flexibility by allowing the grammar constraints to be turned on or off at any time.

Up until this point, we have used the Design View with grammar constraints turned on (by default). Now we will demonstrate how the Design View's guided editing behaves when the grammar constraints are turned off.

1. Click the Turn grammar constraints off button on the toolbar . Now, grammar constraints are turned off in the Design View.
2. Right-click on the student's name element.
3. Select Remove from the pop-up menu.
4. Note that an error hint has been added to the student element .
5. Now, the Design View should appear, as shown in Figure 4 below.

Note that although the name element is required, the Remove action is still made available. With grammar constraints turned off, we have been allowed to edit our document so that it is now invalid.

Back to top

Error hints and validation

When we removed the name element, a yellow indicator appeared next to the student element icon. This indicator is an error hint. The XML Editor automatically detects many errors and provides yellow hint indicators where appropriate. Often, the user will recognize the error immediately and know exactly how to fix it. In this case, the error hint indicates the student element has invalid content since it is missing the required name element. Now, let's correct that error.

1. Right-click on the faculty element
2. Select Add Before => name.
3. Press the Validate button on the toolbar.
4. Notice that the hint indicator has gone away.

To get a complete list of errors and descriptive error messages, we'll need to validate the entire XML document as follows.

1. Right-click the name element.
2. Select Remove to reintroduce an error.
3. Press the Validate button on the toolbar .
4. Click OK to dismiss the message dialog.
5. Look at the errors in the task list.
6. Notice the red indicator beside the student element in the Design View .

The red indicators represent an actual error (as opposed to a hint) with an associated messages in the Task List. Now, we can fix the error and revalidate.

1. Right-click the faculty element.
2. Select Add Before => name.
3. Press the Validate toolbar button.
4. Note that the task list is now empty, and the error indicator is gone.

Back to top

Editing schema information

The XML Editor provides a convenient feature for editing the namespace and schema information that is associated with an XML Schema instance. This is often useful when editing schema information or adding new namespaces and schema.

If we turn to the Design View and examine the misc element, we notice that the element's content model description is displayed in green. See Figure 5 below. This is a concise way of displaying the content model that is specified by the Misc type in the schema. See Listing 4 below.

Listing 4. The content model definition in the schema (University.xsd)

<complexType name="Misc">  
 
   <sequence>  
 
      <element name="LastUpdated" type="date" minOccurs="0"></element>  
 
      <any namespace="##any" minOccurs="0" maxOccurs="unbounded"></any>  
 
   </sequence>  
 
</complexType>

The content model specifies that the misc element contains an optional LastUpdated element followed by zero or more "wild card" elements that can come from any schema. To add elements from another schema, the XML author must first add a namespace declaration with the proper namespace name and provide a schemaLocation. Typing this information manually can be painstaking and error prone. By using the Design View's editing dialog, we can perform this task with just a few clicks!

1. Right-click the University:university element.
2. Select Edit Schema Information.
3. Click the New button.
4. Click Browse to locate a schema that will be associated with this namespace.
5. Select the file Misc.xsd from the Select File view and click OK.
6. Note that the URI and Prefix fields are automatically filled in based on the information in XML Schema file (Misc.xsd).

Notice that the XML document's source has been changed from this:

<University:university 
 
   xmlns:University="http://www.university.ibm.com" 
 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 
   xsi:schemaLocation="http://www.university.ibm.com University.xsd">

to this, with the additions in blue:

<University:university 
 
   xmlns:University="http://www.university.ibm.com" 
 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 
   <font color="0033ff">xmlns:Misc="http://www.misc.university.com" 
 
   xsi:schemaLocation="http://www.university.ibm.com 
 
   University.xsd <font color="0033ff">http://www.misc.university.com Misc.xsd"

Now, to make use of the new XML Schema via the Design View.

1. Right-click the misc element to invoke the context menu.
2. Select Add Child => Misc:Grant.
3. Notice that the elements defined in Misc.xsd are now available to be added to the document.

Back to top

Using the XML Catalog

What is an XML Catalog? The easiest way to describe an XML Catalog is to illustrate the problem that it is designed to solve.

The problem

Let's suppose that I am developing an XML document that will eventually be published on the Web. I'm at work on my PC editing an XML document that looks like this:

<?xml version="1.0" encoding="UTF-8"?>     
 
   <VendingMachine:vendingMachine     
 
      xmlns:VendingMachine="http://www.vending-machine.ibm.com"     
 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     
 
      xsi:schemaLocation="http://www.vending-machine.ibm.com     
 
     <font color="0033ff">"file:///C:/project/sharedSchemas/vending-machine.xsd">     
 
      .  
 
      .  
 
      .  
 
   </VendingMachine:vendingMachine>

When I've finished work for the day, I save this file on to my laptop, so that I can work on it later at home. After dinner, I open up my laptop to begin work again. There's a problem! The XML Editor cannot find the vending-machine schema. After a quick glance, I notice that my the schemaLocation refers to the system id "file:///C:/project/sharedSchemas/vending-machine.xsd". Currently, my project is installed on my D: drive. Now I need to edit the schema location so that it looks like this:

xsi:schemaLocation="http://www.vending-machine.ibm.com 
 
   <font color="0033ff">"file:///D:/project/sharedSchemas/vending-machine.xsd">

A few minutes later, I've finished editing the XML file and it's time to publish it on the Web. Now, I need to edit the URI again so that it points to a resource that's accessible on the Web. The schemaLocation must be updated to look like this:

xsi:schemaLocation="http://www.vending-machine.ibm.com 
 
   <font color="0033ff">"http://www.ibm.com/published-schemas/vending-machine.xsd">

But wait, I'm not finished yet. On the train ride to work, I'm reviewing my XML document on my laptop, and I notice a serious error! Unfortunately, I'm not connected to the Internet, so now I need to change the URI back to point to my local copy. When I arrive at work, before I can republish the corrected version, I'll need to remember to update the document to use the Web-accessible URI.

By now, the problem should be obvious. A URI used within an XML file is not as portable as we would like it to be. To avoid making frequent changes to our XML document, we can make use of the XML Catalog.

The solution

An XML Catalog is used by an XML processor when resolving entity references. The developer can provide rules to the catalog to specify how entities should be resolved. If we consider the example above, the developer could specify a rule that redirects an Internet resource reference (for example, "http://www.ibm.com/published-schemas/vending-machine.xsd") so that it points to a resource on the developer's local machine (for example, "file:///C:/project/sharedSchemas/vending-machine.xsd"). Now, instead of frequently editing XML documents to update the URIs (especially when there may be many documents in our project), we only need to update a single rule in our XML Catalog.

Catalogs in action

Now, let's explore the XML Catalog support provided in Application Developer.

Locate and open the vending-machine.xml file n the XML Editor. Notice that the document specifies a schemaLocation with the URI "http://www.ibm.com/published-schemas/vending-machine.xsd". Since we are still in the development phase, we haven't yet published a schema on our Web server so the URI above isn't very useful to our XML Editor. It's obvious that the XML Editor cannot locate the schema.

Click Validate and notice the File not found error in the task list.

Instead of editing the URI to point to our local copy (which we know is problematic), let's make use of the XML Catalog. Follow the steps below to add a new XML Catalog Entry to the XML Catalog.

1. Select Window => Preferences to invoke the Preferences dialog.
2. Click the Change button next to the Project to use to persist XML Catalog User Entries and select a project (for example, XMLProject).
3. In the User Specified Entries section, click New to create a new XML Catalog Entry.
4. Click Browse and locate the vending-machine.xsd file in your project.
5. Click on the Key Type field and select the value Schema Location.
6. Enter the value http://www.ibm.com/published-schemas/vending-machine.xsd into the Key field. Now, the dialog should look like Figure 6 below.
7. Click OK to close the New XML Catalog Entry dialog. Now, the XML Catalog page should look like Figure 7 below.
8. Click OK to save your updated XML Catalog preferences.

Now, we have added an entry to the XML Catalog so that a schema location that references the URI "http://www.ibm.com/published-schemas/vending-machine.xsd" will be resolved so that our local copy of vending-machine.xsd is used instead. Let's go back to editing the vending-machine.xml file. Perform the steps below and notice how the XML Editor makes use of the XML Catalog to correctly resolve the schema.

1. View the vending-machine.xml file in the XML Editor.
2. Turn to the Design View page.
3. Click the Reload Dependencies button so that the schema is reloaded using the catalog settings.
4. Notice that the green content model descriptions appear in the right column of the Design View.
5. Click Validate. The file should validate without errors!

Back to top

Summary

This article provides a brief overview of the XML Editor that is included in WebSphere Studio Application Developer. In future articles, we hope to cover some advanced topics such as:

• Generating XML documents from complex XML Schemas.
• Support for XML Schema local element qualification rules.
• Support for XML Schema "any elements."
• In-depth explanation of XML Catalogs.

Please let us know what you think.

Top of page

Back to top

Download

Name	Size	Download method
xml-tutorial.zip	298KB	FTP|HTTP

Information about download methods

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Getting started
• Creating an XML document
• Editing an XML document
• Guided editing
• Error hints and validation
• Editing schema information
• Using the XML Catalog
• Summary
• Download
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
• Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers