Copyright © TIBCO Software Inc. All Rights Reserved

Getting Started with the XML Tools Palette

 

The XML Tools palette allows you to create and define the following types of XML resources:

•	DTD — A Document Type Definition (DTD), the schema language specified by the W3C XML 1.0 specification.

•	Schema — An XML Schema, as defined by the W3C Recommendation (May 2001).

•	Instance — An XML document conforming to either an XML Schema or DTD. (The Instance resource can also be used to create XML documents that do not use a schema.)

Schemas and DTDs can be used in several places within your integration project. For example, WSDL files (files that describe web services) use schemas to define the input and output messages of a web service. Several TIBCO ActiveMatrix BusinessWorks activities have Input Editor or Output Editor tabs where you can use a reference to a defined schema.

TIBCO provides partial support for XML Schema redefines in design-time editing of XSD schemas and runtime processing of XML. There are some known issues with complex, multi-level usage of this feature of the schema language that manifest in the TIBCO ActiveMatrix BusinessWorks Mapper activity and in runtime validation of data. Given the industry trend away from this XSDL feature, TIBCO has no plans to further enhance support. It is recommended that schema authors use other features of the language to create similar patterns of inheritance and restriction, such as type extension, substitution groups, and so on. Please contact TIBCO Support if you need help with schema design alternatives.

Creating a New Resource

To add a new XML resource to your project, follow these steps:

1.	Select a folder in the project panel.

The XML Tools palette becomes available. If the palette is not available

−	Make sure you’re in palette mode by clicking the switch palette mode icon.

−	Choose the Palettes > General > XML Tools menu and make sure XML Tools is checked.

2.	From the palette panel, drag a Schema, DTD, or Instance icon into the design panel to add that resource to your project.

For additional information on basic interaction with TIBCO Designer and on customizing your GUI, see TIBCO Designer User’s Guide.

Figure 1 Adding an XML Resource to Your Project

 

Existing XML resources can be added to a folder in your project by way of the Project menu (Project > Import Resources from File, Folder, URL...).

Features

When you select a Schema or DTD resource in the project panel, a set of new panels becomes available. You can use these panels to create, validate, and manage the schema resource. Features include:

•	Real-time DTD error checking

•	Graphical representations of schemas for intuitive development and communication

•	Intuitive properties panel facilitating the application of advanced schema concepts such as data type constraints and substitution groups (XML Schema only)

•	Component and schema level documentation

•	Tools for including other schemas and/or schema components when building a new schema

•	A Source view for directly editing the source code

Because a DTD is not as feature-rich as an XML Schema, the editing environment for an XML Schema and a DTD is similar, but not identical. With a few exceptions, the DTD interface supplies a subset of the functionality provided by the Schema interface.

Getting Started with Schema and DTD Resources

You can access the schema editing panels by using a set of toolbar buttons or the Schema menu. The available tools combine to present a consistent view of your schema. Figure 2 illustrates the editing environment for Schema and DTD resources.

Figure 2 Editing Environment for Schema and DTD Resources

When you begin work on a new XML Schema or DTD, most of your work is performed in the Element/Types Panel, which is used to declare the elements, complex types, and attributes that define document structure and describe data content.

Example: Creating a Schema

For example, to create an element called Book for a schema describing the structure of a book (which may contain elements such as a title, author, chapters, sections, glossary, index, and so on), follow these steps:

1.	Drag a Schema resource from the palette panel to the design panel and double-click it to open it.

2.	If starting a new document, tab to the Element column and replace root with Book.

Names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.

3.	Ignore the Derives From column for now as this declaration will not be derived from an existing complex type definition.

4.	Tab to the Content column and select the appropriate content type from the Content Type button. In this example, the content for Book will contain other elements (such as Chapter), so select Elements.

Figure 3 Selecting Content Type

5.	Tab to the Content Model column and type in the content model of the book. A simple content model for Book might look like the one shown below. See Elements/Types Panel and Example: Building a Content Model, for more information on how to build a content model.

Figure 4 Building Content Model

If the content model contains references to sub-elements that are not yet declared, a prompt to create entries for these elements will appear.

6.	Select Create new elements as Locally defined and click Create.

Figure 5 Auto Create Dialog

By default, new elements are declared to have xs:string content, which means they can hold text, but not other elements.

XML Schema elements can be declared locally or globally. Local elements exist within the context of their parent element only. Accordingly, you could have a local element named title that appears within a book element and another local element named title that appears within a mortgage element. Global elements are declared such that they can be referenced within any content model. All global elements must have unique names.

7.	Click Create to create the elements.

8.	Tab to the Attributes column for the element's row and type in attributes for the element. For example, the element Chapter may include attributes that give us more information about a chapter, such as its chapter number and chapter title.

If an attribute is as yet undefined, it is automatically created with data type xs:string. These attributes can be seen and modified in the Attributes Panel. See Attributes Panel for more information.

The figure below illustrates the elements declared in this example.

Figure 6 Elements Declared

The Elements/Type panel always appears beneath the content model diagram. The content model diagram only appears if the Elements/Type panel is selected. The content model diagram provides a graphical overview of your schema.

Figure 7 Content Model Diagram

This serves as a brief introduction into the types of declarations used to build your schema. An overview of the other panels used to build your Instance resources is provided in Table 5.

For step-by-step XML Schema building exercises, see XML Schema Exercises. To build a sample DTD, see DTD Exercise.

Getting Started with Instance Resources

When an Instance resource is selected within the project panel, a new set of panels appears, providing an interface for creating and navigating the resource. Features include:

•	Document-building guidance based on the rules defined in an XML Schema or DTD

•	Validation against an XML Schema or DTD

•	Source view enabling direct edits to the source code

•	Multiple customized displays of an XML document

The new panels, in addition to new toolbar buttons and menu options, facilitate the schema-driven creation, editing, and management of data-oriented XML documents, messages, and configuration files. The next diagram illustrates the editing environment for instance resources.

Figure 8 Instance Editing Environment

The interface is optimized for XML documents based on a schema, so associating your document with a schema in your project is typically the first step. For example, to create an instance of an invoice schema:

1.	Drag an Instance resource into the design panel and double-click it to select it.

2.	Click the Set Schema button on the toolbar.

Select the desired schema from your project and indicate the element to serve as the root element for the document. Most of your work will be performed in the content panel, which consists of a listing of the elements and attributes (tag area) on the left and an area for inserting values for the elements and attributes (edit area) on the right.

Figure 9 Tag Area and Edit Area

3.	To enter data for an element or attribute (if allowed by the schema), click the corresponding field in the edit area and type in the value.

When a new schema is set, content hints appear as grayed-out text strings in the edit area. The content hints indicate the expected content, as defined by the schema, for the associated element or attribute in the tag area. For more information, see Content Hints.

4.	When a new schema is set, only required elements and attributes appear in the tag area. To add more elements or attributes, double click an element to generate a drop down box.

This box always contains an empty box with a series of icons below. These icons, when selected, determine the type (element, attribute, and so on) and location (child, sibling, parent) of the node to be entered. If the document is based on a schema, any elements and attributes available based on the schema's content models also appear in the insert drop down box, and can be added with a single mouse click.

 

The factory bar at the bottom of the content panel, provides another option for entering new elements and attributes.

An overview of the other panels you can use to build your Instance resources is provided in Table 5.

A detailed, step-by-step XML instance building exercise is included at the end of the Instance chapter. See XML Instance Exercise.

Panels

When working with a resource from the XML Tools palette, new panels are provided to help you review and refine the resource. The panels are summarized in the Table 5.

Table 5 XML Tools Panels

Panel	Resource	Description
Configuration	All	The configuration panel is used for setting the XML resource name. For more information on the configuration panel, see: • Schema Properties Panel (Schema) • Configuration Panel (DTD) • Configuration Panel (Instance)
Source	All	The source panel allows you to edit the source code of your XML resource directly. For more information on the source panel, see: • Source Panel (Schema) • Source Panel (DTD) • Source Panel (Instance)
Validation or Errors	All	The errors or validation panel displays warnings and errors detected throughout the editing process. For more information on the errors or validations panel, see: • Validations Panel (Schema) • Errors Panel(DTD) • Errors Panel (Instance)
Elements/Types	Schema and DTD	The elements/types panel enables you to view, create, and edit element and attribute declarations and complex type definitions. The elements/types panel is typically the place you'll start defining your schemas. For more information on the elements/types panel, see: • Elements/Types Panel (Schema) • Elements Panel (DTD) Note: This panel is referred to as the elements panel when working with DTD resources.
Content	Instance	The content panel provides the primary editing area. The panel loads by default when an Instance resource is selected in the project panel. The content panel consists of a left-hand listing of the elements and attributes (tag area) and a right-hand area for inserting values for the elements and attributes (edit area). For more information on the content panel, see Content Panel.
Attributes	Schema and DTD	The attributes panel is used to view, create, and edit attribute type declarations. For more information on the attributes panel, see: • Attributes Panel (Schema) • Attributes Panel (DTD)
Overview	Schema and DTD	The overview panel is used to control the creation of schemas that use XSD Includes, XSD Imports and DTD System Entities (modules), as well as explore the overall organization of your schema. For more information on the overview panel, see: • Overview Panel (Schema) • Overview Panel (DTD)
Properties	Schema and DTD	The properties panel is used to associate properties or constraints with a selected declaration. For more information on the properties panel, see: • Properties Panel (Schema) • Properties Panel (DTD)
Advanced	Schema and DTD	The advanced panel is used to define or edit parts of XML schemas that move beyond the description of document structures, such as namespaces, notations, entities, and processing instructions. For more information on the advanced panel, see: • Advanced Panel (Schema) • Advanced Panel (DTD)
Simple Types	Schema	The simple types panel enables XML Schema authors to create their own types (simple types), which can then be applied to element declarations and attributes in the schema. For more information on the data types panel, see: • Simple Types Panel
Component Doc or Notes	Schema and DTD	The component doc or notes panel provides an area where you can add schema or declaration level documentation.For more information on the component doc or notes panel, see: • Component Doc Panel (Schema) • Notes Panel (DTD)

Common Columns In Tables

Several panels use tables to display the declarations within a schema. Figure 10 illustrates the first two columns that many tables share.

Figure 10 Common Table Columns Used by XML Tools Palette Resources

•

Row Selector/ Error Indicator — This column contains grey or red dots located at the start of each row on the left. Right-clicking on a dot brings up a menu offering cut, copy, paste, and delete or clear options. (Multiple rows can be selected at a time using the Shift and Ctrl keys). A red dot indicates there is an error in the declaration. If you hover the mouse cursor over a red dot for a few seconds, a description of the declaration's error is displayed.

•

Included Document Indicator — This column indicates whether a declaration comes from the file being edited. If a small document icon with a red line through it appears in this space, the declaration cannot be edited directly here, because the declaration comes from a file that has been included from the overview panel. To edit these declarations, right click the document icon and choose unlock. Be aware, however, that any changes made to the declarations will be reflected in the original (external) document as well.

Toolbar Buttons

When editing or viewing XML Tools resources, additional buttons appear on the toolbar. The toolbar buttons are described in Table 6.

Table 6 Toolbar Buttons

Toolbar Button	Resource	Function
	All	Checks the resource for errors and reports the results in the errors panel.
	All	Opens the source panel. If the button is dimmed, the panel is already open.
	Schema and DTD	Opens and closes the overview panel.
	Schema and DTD	Opens and closes the properties panel.
	Schema and DTD	Opens the elements/types panel. If the button is dimmed, the panel is already open. Note: This panel is referred to as the elements panel when working with DTD resources.
	Schema	Opens the simple types panel. If the button is dimmed, the panel is already open.
	Schema and DTD	Opens the attributes panel. If the button is dimmed, the panel is already open.
	Instance	Opens the content panel.
	Instance	Allows you to associate a schema from your project with your instance document.
	Instance	Allows you edit your schema. Apply your changes to have them reflected in the content panel for the Instance resource.

Menu Options

When editing resources in the XML Tools palette, menus become available for performing various operations. For Schema and DTD resources, the Schema menu becomes available. For Instance resources, the XML Menu becomes available. The following sections describe the options available for these menus.

Schema menu (Schema and DTD resources)

A Schema menu becomes available when editing a Schema resource. The Schema menu contains two submenus, View and Tools (or Edit).

•	The View menu provides options to control the panels used for editing, organizing, and viewing your schemas.

•	The Tools (or Edit) menu includes options for searching or editing your schema, checking your schema for errors, and defining reusable schema components.

Table 7 describes the Schema menu.

Table 7 Schema Menu Options

Menu	Option	Description
Schema > View	Schema Properties	Opens the schema properties panel.
Schema > View	Overview	Opens or closes the overview panel.
Schema > View	Properties	Opens or closes the properties panel.
Schema > View	Element/Types	Opens the element/types panel. If the option is dimmed, the panel is already open. Note: This panel is referred to as the elements panel when working with DTD resources.
Schema > View	Simple Types	Opens the simple types panel. If the option is dimmed, the panel is already open. Note: This option is available for Schema resources only.
Schema > View	Attributes	Opens the attributes panel. If the option is dimmed, the panel is already open.
Schema > View	Advanced	Opens the advanced panel. If the option is dimmed, the panel is already open.
Schema > View	Source	Opens the source panel. If the option is dimmed, the panel is already open.
Schema > View	Notes or Component Doc	Opens or closes the notes or component doc panel.
Schema > View	Errors or Validation	Opens or closes the errors or validation panel.
Schema > View	Zoom In	Makes the items in the content model diagram larger.
Schema > View	Zoom Out	Makes the items in the content model diagram smaller.
Schema > View	Auto-Update Diagram	The Auto-Update Diagram feature updates the content model diagram every time a change is made. This menu option toggles this feature on or off.
Schema > View	Diagram Attributes	Displays or hides attributes in the content model diagram.
Schema > View	Expand	Launches the Content Model Editor, an expanded dialog box for editing content models. The Content Model Editor launches only when the cursor is located within the Content Model column of the element/type list.
Schema > Tools	Check For Errors	Checks the DTD for errors and reports the results in the errors panel. (This function can also be performed by way of the Errors button on the toolbar.)
Schema > Tools	Define Reusable	Provides options for creating either reusable pieces of declarations or text. For more information on reusables, see Building Content Models with Reusables (Internal Parameter Entities) (DTD).
Schema > Tools	Edit Reusable	Provides options for editing existing reusable pieces of declarations or text.
Schema > Tools or Edit	Find	Enables you to search for text in the active window. Select this option for the initial search.
Schema > Tools or Edit	Find Again	Searches for the next occurrence of the text previously entered in the Find dialog box.
Schema > Tools or Edit	Replace	Used to search and replace text in the active window. Replace is used for the initial search-and-replace.
Schema > Tools or Edit	Replace Again	Searches and replaces the next occurrence of the text previously entered in the Replace dialog box.

XML Menu (Instance resources)

An XML menu becomes available when editing an Instance resource. The XML menu contains three submenus: Tools, View, and Presentation.

•	The Tools menu includes options for inserting elements or attributes and for locating and replacing text.

•	The View menu provides options to control the panels used for editing, organizing, and viewing your XML instance.

•	The Presentation menu allows you to associate one or more customized views with the active instance document. The presentations are associated at the schema level, so the views you create for a single document adhering to a schema become available for all instances of the schema.

Table 8 describes the XML menu.

Table 8 XML Menu Options

Menu	Option	Description
XML > Tools	Insert	Enables you to insert an element, attribute, comment, or processing instruction.
XML > Tools	Find	Enables you to search for text in the active window. Select this option for the initial search.
XML > Tools	Find Again	Searches for the next occurrence of the text previously entered in the Find dialog box.
XML > Tools	Replace	Used to search and replace text in the active window. Replace is used for the initial search-and-replace.
XML > Tools	Replace Again	Searches and replaces the next occurrence of the text previously entered in the Replace dialog box.
XML > View	Navigator	Toggles the navigator bar on or off. If a check appears to the left of the menu item, the Context bar is turned on.
XML > View	Factory	Toggles the factory bar on or off. If a check appears to the left of the menu item, the factory bar is turned on.
XML > View	Errors	Opens or closes the errors panel that displays errors found when validating a document against a schema.
XML > View	Markup Icons	Toggles on or off the blue markup icons to the immediate left of items in the tag structure. If a check appears to the left of the menu item, the option is turned on.
XML > View	Content Hints	Toggles on or off content hints that are displayed at half-intensity ('grayed-out') in the edit area to the right of certain elements or attributes. If a check appears to the left of the menu item, the option is turned on.
XML > View	Default Attributes	Hides or displays any default values specified for attributes in the schema. If a check appears to the left of the menu item, the option is turned on.
XML > View	Content	Displays the content panel. If a check appears to the left of the menu item, the content panel is displayed.
XML > View	Source	Displays the source panel. If a check appears to the left of the menu item, the source panel is displayed.
XML > View	Align Labels/Indent Labels	Choosing this option will left-align all tags and markup icons in the tag area. When Align Labels is active, the View menu selection changes to Indent Labels. Choosing Indent Labels will return the tag structure to its default display (with indents).
XML > Presentation	New	Creates a new presentation. Returns the content view to its default environment to allow new customizations from scratch.
XML > Presentation	Save As	Allows you to name and save the current presentation.
XML > Presentation	(Presentation Listing)	A listing of the previously defined presentations. The presentation currently displayed is indicated by a check mark.
XML > Presentation	Set Default	Sets the presentation selected in the presentation listing as the presentation to appear by default when its associated schema is initially set.
XML > Presentation	Remove	Removes the selected presentation.

Content Model Diagram

The content model diagram of the elements/types panel graphically displays the content models in a Schema or DTD resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.

Reading the Content Model Diagram

To view a content model, click the appropriate element in the element/type list (below the diagram). The content model diagram is updated to reflect the currently selected element or type's content model. The content model diagram uses a visual vocabulary to represent complex element content models.

Elements are displayed as objects (in boxes) within the content model diagram. The boxes contain element names, data type indicators, and occurrence indicators. An element’s content model may be composed of text, other elements, text and elements, data, or none of these (as defined in the element definition). The icons used in the content model diagram are illustrated in Figure 11.

Figure 11 Content Model Diagram

If an element’s content model includes other elements (as indicated by the element content icon), the child elements may also be displayed in the content model panel. To view an element’s children, click once on the parent element’s content indicator icon to expand its tree. To collapse the tree and hide the child elements, click on the parent element object again.

Sequence indicator symbols do not appear in the content model diagram, but they are implied. Sequence content models are represented by right-angle brackets, with elements listed in the order that they must appear. Figure 12 illustrates the presentation of an element named sequence.

Figure 12 Diagram for a Sequence

Elements that are separated by the 'or' symbol ('|') in the content model appear to the right of the parent element, after two diagonal branch indicators, in the order they appear in the content model. Figure 13 shows the representation of an element named choices with the content model (choice1 | choice2 | choice3).

Figure 13 Diagram for Choice

Occurrence indicator symbols are used to identify how often an element may or must appear and are shown in the content model diagram. If occurrence indicators apply to a group of elements, the elements are illustrated in the content model diagram as branching off an occurrence indicator symbol. Figure 14 shows a content model similar to that presented in Figure 13, but with the group of choices made optional and repeatable. The multichoice element has the content model (choice1 | choice2 | choice3)*.

Figure 14 Optional and Repeatable Set of Choices

If an occurrence indicator applies only to a single element, it appears appended to the box with the element name. Figure 15 shows a possibilities element whose content model contains all the occurrence indicators: (seq1, choice1?, choice2+, choice3*).

Figure 15 All Occurrence Indicators

Mixed declarations always offer a choice of elements that are both optional and repeatable. These appear as the mixed element shown below in Figure 16. Note that the mixed element may contain both text and elements.

Figure 16 Mixed Content Model

For Schema resources, if a content model is defined as all, a conforming document must contain exactly one of each element specified in the content model (or zero if an element is specified as optional), with the elements occurring in any order. (Elements within an all content model cannot be repeatable.) Figure 17 illustrates the all content model (all1 & all2 & all3), represented with an arc.

Figure 17 All Content Model

Navigating with the Content Model Diagram

The content model diagram also provides navigation to the specifics about a particular element or attribute. To scroll to an element's type definition in the list of elements, right-click on the element while browsing the element in the content model diagram. A context-sensitive menu appears. Click the Go to Element Name option, and the selected element is made active in the list of element definitions.

Editing with the Content Model Diagram

Right-clicking on your content model diagram brings up a menu that allows you to edit your content models. In addition to the navigation features described above, the menu allows you to change the element's occurrence or content.

If you choose to modify the content (content model or data type) for the element, your changes are reflected in the Content and Content Model/Data Type columns of the element/type list below the content model diagram.

Modifying the Display of the Content Model Diagram

To modify the display of the content model panel, right-click the yellow background. A menu appears with the following options.

•	Zoom In — zooms in on the diagram.

•	Zoom Out — zooms out on the diagram.

•	Diagram Attributes — element’s attributes are displayed in the diagram. (This option is selected by default).

•

Show Used-by Pane — displays the used-by panel to appear on the right hand side of the content model diagram. This panel displays a list of other elements (if any) that contain the currently selected element in their content model. All potential parent elements that explicitly include this element in their content models are listed. (If no parents appear, then the element may only be used as a document root element or in content models of ANY.) Clicking on any element name in the list makes the element the currently selected element, changing the display.

Copyright © TIBCO Software Inc. All Rights Reserved