Composer User's Guide

CHAPTER 5

XML Templates

Novell exteNd Composer relies heavily on the concept of organizing related groups of XML, XSL, DTD, and/or XSD files into named templates.

 
Top of page

Sample XML Documents, Document Definitions, XSL Stylesheets, and Templates

In order to simplify working with XML data at design time, Composer lets you defined XML Templates. The purpose of the XML Template is simply to organize related documents into a single functional grouping. For example, it's not unusual, when designing an XML integration application, to have one or more sample input documents that represent hypothetical "incoming data." These input documents might or might not conform to a particular schema (.xsd) or DTD. They might or might not be associated with XSL stylesheets. You may or may not also want to associate various kinds of fault documents with the service. In Composer, you would typically organize input documents into one XML Template and create a different XML Template (with any or all of the above-mentioned ancillary items) to hold sample output documents. The "XML Template" wrapper identifies a group of related documents: sample XML docs that go with particular stylesheets, schema docs, and/or DTD files, and/or fault docs that need to be used in association with each other.

At design time, the XML sample documents in your templates serve as exemplars, or "hints," to enable Composer to display proper document tree views in the various GUI pieces that need to show your service's inputs and outputs. In this way, it becomes possible for Composer to translate simple UI gestures (like drag-and-drop) into XPath and ECMAScript expressions that can be used to carry out mappings and transformations at runtime. (Composer does the "hard work" of generating XPath and DOM methods so that you don't have to.)

 
Top of section

About Sample XML Documents

A sample XML document is nothing more than a representative model of the data your component or service will process: it contains the same elements, attributes, and structures. For example, if your application will process Company ABC's invoices, you might use a sample invoice when building the application. The sample (if it's truly representative) will have exactly the same XML structure as the invoices that will be processed.

One of the most important parts of planning and designing an XML integration application is determining all of the possible kinds of sample documents your components might need before you begin development.

The types of sample documents you may need are:

An important concept to note is that sample documents used in designing a component are not used on the server at runtime. The samples in an XML Template are really only design-time hints. They cannot be used as sources of instance data. (For that, you'd probably want to use XML Resource documents. See "About XML Resources" in the chapter on Resources.)

NOTE:   If you need to initialize any data elements with hard-coded values, you can do it programmatically in the action model, by mapping an ECMAScript string or number to XPath locations, as needed. You can also load an XML Resource and create mappings from it to (say) an input document using drag-and-drop gestures.

The sample document is a design aid that allows you to visualize the data manipulations that need to happen at runtime. At animation time (during testing or debugging) you can watch element data in the sample change locations or values, or show up in output, etc., in real time, in response to XML Map actions, ECMAScript operations, and so on. After watching the data change in real time during step-through/step-over debugging, it's easy to forget that the data values are just design-time values—placeholders, if you will. At runtime, Composer merely executes the map actions, XPath and ECMAScript operations, etc. that you specified in development.

 
Top of section

About XML Validation Documents (DTDs and Schemas)

Document Type Definition and XML Schema Definition files (DTDs and XSDs, respectively) can be used to define and validate XML documents. Schemas and DTDs define the grammatical rules of the document, such as which elements must be present and what the structural relationships are between the elements.

Recall that a schema differs from a DTD in several ways, including:

For these and other reasons, schemas (XSD files) are gradually displacing DTD files for definition and validation of XML documents.

Runtime Validation versus Design-Time Validation

Schema and DTD validation are enforced by Composer only at design time. At runtime, no validations (other than a well-formedness check) are performed on incoming or outgoing data. Nevertheless, you can force runtime validation to occur by means of ECMAScript (used either in a Function action, or wherever ECMAScript is permitted in Composer). For example, suppose you want your service to validate the Input document. You would execute this expression:

  result = Input.validate();
  if (result == true)
  // do something
  else
  // throw fault

If a schema is associated with Input in the XML Template for Input, that schema will be used for validation when the above code executes. If no schema is referenced anywhere, the validate() function simply performs a well-formedness check and returns a boolean result.

NOTE:   The validate() function will not use DTDs.

 
Top of section

About XSL Stylesheets

As part of the set of files you use in a component, you can include an XSL stylesheet. An XSL stylesheet defines the display properties of an XML document. You create or obtain the stylesheet external to Composer. The stylesheet may be useful for a component of your application that is creating a page to be displayed in Web browser.

 
Top of section

About XML Templates

An XML Template contains the sample documents, document definitions, and XML stylesheets that comprise a set of sample documents that can be used in designing your components. You'll create XML Templates early in the component design phase, then use them to specify the inputs and outputs of the components you build.

XML Templates exist primarily so that you can use and test many types of sample data at design time. It is possible to have two XML documents with different structures that both have to be handled without error by the same component. For example, if you are using an industry standard purchase order document as input, but one of your customers uses a slightly different version of that document in his business (e.g., it has some optional elements missing), you can load your customer's document into a component for testing purposes. Your component must be able to handle the different document versions, and you can test several cases by collecting all your samples into a template that serves as an input for a component.

 
Top of section

About Template Categories

Instances of XML Templates are collected into Template Categories. The Template Categories have user-assignable names and appear as folders in the XML Template Category pane of Composer's navigation frame. The members of a given category appear in the Instance pane under the Category pane. See below.

Your application can have many input and output documents, so you will want to organize them within XML Template Categories. Within an XML Template Category, you can organize templates in a way that makes sense for your application. For example, you can create folders for:

Here is an example of what your organizational scheme might look like.

5exampleXMLcats

The purpose of the folders is to store your XML Templates, which might contain sample XML documents, schema, and XSL stylesheets.

Procedure To create an XML Template Category:

  1. Select XML Template Category in the Composer Category pane.

  2. Click the right-mouse button and select New.

    5NewXMLCategory

  3. Type a name for the category and click OK.

 
Top of section

Template Scenarios

XML output from one component is often used as input for the next component in a service. Ease of sample-reuse is, in fact, one of the main benefits of working with XML Templates.

Another benefit is sample organization. It's common for a particular XML Template to hold a variety of documents related to a service. For example, a given template might contain four XML files: one to be used as Input to a particular service, one as a Temp document (a sort of scratchpad-doc to hold values that will change throughout the course of your service), one as Output, and one as a Fault document, which can hold values to be used in the case of an error.

NOTE:   For more information on Temp and Fault Documents, refer to "Using Temp and Fault Messages with a Component" in the chapter on Components.

Of course, it's entirely acceptable to create individual XML Templates for Input docs and other templates for Output docs. How you organize your documents is up to you.

 
Top of page

Creating an XML Template

5XMLTemplateIconXML Templates can be created in a variety of ways.

The most basic way to create an XML Template (and the way you'd use if you already have the assortment of XML sample docs that you want to use at design time) is to step through the XML Template Wizard. This procedure is outlined below.

You can also start with a schema (.xsd file) and have Composer generate a sample XML document (and associated XML Template) from the schema. This method is described in the section called "Creating XML Templates from Schemas" further below.

A third option is to start with a WSDL file and let Composer generate templates corresponding to the message parts defined in the WSDL. This option is described under "Creating XML Templates from WSDL" further below.

No matter which way you choose, you should begin by making sure a Template Category (a "holder" for your template) exists, as shown in the graphic below. (See the preceding section for information on how to create a Template Category.)

Procedure To create an XML Template using the wizare:

  1. Select an XML Template Category in the Category Pane, then Click the right-mouse button on the category, and select New.

    or

    Use the main menu to select File > New > xObject, then select the Template tab on the New xObject dialog, and select XML Template. (Then click OK.)

    The Create a New XML Template Wizard appears.

    5CreateNewXMLTemp01

  2. Type an arbitrary Name for this template.

  3. From the pulldown menu under Category, select from among the existing XML Template Categories that you have already created. (See "To create an XML Template Category:" above.)

  4. Under Description, enter a plain-text description of the intended usage of the template. (Optional.)

  5. Click Next. The document-selection panel of the wizard appears.

    5CreateNewXMLTemp01a

  6. Click the blue `+' icon; a file navigation dialog will appear. Use the dialog to specify an XML file on disk that you wish to add to this template. Repeat this step as necessary to add however many XML files you want. You can add files to be used as Temp and Fault documents at this time, in addition to Input and Output Parts. (Click the minus-sign icon to remove a given file from the list.)

    NOTE:   If you do not specify existing files to be used as your XML samples, an empty default file will be created. You will be able to give this file a name following the last step of the wizard.

  7. Under Default Samples, below Input, use the pulldown menu to select the file you want to see as the default Input Message for any components that use this template. (The pulldown menu will be populated with the names of the files shown in the list you built in the preceding step.)

  8. Below Output, use the pulldown menu to select the file you want to see as the default Output Message for any components that use this template. (The pulldown menu is populated with the names of the files shown in the list on the left.)

  9. Click Next. The document validation panel of the wizard appears.

    5CreateNewXMLTemp02

  10. To indicate the type of document validation you want to impose on your template documents, click one of the three radio buttons: None, Enforce DTD, or Enforce Schema. The appearance of the dialog will change depending on which button is active. Note that Composer will attempt, based on inspection of the XML template document(s) you specified in the previous dialog, to set the correct radio button for you. You can override Composer's choice at any time. The radio buttons have the following consequences:

    None—Choose this option if your application does not require validation of XML documents or if you would like to override the DTD or XSD information specified in your template documents.

    Enforce DTD—Documents will be validated against the DTD whose name and/or URI are specified in the text fields shown.

    NOTE:   If the DTD will be determined dynamically at runtime, you can supply the URI as an ECMAScript expression. If you plan to use a PUBLIC DTD/Schema after deploying the project, you must fill in the PUBLIC Name of DTD field.

    Enforce Schema—Documents will be validated against the XSD or WSDL file indicated. (See illustration below.)

    5CreateNewXMLTemp04b

    NOTE:   Composer will automatically search your sample documents to discover all of the namespaces (if any) declared inside them and the .xsd files to which they point. The namespaces and their associated schemas are displayed automatically in the above dialog; in most cases, you will not have to fill in the dialog yourself. If any namespaces are not displayed next to the correct Schema Resource, select the appropriate Schema Resource from the pulldown menu on the right. (That is, use the pulldown menu to associate the correct schema with the correct namespace.)

  11. Click Next to go to the next panel.

  12. If the documents you are using contain namespace information, the namespaces and corresponding prefixes will be summarized in this dialog. If you need to add additional namespace declarations (perhaps for documents that do not reference schemas), use the plus sign (+) icon to do so.

    5CreateNewXMLTemp04

  13. Click Next. The stylesheet selection pane of the wizard appears.

  14. (Optional) Specify an XSL StyleSheet to associate with any Service Output that is defined by this XML Template. An XSL Processing Instruction pointing to this stylesheet will be added to the Service Output.

  15. If you specified an XSL stylesheet, the following occurs:

  16. Click Finish to create the XML Template.

    NOTE:   If you did not use the + sign to add pre-existing files to your template because you wished to create an empty one, at this point, the following dialog window will appear, allowing you to type in a name for your default sample:

    5CreateNewXMLTemp06

 
Top of page

Creating XML Templates from Schemas

Composer can generate a sample XML document and an XML Template resource from a schema (.xsd) document. This is useful in cases where, for example, a business partner may have supplied you with a schema that must be used, but you lack actual sample docs based on that schema.

NOTE:   The XML "stub document" (sample doc) that Composer generates from a schema will initially have no data values, which means it may not validate against the schema until you edit it to add data values.

Procedure To create an XML Template from a Schema:

  1. If you have not already done so, create an XSD Resource based on the schema file you are using. (See "About XSD Resources" in the chapter on Resources. The XSD Resource wizard can be accessed via File > New > xObject and the Resource tab of the New xObject dialog.)

  2. Open the XSD Resource you intend to use. (You can right-click on it in the explorer instance pane, or use the File > Open command in the main menu.)

  3. When an XSD Resource is open, a blue Template icon will appear in the main toolbar in Composer:

    5XMLTemplateToolButton

    Click the XML Template tool button. A dialog appears:

    5TemplateFromXSD

  4. Choose a Template Category in which the new template should be created, using the Template Category pulldown menu.

  5. Verify that the Root Element, Template Name, and Sample controls (which are prepopulated with values derived from the schema in question) contain appropriate values. Edit any values as needed.

  6. Click OK. A new XML Template is added to the Template Category.

  7. Edit the newly created sample document as needed (to add data values).

  8. Save your work.

 
Top of page

Creating XML Templates from WSDL

When an external WSDL is downloaded into exteNd Composer, you generally need to have XML templates corresponding to message parts in the WSDL in order to create working components. XML samples must be created which can be validated against the WSDL. (These templates can then be used in components to create actions then used in the WS interchange.) Composer can help with this. If you have a WSDL Resource for a service, simply open the WSDL Resource: Composer's toolbar and menus will change as shown below, and you will be able to create XML stub documents (template docs) at the click of a button.

There are two ways to generate XML Template docs from an open WSDL Resource:

NOTE:   The samples created will not contain element data (and as a result, may cause validation errors until you enter dummy values of the appropriate types). You may need to populate various elements with sample data for test purposes. Note also that when elements refer to ##any or ##other namespaces, the samples are incomplete and you have to manually complete them.

Template documents can be create in this fashion for document-style as well as RPC bindings.

Procedure To create XML Templates from WSDL:

  1. From the main menu, click on Resources>Create XML Templates, or click on the button on the toolbar. A dialog will appear.

    5createxmltemplatefromwsdl

  2. Select a Service/Port or Binding from the dropdown list as a source for creating the XML Template.

  3. Select an Operation from the dropdown list as a source for creating the XML Template.

  4. The bottom portion of the dialog box is divided into Input, Output and Fault Messages. Follow the same procedure for each Part:

  5. Click OK to finish.

 
Top of page

Importing an XML Template

If you've already created an XML Template for another project, you can import it into the current project.

Procedure To import an XML Template:

  1. In Composer's Category Pane, select the XML Template Category to which you want to associate the template instance.

  2. Right-click and select Import from the context menu. A dialog appears.

    NOTE:   If the Import command is not highlighted, it's because you have chosen a Template Category that belongs to a subproject. This operation is not allowed. If you need to import template docs into a subproject, close the current project. Open the subproject on its own, add templates to it, save it, and close it; then return to the project you were working on originally.

    5ImportXMLTemplate

  3. Select XML Template as the Type.

  4. Select an XML Template Category from the drop down list.

  5. Select the File Name location using Browse. You may also read in a file from a URL by explicitly preceding your filename with "http://," "https://" or "ftp."

  6. Type in a Name.

  7. Optionally supply a Description.

  8. Click OK.

 
Top of page

Showing and Hiding XML Documents

It can be convenient to toggle the visibility of XML document views when working in Composer's main window.

Procedure To toggle XML document visibility:

  1. From Composer's main menubar, choose: View>XML Documents>Show/Hide.

    5xmlviewmenu

    A dialog will appear:

    5Showhidedialog

  2. The Show/Hide dialog displays the names of the XML documents associated with the open template or component.

    NOTE:   In a component, the Input and Output XML documents default to the Show column. Message parts created as a result of a component action default to hidden.

  3. In the Hide column, select any XML documents you want to be displayed and click the left arrow button. Conversely, in the Show column, select any XML documents you want to be hidden and click the right arrow button.

  4. Select the XML document you want to display as the top document and click the up arrow button until the document is displayed as the uppermost document in the Show column. Conversely, use the down arrow to move the document down further in the list.

  5. Continue to select XML documents in the Show column and use the up- and down-triangle buttons to move the XML documents into the desired order until they are displayed the way you like.

  6. Click OK. The dialog closes and the Component editor's data panes are rearranged accordingly.

 
Top of page

XML Template Editor

The XML Template Editor allows you to edit the template in Composer, rather than using an external editor.

Viewing the documents in the Template Editor and Context Menus

The View option from the main menubar allows you to select the way you want the XML information displayed in the Component Editor. You can choose from tree, text or stylized. Each view has its own unique context menu accessed by the RMB.

Tree View and Context menu options

The default view displays the message part as a tree, as shown below.

6ViewDOMasTree

This view allows you to edit element and attribute values (that is, document data) but not the XML structure.

The Context menu commands accessible via the right mouse button are shown below.

5tree

Text View and Context menu options

In Text View, you can see and edit the complete XML file, including structural elements.

6ViewDOMasText

Text view offers a convenient way to inspect non-content-model portions of the Input, Temp or Output Parts, such as comments, processing instructions, DOCTYPE declarations, and so forth.

The Context menu options accessed by RMB as shown below.

5text

Stylized View and Context menu options

When the Stylized view is selected pane, your view of the message part contents looks like this:

6ViewDOMasStyled

This view gives a "report" style overview of the XML contents so that you can see at a glance what the content is for all attributes and elements. This view uses the following algorithm to render XML.

If there is an associated stylesheet with this document component, evaluate the expression and use that one.

If this fails, use the default stylesheet: com/sssw/b2b/dt/default.xsl

To change to a stylized view, click the RMB to access the Context menu as shown below.

5stylized

Working with an XML Template

Each XML Template you create resides in an XML Template category. To view the name and creation date of the XML Template, select an XML Template category. All XML Templates for the category are listed in the Detail pane of Composer. Each template has a context menu, giving you ways to work with the template.

5objrightmousebutton

 
Top of section

Viewing an XML Document

Each XML Template contains one or more sample documents. You can open a sample document in an XML editor (a separate application external to Composer).

Procedure To view a sample document in your XML editor:

  1. Click the right-mouse button on an XML Template.

  2. Select Edit Sample and select the sample document you wish to edit. Whatever XML editor you identified during your Composer installation will open (by default, Internet Explorer is used).

 
Top of section

Editing an XML Template

You can modify the XML Template by adding and deleting sample documents, schema, and XSL stylesheets.

Procedure To edit an XML Template:

5EditXMLTemplateProp

NOTE:   Changing the name of the template on the Properties page causes a Save As operation, preserving the original and creating a duplicate with a new name. To change just the name of an XML Template, use the Rename option on the context menu.

 
Top of section

Saving Changes to XML Documents

Once you have made changes to your XML using the methods described above, you will, of course, want to save them. There are four ways to save sample XML documents i n Composer.

5SaveXMLas

Procedure To use the Save XML As dialog:

  1. Select a "Part", or XML document name from the drop-down list.

  2. If you want to save the open document as a sample, then choose Save as Template Sample.

  3. If you want to save the open document as a file, then choose Save as File.

  4. Click on OK to close the window and Save the XML.

 
Top of section

Printing an XML Document

To print the XML document, Select File>Print from the main menubar. The document component is formatted according to the template.

 
Top of section

The XML Template Editor Context Menu

When you open an XML sample file in the Content Editor and right-click on it, a menu appears allowing you to perform several functions.

5XMLContext

These functions are explained in the table below:

Edit Data

Allows you to edit element and attribute values (that is, document data)

Create Schema

Brings up a dialog allowing you to create a new schema resource

Add Sample File

Brings up a dialog with a file directory so you can select a pre-existing XML file to add to the template

Create Sample File

Brings up a dialog which allows you to type in a name for a new sample XML file.

Add to Display

Allows you to display additional XML files which are part of the current template but are not currently open in the editor pane

View

Change the view of the document (see "Viewing an XML Document" above)

Launch Editor

Opens the default XML editor you specified during installation

Save XML As

Opens the Save As dialog window, which allows you to specify a part name, save the file as a sample or save as a file

Validate

Runs a validation routine to check that your XML is sound

Find

Opens the Find dialog allowing you to search for strings in the XML data or structure

Find Next

Repeats previous search

 
Top of section

Deleting an XML Template

When you create an XML Template, Composer makes copies of the original XML, document definition and XSL files and places them into an "Imports" directory under the proper XML category. When you delete an XML Template, you are going to delete the copies, not the original files. To delete an XML Template, highlight it in the Detail Pane of the Navigator, right-mouse click it, and select Delete. The file must be closed in order to delete it.

 
Top of section

Moving an XML Template to a Different Category

Procedure To move an XML Template from one category to another:

  1. Select the template you wish to move.

  2. Click the right-mouse button and select either Cut or Copy.

  3. In the Category pane of Composer, click on another XML category.

  4. In the Details pane, click the right mouse button and select Paste.

 
Top of section

Renaming an XML Template

Procedure To rename an XML Template:

  1. Select the template you wish to rename.

  2. Click the right mouse button and select Rename.

  3. Type the new name.

  4. Click OK.

NOTE:   Be sure to rename a template using the above procedure. If you change the name of the template on its Properties page, it causes a Save As operation, preserving the original and creating a duplicate with a new name.

 
Top of page

Understanding Where XML Templates Are Stored on Your Hard Drive

XML Templates are stored as part of a project. For information on where project files are stored, see Understanding Where Project Files are Stored.

NOTE:   Copies of the samples, definitions and XML stylesheets used in the template are stored in a folder. The original documents are not modified.




Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...