Copyright © TIBCO Software Inc. All Rights Reserved

Instance

Resource

The Instance resource of the XML Tool palette enables the creation of an XML instance document. XML instance documents are XML documents -- typically representing data-oriented business documents, messages, and configuration files -- that conform to the rules of an XML Schema or DTD.

When an Instance resource is selected within your project, a series of new panels, toolbar buttons, and menus options are provided to facilitate the schema-driven creation, editing, and navigation of the resource. The editing environment for instance resources, shown in Figure 75 is described in this chapter.

Figure 75 XML Instance Editing Environment

For a hands-on demonstration of the instance editing environment, see the XML Instance Exercise.

Configuration Panel

When editing an Instance resource, the Configuration tab has the following fields:.

Table 37 Configuration Tab Field

Field	Description
Name	This is the name of the file when persisted. The *.xml suffix will be automatically added.

Toolbar

For a description of the buttons that appear on the toolbar when editing Instance resources, see Toolbar Buttons.

XML Menu

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 documents. 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.

The XML menu options are described in detail in Menu Options.

Setting a Schema

The XML instance editing environment is optimized for building XML documents based on an XML Schema or DTD. When creating a new XML document, specifying the schema within your project to base the document on is typically your first step. To set a schema, use the Set Schema button on the toolbar.

A window will appear enabling you to choose a schema from your project. Upon selecting your schema, you will be prompted to specify a root element for your document. A default value will appear, representing a “best guess” as to the root of the schema you have selected. If the default value is correct, simply select OK and the schema will be loaded. If the default value is not correct, type in the name of the root you would like to use. If you decide that you do not want to set the schema, click Cancel.

If you set a schema to a brand new document, the schema will be used to “jumpstart” your document, automatically adding all required attributes and elements into the content panel. Keep in mind, however, that your document will likely not be error free until you have entered appropriate values in the edit area. Use the Errors button on the toolbar to view a listing of validation errors in the errors panel.

You can set a schema to an existing Instance resources as well. Any errors detected will be immediately listed in the errors panel.

Right-click the Set Schema button to choose from a list of recently applied schemas.

Content Panel

The content panel provides the primary editing area and 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). The content panel also has a navigator bar for navigating throughout the document and a factory bar for adding new elements, attributes, processing instructions, comments, and text. The content panel is shown in Figure 76.

Figure 76 Content Panel

Content Panel: Tag Area

The tag area appears as a shaded column to the left of the edit area in the main window. It displays all of the component that comprise the instance document. Blue icons are used to distinguish the components, as described in the table below.

Table 38 Tag Area Components

Icon	Component
	Element
	Attribute
	Comment
	Processing Instruction
	Text

Along with the edit area, the tag area is where most of your work will be done when building XML documents. For more information on the key tasks performed within the Tag area, see:

•	Inserting new elements, attributes, processing instructions, and comments

•	Modifying Document Structure

•	Identifying Data-Entry Constraints

•	Navigating the Document

•	Creating a Customized View of the Tag Area

Inserting new elements, attributes, processing instructions, and comments

Graphical document building tools are provided that facilitate the insertion of new elements, attributes, processing instructions, comments, and text. The two main insertion tools are the Insert box, which appears in the tag area, and the factory bar which appears in between the Tag and Edit areas and the errors panel.

Insert box

Within the tag area, double click an element to generate a drop down box. This box will always contain an empty box with a series of icons below which, when selected, determine the type (element, attribute, and so on) and location (child, sibling, parent) of the node to be entered. (The insertion default is an element sibling.) If the document is based on a schema, any elements and attributes available based on the schema's content models will also be appear in the insert box, and can be added with single mouse click. Note in Figure 77 that the elements appearing the drop down box are marked by various indentions which represent their relationship to the selected element. In this case, street and city are siblings to the selected element, street, and hence, appear along the same vertical line. The elements shipTo and item appear to the left of the selected item, indicating parent and grand-parent relationships, respectively.

Figure 77 Insert Box

In Figure 77, a name (suiteNumber) for a new sibling element for street has been entered into the text box. With a single click on the appropriate icon, this new entry can be changed from an element into an attribute, text, comment, or processing instruction. When you are finished entering and defining your new tags, either hit tab or enter to complete the entry.

If you are using a schema to build your document, adding new elements and attributes may cause your document to become invalid. You will be permitted to create documents that break from the structure of your schema, but will be alerted whenever this occurs by way of the errors panel.

Factory Bar

The factory bar at the bottom of the content panel, provides another option for entering new items to the tag area. The factory bar is shown in Figure 78.

Figure 78 Factory Bar

The factory bar provides an easy way to identify and insert any additional elements (children or siblings) or attributes defined by the schema for the element selected in the tag area. Click on any element of attribute name appearing on the factory bar to have it automatically added to the document.

The factory bar also facilitates the insertion of new elements and attributes, as well as new comments, processing instructions, and text. Click the blue icon representative of the item you would like to add to launch the Insert box described above. Figure 79 illustrates the insert box which appears after clicking on the comment icon on the factory bar.

Figure 79 Inserting a Comment

Modifying Document Structure

A right button menu, shown in Figure 80, provides the basic cut, copy, paste, clear and rename functions to enable you to make changes to the elements and attributes within the tag area. (For an explanation of the other options on this menu, see Creating a Customized View of the Tag Area.)

Figure 80 Right Button Menu

You can also use your mouse to quickly change the positioning of elements and attributes appearing in the tag area. This “drag and drop” editing can be used to change the structure of your document or simply to change the view of your document. (For more information, see Promoting elements and attributes). To move an element or attribute, left click on the blue icon which appears to the left of the tag. Holding down the left mouse button, drag the item to its new position and release the mouse button. If your document is dependent on a schema, be sure to use the Errors button on the toolbar to determine if the move is permitted by the schema.

Identifying Data-Entry Constraints

When creating an XML document based on a schema, the tag area facilitates data entry into the edit area by providing a guide to the type of data that is required by the schema. When you mouse over the element and attribute tags appearing in the tag area, a tool tip is created which describes the type of data that should be entered in the edit area. For example, in Figure 81, the tool tip indicates that the content for the quantity element should be entered as an int (integer) to conform to the schema.

Figure 81 Content Hint as Tool Tip

Navigating the Document

The navigator bar appears along the top of the content panel (below) tracks your movements throughout the tag area, displaying your selected element or attribute along with each of its element antecedents, all the way up to the document root. Notice in Figure 82 that the entire ancestry of the element selected in the tag area--street--is illustrated on the navigator bar.

Figure 82 Navigator Bar

Clicking on an element in the navigator bar will also open a drop down window displaying the selected element and each of its siblings. Figure 83 shows the siblings for the billTo element.

Figure 83 Siblings Displayed on Navigator Bar

By presenting elements in the context of their parents and siblings, the navigator bar provides a clean view of an element’s place in the document's structure, a feature which is particularly useful when your documents are lengthy. The navigator bar also facilitates navigation throughout your document. Double clicking on an element from the drop-down automatically moves you to that element within the tag area.

Creating a Customized View of the Tag Area

The tag area can be customized in numerous ways to facilitate data entry and to make the presentation of the document more intuitive and user-friendly. Customized views are preserved and associated with the schema used to create this document. This means that, as long as needed, every new XML document created using the same schema will be presented the same way automatically.

Your customized view can be saved by way of the Presentation menu (XML>Presentation). Multiple presentations may be associated with a given schema, providing multiple display options for an instance document.

Customization is performed using the right button menus associated with each tag. The initial menu that appears is used to customize tags on an individual item basis. That is, if the document uses several address elements, the menu choice will only affect the address element that is selected. The final option of this menu provides access to a type level sub-menu. The options within this menu affect all instances of a given element within your document. Both the item and type level menus are shown in Figure 84.

Figure 84 Item and Type Level (Right-Button) Menus

To learn more about the customization options on the right-button menu, see:

•	Expanding and collapsing elements

•	Hiding elements and attributes

•	Creating aliases for elements and attributes

•	Adding color to your tags

•	Promoting elements and attributes

Type level changes made through the application of each of these options can be saved by way of the XML menu (XML> Presentation > Save As...)

The alignment of the tags can also be changed by way of the XML menu (XML>View>Align Labels).

Expanding and collapsing elements

To allow for a cleaner view of your document at a particular level of its hierarchy, you can expand or collapse sections of the tag structure by clicking the small + or - icons preceding element tags. All elements of a particular type (e.g. all address elements) can be collapsed at once by right-clicking on an instance of element in the tag area and selecting the “Element Type” option from the drop down menu. A second menu will appear with the expand and collapse options.

Hiding elements and attributes

If you are working with a specific set of elements in a document, you may want to hide the elements and attributes you are not editing. Elements and attributes can be hidden either on an item basis (hide only one instance) by right-clicking on the element and selecting hide from the initial drop-down menu. Elements and attributes can be hidden on a type basis (hide all instances) by right-clicking on the element and selecting “Element Type” from the first drop down menu and “Hide” from the “Element Type” sub menu.

To show elements that have been hidden, select the parent of the hidden element and use the “Show” or “Show All” functions accessible through the item and type-level drop down menus. The Show command is used to select an individual element or element to be shown, as shown in Figure 85, while “Show All” displays all elements or elements previously hidden within the selected element.

Figure 85 Selecting a Hidden Element to Show

Creating aliases for elements and attributes

Element or attribute names that are not easily understood can be given an alias in your view of the document. The alias is only designed to help users understand the meaning of a tag within the tag area without having to rename the element. Aliases will not appear in the source panel and the original element names will be preserved when the document is saved.

An alias can only be applied at the type level (meaning all instances of the selected element or attribute name will be displayed with the alias name), using the Alias option of the type level submenu of the right button menu. A dialog box will appear where you can set the alias. In Figure 86, the attribute dur is given the alias of duration.

Figure 86 Specifying an Alias

Adding color to your tags

Color highlighting can be applied to make the instance document more intuitive and to showcase important areas. Color can only be applied at the type level (meaning all instances of the selected element or attribute name will be highlighted with the selected color), using the Color option of the type level submenu of the right button menu. Six colors are available, as shown in Figure 87.

Figure 87 Color Options

Once a color has been selected, the tag’s default background color (light gray) will change to the chosen color.

Promoting elements and attributes

You can customize your view from the default vertical format to a horizontal tabular format by promoting one or more attributes or (child) elements to the same line as the parent. This helps isolate a selected element or attribute type for data entry. Promotion also provides a more concentrated view of the document, especially useful for documents with many elements and attributes holding small amounts of text.

Promotion is performed at the type level only (meaning all instances of the selected element or attribute will be promoted), using the Promote option of the type level submenu of the right button menu.

Promotion can also be performed by dragging and dropping an attribute or child element from the tag structure into the edit area on the same row of the parent element.

Figure 88 illustrates the tabular format created through promotion. In this example, the attributes name and focus have been placed on the same row as their element, sale_agent and the elements total_sales, total_calls, nails, and screws have been placed on the same row of their parent, monthly.

Figure 88 Promoted Elements and Attributes

If you want to promote a large number of child elements, you can resize an element row to allow for multiple lines of promotion per element. To resize an element row vertically, click on the bottom of the row in the area just to the left of the split bar separating the Tag and Edit Areas and then drag to the desired size. An element row can be re-sized to allow for a maximum of 7 lines per row. In Figure 89, the row for the element monthly has been resized to allow for three lines of promotion.

Figure 89 Resizing Rows to Allow for Additional Promotion

To cancel a promotion, right click the promoted item and choose Demote from the menu.

Promoting elements and attributes does not change their structural position within the XML document, just their position within the content panel.

Content Panel: Edit Area

The edit area, adjacent to the tag area in the content panel, is where the data associated with the elements and attributes that appear in the tag area is entered.

While entering data in the edit area is very straight forward -- much like filling out a form -- the following tips will help you add to your document with greater ease.

When building documents based on a schema:

•	a single mouse click activates the data entry field for elements defined as text only.

•	mixed content models default to the “show as markup” view; all other content models default to “show as rows”. See “Show as Rows” versus “Show as Markup” for more information.

•	data should be entered directly over the content tips, which appear as grayed-out text strings and describe the expected content for the element or attribute.

•	when data entry in a particular field is complete, press Enter or Tab to move to the next field.

When building documents with no schema:

•	when a new element is added, the data entry field is initially activated with a double click, after which only a single click is required.

•	when data entry in a particular field is complete, press Enter or Tab to move to the next field.

Content Hints

If your document is based on a schema, content hints facilitate valid data entry by providing information about the schema's content model. The hints appear as grayed-out text strings in the edit area next to each structural element. Figure 90 illustrates the different types of content hints.

Figure 90 Content Hints

Content hints in parentheses represent the sequence and occurrence of any data elements contained by the particular structural element. The content models are described using occurrence and sequence indicators. Table 39 describes the Occurrence indicators. Table 40 describes the Sequence indicators.

Table 39 Occurrence Indicators

Occurrence Indicator	Meaning
None	The element must appear once and only once.
?	The element (or group of elements) may appear zero or one times. The element is optional, but is only allowed to appear once if used.
+	The element (or group of elements) must appear one or more times. The element is required to appear at least once, but multiple consecutive occurrences may be present.
*	The element (or group of elements) may appear zero or more times. The element can appear as many times consecutively as needed, or even zero times.
{}	The element (or group of elements) must appear within the specified range of times.

 

Table 40 Sequence Indicators

Sequence Indicator	Meaning
|	Can be read as 'or'. Creates content model with particles enumerated (only one may be chosen).
,	Can be read as 'followed by,' requiring that the elements or groups of elements appear in the precise sequence indicated
&	Elements may appear in any order, but may not be repeatable.
()	Groups elements, allowing a set of choices or a sequence to be used anywhere that a single element can appear.

Besides element content, content hints also provide data typing and default value information. Also, if the schema enumerates values for an element or attribute, a drop down list of the possible choices is provided (when you click on the data entry field.)

For a description of the data types that may appear as content hints, see http://www.w3.org/TR/xmlschema-2/#built-in-datatypes

Content hints are displayed by default. They can be turned off by way of the XML menu (XML > View > Content Hints).

“Show as Rows” versus “Show as Markup”

Element and attribute content can be displayed in either a row format or in markup format. When a element's content is displayed in row format the element, along with each of its child elements, appear in the tag area along with a corresponding data entry field in the edit area. Figure 91 shows a date element in row format.

Figure 91 Row Format (The Default View)

When an element's content is displayed as markup, all of the element's content (that is character data, child elements, child element character data, and so on) is displayed as XML in the edit area. Figure 92 shows the date element in markup format.

Figure 92 Markup Format

A row holding content shown as markup can be collapsed or expanded by way of the blue icon appearing at the end of the data entry field. In Figure 93, the field has been expanded to show all of the markup content associated with the element Date.

Figure 93 Blue Ellipsis Icon for Collapsing or Expanding Markup View

By default, data is presented in “show as rows” formatting. The two exceptions are mixed content models and comments, which are displayed as markup by default.

Errors Panel

When you set an XML document to a schema, an initial validation check is performed to ensure that your document is in agreement with the rules outlined by the schema. As you make changes to your document, use the Check for Errors button on the top of the panel to determine if the changes are valid. Detected errors are displayed in the errors panel, located below the Content or Source panel.

The errors panel contains a listing of errors along with a brief description. Typical error messages indicate:

•	data that does not match the data type specified by the schema

•	elements in the improper sequence

•	elements or attributes not defined in the schema

Click on the error within the errors panel to identify where the error exists within the document. The problem area will be highlighted within the Tag and Edit areas.

If the document does not reference a schema, upon checking for errors the errors panel will indicate one error: Element “root”: Document has no governing schema This message is not indicative of an error; rather, it indicates that the instance cannot be checked for validity errors as it is not governed by a schema.

Source Panel

When selected by way of the XML > View menu or upon clicking the Source button on the toolbar, the source panel becomes the primary panel for editing. The source panel allows you to edit the source code directly. If you're comfortable with XML syntax, editing directly within the XML source may be useful.

To make the other panels reflect the changes you've made, click on 'Reparse' at the top of the panel. Any errors found upon reparse will be reported.

UTF-8 is set as the default encoding for XML resources. The encoding can be changed on the XML Editing tab of the Preferences window (Edit>Preferences).

Copyright © TIBCO Software Inc. All Rights Reserved