Tools Guide
|
|
Tools Guide |
This chapter describes the facilities that Workbench provides to work with XML and XML-related files. It contains the following topics:
XML (Extensible Markup Language) is a language designed to facilitate the exchange of data between computer systems (which can be of different types) and applications on the Web. XML is a project of the World Wide Web Consortium (W3C). It is a standard, public format.
Unlike HTML, XML is extensible. It is a metalanguage, a language that describes other languages. With XML, you can define customized markup languages to describe any type of document structure. XML can be used to specify the structure of anything from a recipe (which might consist of descriptions, ingredients, preparation steps, and so on) to a Web application (WAR deployment descriptors are XML documents).
The definition of an XML document is specified by either a Document Type Definition (DTD) or a Schema. DTDs, which are older, specify the structure of an XML document. They specify the names of elements, attributes, and entities that can exist in a conforming XML document. DTDs also specify where the elements can be used, whether they are required, and so on.
Schemas are more recent and more powerful. They can specify the structure as well as the content (data types) allowed in XML documents. Unlike DTDs, Schemas are themselves XML documents.
The complete XML standard can be found at http://www.w3.org/XML.
TIP If you are new to XML, you might want to read the XML FAQ at http://www.ucc.ie/xml. Among other topics, it describes the differences between Schemas and DTDs.
Workbench provides comprehensive support for working with XML files, including:
This chapter describes these XML facilities.
View and edit XML documents in a syntax-colored Source View or a Tree View
Easily create and modify document elements through the editor's context-based code completion and the Schema Guide window
The Source View provides you with a powerful XML source editor. In addition to standard text editing features—including cut-and-paste editing, undo and redo, and searching and replacing text—it supports these specialized features for editing XML files:
Context-sensitive code completion (see Editing an XML document)
Formatting of XML elements (see Modifying text and Changing indentation)
Navigating by XML elements (see Moving the insertion point)
Finding matching tags (see Moving the insertion point)
Bookmarks (see Bookmarks)
Specifying colors to display different types of information (see "XML Editor color preferences" on page 24)
The XML Editor displays the current XML document in the Source View if you click the XML Source View tab.
The Tree View has special features designed to help you create valid XML documents quickly and easily based on XML Schemas or DTDs. The Tree View supports:
Context-sensitive editing (see Editing an XML document)
Cut-and-paste editing (see Editing objects)
Drag and drop (see Editing objects)
Searching by name, value, or XPath (see Searching an XML document)
Finding matching elements (see Navigation and display)
The XML Editor displays the current XML document in the Tree View if you click the XML Tree View tab.
NOTE The Tree View does not show or manipulate XML comments.
|
Icon |
Description |
|---|---|
Text value of an element (for example, the text value of <myTag>the text</myTag> is the text) | |
You can create new XML documents or work with existing ones.
To create a blank XML document, deselect Use Wizard and click OK. An empty XML document is created and displayed in the XML Editor.
To use the XML Wizard, select Use Wizard and click OK. The XML Wizard displays. Go through the wizard as follows.
Specify the name and location of the XML file and click Next.
Specify a Schema or DTD to associate with the XML file. You can:
Select a Schema URI from the list of Schemas in the Workbench catalog; the corresponding file name is displayed in the File Name field
Select a public or system identifier from the list of DTDs in the Workbench catalog; the corresponding file name is displayed in the File Name field
Select a Schema or DTD directly from the file system by clicking Browse and selecting the file
For more information about the Workbench catalog, see
Maintaining the XML catalog.
The XML Editor displays the Schema Guide.
You can use the Schema Guide, or click Close to edit the file manually.
For information about the Schema Guide, see
Using the Schema Guide.
In the Open dialog, select the XML file and click Open.
The file extension must be .XML, .XSD (for a Schema file), or .TLD (for a tag library descriptor file).
The file opens in the XML Editor. If you opened an .XML or .TLD file, there is a new XML Editor item on the menu bar.
NOTE An XML file might instead be opened by a specialized XML editor, such as the XML Catalog Editor or Deployment Descriptor Editor.
Finding Schemas and DTDs If the XML document specifies a Schema or DTD, Workbench searches for it when opening the document. If Workbench finds the Schema or DTD, it attaches it to the XML document. If the reference is unqualified, Workbench first looks in its XML catalog; if Workbench doesn't find the Schema or DTD there, it looks in the directory containing the XML document.
If the XML Editor cannot find the referenced Schema or DTD, you receive an error message in the Output Pane and the document is opened without being attached to the Schema or a DTD.
For more information, see
Associating Schemas and DTDs with XML documents.
The window title for an XML document specifies whether the document is attached to a Schema or DTD.
In order to use context-sensitive code completion and to validate your document, an XML Schema (.XSD file) or a DTD (.DTD file) must be attached to the document.
If Workbench didn't attach a Schema or DTD when opening an XML document, you can manually attach a Schema or DTD or modify your XML document to specify a Schema or DTD and refresh Workbench.
You can attach a Schema or DTD that is in the Workbench XML catalog or elsewhere on the file system to an open XML document.
For more information about the Workbench XML catalog, see
Maintaining the XML catalog.
To attach a Schema or DTD to an XML document:
Select XML Editor>Attach Schema or DTD.
Specify a Schema or DTD to associate with the XML document. You can:
Select a Schema URI from the list of Schemas in the Workbench catalog; the corresponding file name is displayed in the File Name field
Select a public or system identifier from the list of DTDs in the Workbench catalog; the corresponding file name is displayed in the File Name field
Select a Schema or DTD directly from the file system by clicking Browse and selecting the file
The Schema or DTD is now attached to your XML document. You can use the XML Editor's context support for editing, and you can validate your document.
NOTE Attaching a Schema or DTD to an XML document is only for the purpose of context editing and validation in the XML Editor; it doesn't modify the XML document itself. See the next section for permanently associating a Schema or DTD with the document.
Errors Any errors that occur when attaching a Schema or DTD are reported in the Messages tab of the Output Pane.
After opening an XML document, you might want to permanently associate the document with a Schema or DTD and make Workbench aware of the association.
To associate the document with a Schema or DTD and update Workbench:
Edit the open XML document to specify the associated Schema or DTD. For example, to associate the document with a DTD, edit its DOCTYPE statement.
Update Workbench to use the association by selecting XML Editor>Refresh Schema Handler.
Workbench parses the XML document and updates the DTD or Schema information associated with the document.
Errors Any errors that occur when updating the Schema or DTD information are reported in the Messages tab of the Output Pane.
You can detach a Schema or DTD from an open XML document.
Select XML Editor>Detach Schema or DTD.
The Schema or DTD definition is no longer used by the XML Editor. Context editing and validation are no longer provided for the open document.
The Schema or DTD is not permanently detached. The next time you open the XML document, if the document specifies a Schema or DTD that Workbench can find, the Schema or DTD will be attached again.
Schemas are more powerful than DTDs and are becoming the standard for defining the structure and allowable content type for XML documents. Also, unlike DTDs, Schemas are themselves XML documents and can be edited and validated in the XML Editor.
If you have been using DTDs, you can use Workbench to convert a DTD to a Schema. You can:
To convert a DTD on the file system to a Schema:
Specify the DTD to convert. You can click the ellipses button to browse the file system for the DTD file. The file must have the extension .DTD.
Specify the name of the Schema file to generate. Don't provide a file extension; the file will be given the extension .XSD.
Specify the location to save the Schema file. You can click the ellipses button to browse the file system.
Specify whether you want the Schema opened in the XML Editor after it is created.
Workbench converts the DTD to a Schema, stores the Schema in the specified location, and displays the Schema in the XML Editor if you specified to open it.
To convert a DTD attached to an open document to a Schema:
Select XML Editor>Convert DTD to Schema.
A file save dialog displays.
Specify the name and location of the Schema. Don't provide a file extension; the file will be given the extension .XSD.
The Schema is saved.
What to do next You can edit the generated Schema file in the XML Editor and attach it to an XML document for context editing and validation. If you want to permanently associate the Schema with an XML document, edit the XML document to specify the Schema.
You can edit an XML document using either Tree View or Source View. If you have attached a Schema or DTD, you can use the XML Editor's context support.
Workbench provides context editing in both the Tree View and the Source View.
In Tree View, right-click at the appropriate location in the document. In the following illustration, a new person is being added to the document, and the XML Editor detects from the Schema that the next valid element is name.
Once the name has been added, the XML Editor presents the new list of valid elements, according to the Schema.
Similarly, the editor presents valid attributes when you have an element selected.
Notice that the editor also provides the choice Other, allowing you to define an entry that does not conform to the Schema. If you choose Other, you see a dialog similar to the following:
Using the Schema Guide In addition to using the context menu to edit your XML document, you can use the Schema Guide for more comprehensive context support. See Using the Schema Guide.
In Source View, after you type < (to start an element tag) or a single space within an element (to define an attribute), the editor displays the valid entries (if there are any). For example:
Here a space has been typed in the url element, which results in a display of the valid attribute, href:
To add an element in Tree View:
Right-click and select Insert New Element to insert an element inside the current element, or select Insert New Element Before to insert an element before the current element at the same level.
If valid elements can be inferred from the definition of the document, they will be listed.
If no element can be inferred, you can add an element by choosing Other. You are warned that the new element might not be valid.
To add an element in Source View:
Position the insertion point where you want to insert the element.
If valid elements can be inferred from the definition of the document, they will be listed.
If no element can be inferred, you can add an element by typing it.
To add an attribute in Tree View:
Right-click and select Insert New Attribute.
If valid attributes can be inferred from the definition of the document, they will be listed.
If no attribute can be inferred, you can add an attribute by choosing Other. You are warned that the new attribute might not be valid.
To add an attribute in Source View:
Position the insertion point inside an element where you want to insert the attribute.
If valid attributes can be inferred from the definition of the document, they will be listed.
If no attribute can be inferred, you can add an attribute definition by typing it.
To add a namespace declaration in Tree View:
Right-click and select Insert New Namespace Declaration.
The Insert Namespace Declaration dialog displays.
Specify the prefix, URL, and Schema location for the namespace.
To add a namespace declaration in Source View:
To copy, move, or delete objects in Tree View:
You can use drag-and-drop to move objects, or use the right-mouse-button menu to perform the following actions:
Cut or Copy to place an object on the clipboard, then Paste to insert it before a selected object or Paste As Child to insert it as the last child of a selected object
TIP Cut and Copy also place contents on the system clipboard, so you can paste a textual representation of the tree contents into other applications. Similarly, you can paste textual XML contents from other applications into Tree View.
Delete Namespace Declaration to delete a namespace declaration
In all cases, you will be informed if the edit would result in an invalid document. You can choose whether to continue.
To copy, move, or delete objects in Source View:
Reversing changes All editing actions can be undone by selecting Edit>Undo or pressing Ctrl+Z, or redone by selecting Edit>Redo or pressing Ctrl+Y.
The context editing functionality described above is very useful when editing XML documents, but doesn't always provide all the information you might want. For example:
It doesn't show exactly how a Schema (or DTD) is put together and what elements and attributes are allowable at different locations.
It doesn't indicate whether an element must include a sequence of child elements before it is legal. For example, say element A must have elements B, C, and D as children to be valid. When you insert an instance of A, the standard context support described above suggests element B as a valid subelement. If B is inserted alone the document becomes invalid until you have inserted C and D. With the standard context support, you wouldn't know this unless you perform a full validation of the document.
If you are looking for a specific element to insert, for instance D in the example above, with the standard context support you wouldn't be informed about D unless you have inserted B and C first.
If an element contains illegal children, the standard context support doesn't suggest new elements to insert, so you must perform a full validation to find out where the problem is and then correct it.
The Schema Guide addresses these situations.
The Schema Guide opens in a new window.
The Schema Guide window consists of four parts:
The top of the window displays the XPath for the selected element, its namespace, documentation for the element's type (if any, taken from comments in the DTD or annotation elements in the Schema), and a textual DTD-like description of the element's allowed contents
For more information about XPaths, see
XPaths.
The left side contains a graphical representation of the definition of the selected element
The right side contains a tree representation of the actual instance of the selected element, including its attributes and children (but not its children's children)
In the screen shown above, the second person element (/personnel/person[2]) was selected when the Schema Guide was invoked.
The left pane shows the element's subelements as well as the Schema model groups they belong to (Choice, Sequence, or All) or the model group declarations (for example, schemaTop).
Choice groups are shown with two elements on each row, with a horizontal bracket above and below
Sequence groups are shown with one element in each row and a vertical bracket on the left and right hand side of the contained elements
Positioning the mouse pointer over an element displays a tool tip describing the element if there is documentation for the element in the Schema or DTD.
The Schema Guide also displays how many instances of each subelement and attribute are allowed. If exactly one of the subelement or attribute is required, no enumeration is shown. Otherwise, the Schema Guide displays the requirement (such as "0 or more", "0 or 1", or "1 or more").
The Schema Guide is invoked automatically when you use the XML Wizard to create an XML document. You can also invoke it when the document is empty and has a Schema attached. In this situation, the Schema Guide lists in the left pane possible root elements. If using a DTD, the description in the header will show the suggested root elements (that is, those elements that are not in the content model of other elements).
The right pane displays the standard Tree View of the XML Editor to show the element that was selected when the Schema Guide was invoked, its attributes, and its immediate children.
Subelements that are not legal are shown with a red background. If the selected element contains an illegal attribute, the element itself is marked with red. Clicking on a colored element displays a similarly colored region of text along the bottom of the tree. The text describes the issue in more detail.
In many cases, the Schema Guide can fix validation errors, either by removing illegal elements or attributes, or by moving an element from a wrong namespace into a correct one. In the following example, the Schema Guide is indicating that the age element is invalid in the person element. You can delete the invalid element by clicking Delete.
Namespace errors are treated separately. These errors are common when dealing with Schemas, because Schemas can contain elements from several namespaces and have different rules for whether specific elements or attributes are required to be in a namespace. An element that has the correct local name for the document to validate correctly but whose namespace is incorrect is shown with a yellow background. You can use the Change button to move the element to the correct namespace.
Elements When selecting an element in the left pane, the tree view shows where the element can be legally inserted by displaying one or more green nodes in the tree. The following screen shows that an email element can be legally inserted above or below the existing email element.
To insert an element, select one of the green elements in the tree and click Insert. If you don't want to insert the element, simply select another object in the left pane to consider.
If you click an element in the left pane that cannot be legally inserted, you will not see any green entries in the right pane.
Attributes To add an attribute, select it in the left pane. If it is legal to add, you will see a green attribute in the right pane. Specify the attribute's value and click Insert.
You can navigate the element hierarchy by selecting a subelement in the right pane and clicking Go to. The subelement becomes the selected element and its definition is now shown in the left pane and the tree structure for the selected instance is shown in the right pane. You can work with it the same way you worked with the parent element.
The following screen shows the Schema Guide after the person element's name subelement was selected and Go to was clicked.
Click Back to return to working with the parent element.
As you type in Source View, the editor automatically highlights in red any areas of the document that are not well formed. The Tree View creates well-formed documents by design.
You can also manually validate the document for conformance to the Schema or DTD.
Select XML Editor>Validate to validate an XML document.
NOTE The menu item is enabled only if the XML document is attached to a Schema or DTD.
The editor validates the XML document against the attached Schema or DTD.
The results The report identifying any malformed statements displays in the Validate tab of the Output Pane.
XPaths References to errors are reported as XPaths. XPath (XML Path Language) is the W3C-endorsed language for addressing parts of an XML document. It uses a path notation similar to an URL for navigating through the structure of the document. (For more information, see http://www.w3c.org/TR/xpath.)
For example, the XPath /personnel/person[1] indicates the first instance of person in the XML document, the XPath /personnel/person[2] indicates the second instance of person, and so on.
In the preceding example, the id attribute is reported as missing from the first two person elements.
TIP You can search for specific XPaths in Tree View. See Searching an XML document.
You can search your document in either Source View or Tree View.
In either Source View or Tree View, select Search>Find or press Ctrl+F.
The Find dialog displays.
In Source View, you can perform standard text searches. In Tree View, you can specify the following:
Attribute names and/or values (see Searching for attributes in Tree View)
XPaths (see XPaths)
If there is a match, the first match is selected and all matching occurrences are indicated:
Searching for attributes in Tree View When searching for attributes, you can specify:
Attribute name only—This will find all attributes of that name, in any element
Attribute value only—This will find all attributes having the specified value, regardless of the attribute name
Attribute name and value—This will find all attributes with the given name and value
You can click Add attribute name and value search to search for elements containing more than one attribute with a given name and/or value. To be matched, an element must match all of the specified entries. For example, you could search for all elements having an id attribute and a salary attribute.
Workbench provides a built-in catalog of widely used Schemas and DTDs. For example, the catalog includes the Schemas for XSL, WSDL, and XML Schemas; the Sun J2EE DTDs; and the SilverStream deployment plan DTDs.
When you open an XML document that references a Schema or DTD, if the Schema or DTD is in the catalog, Workbench associates it with the XML document and enables context editing and validation.
The Workbench catalog is based on the OASIS XML catalog standard. The OASIS XML catalog standard specifies a format for mapping external identifiers (public and system identifiers) and URI references to other URI references. This makes it possible to map, for example, a URI of a namespace to a local Schema file. The standard specifies that catalogs consist of one or more catalog entry files, each file specifying a set of catalog entries.
For information on the OASIS standard, see http://www.oasis-open.org/committees/entity/spec.html.
The built-in Workbench catalog consists of three directories in the Workbench Resources directory:
About the catalog entry files There are four built-in catalog entry files:
dtdcatalog.xml, which lists all the preinstalled DTDs in the DTDCatalog directory
schemacatalog.xml, which lists all the preinstalled Schemas in the SchemaCatalog directory
user-dtdcatalog.xml and user-schemacatalog.xml, which are initially empty; you can use them to add entries to the catalog
The two DTD-related catalog entry files both point to DTD files in the DTDCatalog directory, that is, their base directory is specified as ../DTDCatalog. Similarly, the two Schema-related catalog entry files both point to Schemas in the SchemaCatalog directory, that is, their base directory is ../SchemaCatalog.
An example For example, say you are working with the personal.xsd document that contains this declaration:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
Because the built-in Workbench catalog entry file schemacatalog.xml lists this URI and maps it to XMLSchema.xsd in the SchemaCatalog directory, when you open personal.xsd, Workbench locates its Schema in the local catalog without having to go out to the Internet for it.
You might have Schemas and/or DTDs that you want to add to the Workbench catalog so they can be located when you open XML documents that use them. You can add Schemas and DTDs using the existing catalog structure or by extending the structure.
Maintaining the existing structure The easiest way to add entries to the Workbench catalog is by using the existing catalog directory structure.
To add to the Workbench catalog using the existing structure:
Add the .DTD or .XSD file to the DTDCatalog directory or SchemaCatalog directory.
Open the corresponding user-editable catalog entry file in the Workbench Resources\CatalogFiles directory.
Add the catalog entries to the file.
You edit catalog entry files with the XML Catalog Editor, as described in Using the XML Catalog Editor.
Extending the catalog structure You can also add entries to the XML catalog by extending the directory structure, that is, by creating additional directories of Schemas and DTDs and additional catalog entry files.
To add to the catalog by extending the directory structure:
Add the .DTD and/or .XSD files you want in the catalog to directories on your file system. You can organize the DTDs and Schemas any way you want, but you will need to create a catalog entry file for each directory containing DTDs or Schemas.
Create catalog entry files for each of the directories using the XML Catalog Wizard:
On the XML tab, select XML Catalog file and click OK.
The XML Catalog Wizard displays.
Specify its location. In order to have Workbench read the catalog entry file, place the file in the Workbench Resources\CatalogFiles directory.
Specify the base URI, that is, the path to the directory containing the DTD or Schema files. It is through this base URI that Workbench is able to find the DTDs or Schemas listed in the catalog entry file.
The catalog entry file is opened in the XML Catalog Editor.
Add entries as described in Using the XML Catalog Editor.
When you open a catalog entry file, Workbench displays it in the XML Catalog Editor.
The XML Catalog Editor has three views:
A Tree View and Source View, which are the same as the corresponding views in the core XML Editor
A Catalog View, which presents an interface to the catalog entries
The Catalog View has one or more tabs:
A catalog entry file whose base directory is Resources/DTDCatalog has two tabs: Public Identifier and System Identifier
A catalog entry file whose base directory is Resources/SchemaCatalog has one tab: Schema URI
A catalog entry file whose base directory is any other directory has three tabs: Schema URI, Public Identifier, and System Identifier
You can also edit and remove entries from the catalog entry file.
CAUTION Don't delete preexisting DTDs or Schemas from the catalog, because Workbench might require them.
Double-click the entry and make whatever edits you want. If you double-click a resolved URI value, the Browse button is enabled, allowing you to pick another file.
Select the entry and click Delete.
The entry is removed from the catalog entry file (the Schema or DTD itself is unaffected).
Workbench provides an XSL Editor for you to create and maintain XSL style sheets.
For complete information about XSL, see http://www.w3.org/Style/XSL.
On the XML tab, select XSL file and click OK.
Workbench generates a skeleton XSL document and displays it in the XSL Editor.
Using the XSL Editor The XSL Editor provides an environment for editing, validating, and testing XSL files.
|
Task |
Description |
|---|---|
Use the XSL tab. You can use the keyboard shortcuts listed under In Source View. | |
|
Workbench displays the results in the Validate tab in the Output Pane.
| |
Select XSL Editor>Attach Schema or DTD or XSL Editor>Detach Schema or DTD.
| |
The Result tab allows you to see the result of the transformation specified by the XSL file:
|
Here are the keyboard shortcuts provided in the XML Editor, XML Catalog Editor, and XSL Editor.
|
Keys |
Description |
|---|---|
|
Keys |
Description |
|---|---|
(Paste) Pastes the contents of the clipboard at the insertion point | |
Pastes the contents of the clipboard as the last child of the selected element | |
|
Keys |
Description |
|---|---|
Moves the insertion point one character to the left or right | |
Moves the insertion point to previous sibling (element within an element group) | |
|
Keys |
Description |
|---|---|
Selects the word the insertion point is on, or deselects any selected text | |
|
Keys |
Description |
|---|---|
|
Keys |
Description |
|---|---|
Shifts text in line containing the insertion point to the right | |
Shifts text in line containing the insertion point to the left |
|
Keys |
Description |
|---|---|
|
Keys |
Description |
|---|---|
|
Keys |
Description |
|---|---|
Displays dialog for changing the base URI, that is, the path to the directory containing the DTD or Schema files for the catalog entry file |
|
|
Tools Guide |
Copyright © 2002, SilverStream Software, Inc. All rights reserved.
