Figure 40-1 shows the Map View of the XSLT Map Editor. The left pane contains the source tree representing the incoming source XML document. The source tree can be created from an XSD schema file or a sample XML file.

The center pane, or the canvas, is the place where you drop XPath expressions and functions that can be mapped to XSLT elements.

The right pane is the target pane representing a merged view of the XSLT being created, and the target tree that represents the target schema. The target tree can be created from an XSD schema file or a sample XML file.

The grayed nodes, in italics, in the target tree represent nodes that haven't been mapped yet. These nodes are not part of the XSLT, and are displayed for convenience. Once a grayed node is mapped, it appears in regular font, and gets represented in the XSLT map.

Map View supports drag-and-drop mappings from source tree to target tree. Map View also supports XPath function calls and XSLT statements such as xsl:if and xsl:for-each.

As Map View does not separate the XSLT statements from the target tree, it is limited to the following:

• Only one XSLT template rule with the match='/' attribute is supported.

• The following XSLT statements are supported: xsl:for-each, xsl:value-of, xsl:text, xsl:if, xsl:choose/when, xsl:variable and xsl:param.

Use the XSLT View for complex XSLT statements that require separating the XSLT statements from the target tree.

The XSLT View is a more advanced mode that enables you to separate the XSLT statements from the target tree document. This enables you to create complex XSLT statements without leaving the design view. Source and target schemas are optional in the XSLT View.

The XSLT View includes the same panes as the Map View, except that the right target pane is divided into two panes. The top pane is called the XSLT pane and the lower pane is called the target pane. If no target schema is defined, then the lower pane is not shown. If no source schema is defined, the source pane is still displayed to enable you to add parameters and variables, whose values can be referenced by the XSLT.

In XSLT View, you can create any series of XSLT statements without having to intersperse these statements around target tree nodes. For instance, in the 11g mapper, all xsl:if statements had to contain a single target output node. In XSLT View, the xsl:if statement can be used anywhere, and can contain any other XSLT statement.

The XSLT View supports all XSLT 1.0 statements. The XSLT View also supports multiple template rules with or without source and target schemas. The XSLT View enables you to graphically display and edit any XSLT stylesheet, irrespective of the complexity involved.

The Components window contains all the XPath functions and XSLT elements and templates that you can use in your XSLT map.

The Components window is located at the upper right-hand corner of Oracle JDeveloper, by default. If the Components window does not appear, click Components under the Window menu to display the Components window. You can optionally choose to drag the Components window to any convenient location in the JDeveloper window. You can also resize the Components window, as desired.

The Components window organizes these functions, elements, and templates under the following categories:

• Advanced XPath:

• General XPath:

• XML:

• XSLT Elements:

• XSLT Templates:

• All Pages:

• User Defined:

• My Components:

The Properties window shows the content and properties of the item selected in the XSLT Map Editor. Some of these properties can also be edited.

The Properties window is located below the XSLT Map Editor, by default. If the Properties window does not appear, click Properties under the Window menu to display the Properties window. You can optionally choose to drag the Properties window to any convenient location within the JDeveloper window. You can also resize the Properties window, as desired.

The Properties window, in general, can be used to display and edit the properties of the following items:

1. From the File main menu, select New > XSL Map. Alternatively, right-click the project folder and select New > XSL Map.

   The Create XSL Map File dialog appears.

2. Under File Name, specify a name for your .xsl map file.
3. Under Directory name, select the destination directory for the .xsl file.
4. Under Sources, select Use Source Schema(s) to specify a source schema for the map.
5. Under Primary Source, click Browse to select the source schema. The Select Schema dialog box appears.
6. Choose Select Schema if you want to use an XSD schema file or WSDL file for the source schema.

   Note:

   You can alternatively use a sample XML file as the schema source.

   Select Generate from XML to generate the schema from an XML file. Select the sample file and click Open. Go to Step 9.

7. Click Browse to select a schema file and element for the source schema. The Type Chooser dialog appears.
8. Select the schema file and the corresponding element from the project schema files or project WSDL files tree. Click OK.

   If the schema or wsdl file that you need is not available in the tree, you may import a schema or wsdl file by clicking the Import Schema File or Import WSDL File button at the top right corner of the dialog.

9. Click OK in the Select Schema dialog.

   Note:

   Under Additional Sources, you can click the Add Schema button identified by the green plus icon (+) to add any additional sources in the form of parameters.

10. Select Use target schema to specify a target schema for your XSL map.
11. Click Browse to select the target schema. The Select Schema dialog appears.
12. After selecting the target schema, click OK in the Select Schema dialog.

    Note:

    When a Target Schema is used, initial element and attribute nodes may be generated in the XSLT pane depending upon the current Preferences setting.

    The default setting is to generate a root template with a match=''/'' attribute followed by all required elements and attributes in the target schema.

13. Click OK to create the XSL map file.

    Note:

    • Once the XSLT map is created you may add or replace source and target schemas by selecting the appropriate option from the context menu in the canvas pane.

      For example, you may add additional sources as parameters by selecting Add Parameter from the context menu on the source pane.

    • You may edit a source or target schema file that is being used by an XSLT Map, using JDeveloper. Upon saving the schema file, the source or target tree in the XSLT editor is automatically updated.

1. Open the Mediator Editor.
2. To the left of Routing Rules, click the + icon to open the Routing Rules panel.

   The transformation map icon is visible in the routing rules panel.

3. To the right of the Transform Using field shown in Figure 40-6, click the appropriate transformation map icon to open the Transformation Map dialog.

   Figure 40-6 Routing Rules

   
   Description of "Figure 40-6 Routing Rules"

   The appropriate Transformation Map dialog displays with options for selecting an existing transformation map (XSL) file or creating a new map file. For example, if you select the transformation map icon in the Synchronous Reply section, the dialog shown in Figure 40-7 appears.

   Figure 40-7 Reply Transformation Map Dialog

   
   Description of "Figure 40-7 Reply Transformation Map Dialog"

   If the routing rule includes a synchronous reply or fault, the Reply Transformation Map dialog or Fault Transformation Map dialog contains the Include Request in the Reply Payload option. When you enable this option, you can obtain information from the request message. The request message and the reply and fault message can consist of multiple parts, meaning you can have multiple source schemas. Callback and callback time-out transformations can also consist of multiple parts.

   Each message part includes a variable. For a reply transformation, the reply message includes a schema for the main part (the first part encountered) and an in.partname variable for each subsequent part. The include request message includes an initial.partname variable for each part.

   For example, assume the main reply part is the out1.HoustonStoreProduct schema and the reply also includes two other parts that are handled as variables, in.HoustonStoreProduct and in.HoustonStoreProduct2. The request message includes three parts that are handled as the variables initial.expense, initial.expense2, and initial.expense3. Figure 40-8 provides an example.

   Figure 40-8 Reply Part

   
   Description of "Figure 40-8 Reply Part"
4. Choose one of the following options:

   • Click the Search icon to browse for an existing XSLT map file (or accept the default value).

   • Click the Add icon, to create a new XSLT map file, and then enter a name for the file (or accept the default value).

     If the source message in the WSDL file has multiple parts, variables are used for each part, as mentioned in Step 3. When the target of a transformation has multiple parts, multiple transformation files map to these targets. In this case, Oracle Mediator's transformation dialog has a separate panel for each target part. For example, Figure 40-9 shows a request in which the target has three parts:

   Figure 40-9 Request Transformation Map Dialog

   
   Description of "Figure 40-9 Request Transformation Map Dialog"
5. Click OK.

   If you chose to create a new XSLT map, the XSLT Map Editor opens to enable you to correlate source schema elements to target schema elements.

6. Go to Introduction to the XSLT Map Editor for an overview of using the XSLT Map Editor.

1. Create a transformation mapping of input data to output data in the XSLT Map Editor.
2. Design the application to write the output data to a file using the file adapter.
3. Manually modify the XSL file and remove all mapping entries except the basic format data. For example:

   <?xml version="1.0" encoding="UTF-8" ?> 
   <xsl:stylesheet version="1.0" 
   xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu 
   nctions.Xpath20" 
   xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/" 
   xmlns:ns0="http://xmlns.oracle.com/pcbpel/adapter/file/MediaterDemo/Validation 
   UsingSchematron/WriteAccounInfoToFile/" 
   xmlns:orcl="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.fu 
   nctions.ExtFunc" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue 
   " 
   xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath" 
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
   xmlns:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.servi 
   ce.common.functions.GetRequestHeaderExtnFunction" 
   xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath" 
   xmlns:imp1="http://www.mycompany.com/MyExample/NewAccount" 
   xmlns:tns="http://oracle.com/sca/soapservice/MediaterDemo/ValidationUsingSchem 
   atron/CreateNewCustomerService" 
   xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRe 
   fXPathFunctions" 
   xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:ora="http://schemas.oracle.com/xpath/extension" 
   xmlns:inp1="http://www.mycompany.com/MyExample/NewCustomer" 
   exclude-result-prefixes="xsi xsl tns xsd inp1 ns0 imp1 plt xp20 bpws orcl dvm 
   hwf mhdr ids xref ora"> 
   </xsl:stylesheet> 
   

   While the file can still be compiled, the XSL mapping is now invalid.

4. Deploy and create an instance of the SOA composite application.

   During instance creation, an exception error occurs when the write operation fails because it did not receive any input. However, no errors are displayed during XSL transformation.

If you design a SOA composite application to pass a payload through Oracle Mediator without defining any transformation mapping or assigning any values, Oracle Mediator passes the payload through.

However, for the payload to be passed through successfully, the source and target message part names must be the same, and of the same type. Otherwise, the SOA project fails to compile. For projects that have been upgraded from 11g, the project compiles, but the target reference may fail to execute with error messages such as Input source like Null or Part not found.

The XML representation from an XSL file may differ from that used in a scenario in which a message is passed through with a transformation being performed or in which an assign activity is used, even though the XMLs are syntactically and semantically the same. For example, if you use an Oracle Mediator service component to map an inbound payload that includes an element without a namespace to an outbound payload, you may receive an empty namespace tag in the output message.

<Country xmlns="">US</Country> 

This is the correct behavior. A blank namespace, xmlns="", is automatically added.

1. Select the grayed node in the target pane.
2. Right-click the node, and select Create Node in XSLT from the context menu.

1. Right-click the node in the target pane. Select Edit Text Value from the context menu that appears.

   The Set Text dialog appears.

2. Enter the text value to be assigned to the node. Do not enclose the text in quotation marks.
3. Click OK.

   A yellow T icon appears next to the node indicating that a text value has been set for the item. If you move the mouse cursor over the node, the corresponding text appears. If the node was grayed earlier, it no longer appears gray, as the node has been added to the XSLT map.

You can add XSLT statements to handle constructs such as conditional statements (if-then-else) and iterations (for-each).

1. If the target node text is grayed, and in italics, right-click the node and select Create Node in XSLT from the context menu that appears.

   Figure 40-26 Creating Node in XSLT

   
   Description of "Figure 40-26 Creating Node in XSLT "
2. Right-click the node again and select Duplicate from the context menu that appears. The node is duplicated.

   Figure 40-27 Duplicate Contact Nodes

   
   Description of "Figure 40-27 Duplicate Contact Nodes"
3. Map the appropriate fields from the source document to the two duplicate elements.

   In the following figure, the duplicate Contact nodes in the target tree are mapped to different areas of the source document. The first Contact node is mapped to the ShipTo data. The second Contact node is mapped to the BillTo data.

   
   Description of the illustration xslt_map_duplicate_values.gif

Before mapping to target elements and attributes, the element or attribute must be explicitly added to the XSLT pane. This section contains the following topics:

• How to Add Elements and Attributes from the Target Schema

• How to Add Literal Elements and Attributes When No Target Schema Is Present

• How to Create an Empty Node in the Output Document

1. Right-click the literal element in the XSLT pane. The context menu appears.
2. Select Append Child > XSL > value-of from the context menu. The Set Attributes dialog box appears.
3. Optionally select 'disable output escaping' Attribute. Click OK.

   The xsl:value-of element is inserted.

4. Map the xsl:value-of element to a source element just as you map a literal element. This is described in the preceding section.

1. Right-click the node in the XSLT pane. Select Edit Text Value from the context menu that appears.

   The Set Text dialog appears.

2. Enter the text value to be assigned to the node. Do not enclose the text in quotation marks.
3. Click OK.

   A yellow T icon appears next to the node indicating that a text value has been set for the item. If you move the mouse cursor over the node, the corresponding text appears.

1. Right-click the literal element in the XSLT pane. The context menu appears.
2. Select Append Child > XSL > text from the context menu. The Set Attributes dialog box appears.
3. Optionally select 'disable output escaping' Attribute. Click OK.

   The xsl:text element is inserted.

4. Right-click the newly inserted xsl:text element and select Edit Text Value from the context menu that appears.

   The Set Text dialog box appears.

5. Enter the text value to be assigned Do not enclose the text in quotation marks.
6. Click OK.

   A yellow T icon appears next to the xsl:text node indicating that a text value has been set for the element. If you move the mouse cursor over the node, the corresponding text appears.

7. To change the text value at any time, right-click the xsl:text element again and select Edit Text Value from the context menu that appears.

This procedure applies to XSLT View only. XSLT statements can be added using the Components window or context menu.

1. In the XSLT pane, right-click the element to be duplicated. The context menu appears.
2. Select Insert Sibling After -> Literal Element from the context menu. The Define Element dialog appears.
3. Enter the element name and namespace of the node to be duplicated. Click OK.

You can modify the XPath expression for a mapping created from a drag and drop action between a source and target node.

XPath functions are shown in the canvas panel and can be edited in several ways. Continuing our example from the previous section (How to Add an XPath Function to an Existing XPath Expression), you set the value of the second parameter of the concat function in several ways.

There are several ways to create a new function in the XSLT canvas pane. These are described in the sections that follow.

1. Drag the left-trim and right-trim functions into the border area of the concat function.
2. Chain them as shown in Figure 40-35 by dragging lines from the output side of one function to the input side of the next function.

Chaining can also be performed by dragging and dropping a function onto a connecting link.

Figure 40-35 Chaining Functions

Description of "Figure 40-35 Chaining Functions"

1. Select the XPath expression/function icon in the Canvas pane.
2. Right-click the icon and select Delete from the context menu.

1. Code and build your functions.

   The XSLT Map Editor extension functions are coded differently than the Oracle BPEL Process Manager extension functions. Two examples are provided in the SampleExtensionFunctions.java file of the mapper-107-extension-functions sample scenario. You can download this and other samples on the Sample Code site.

   Each function must be declared as a static function. Input parameters and the returned value must be declared as one of the following types:

   • java.lang.String

   • int

   • float

   • double

   • boolean

   • oracle.xml.parser.v2.XMLNodeList

   • oracle.xml.parser.v2.XMLDocumentFragment

   The text for these functions is as follows:

   // SampleExtensionFunctions.java
   package oracle.sample;
   /*
   This is a sample XSLT Map Editor User Defined Extension Functions implementation
   class.
   */
   public class SampleExtensionFunctions
   {
      public static Double toKilograms(Double lb)
      {
         return new Double(lb.doubleValue()*0.45359237);
      }
      public static String replaceChar(String inputString, String oldChar, String
         newChar )
      {
         return inputString.replace(oldChar.charAt(0), newChar.charAt(0));
      }
   }
   

2. Create an XML extension function configuration file. This file defines the functions and their parameters.

   This file must have the name ext-mapper-xpath-functions-config.xml. See Creating User-Defined XPath Extension Functions for more information on the format of this file. The following syntax represents the functions toKilograms and replaceChar as they are coded in Step 1.

   <?xml version="1.0" encoding="UTF-8"?>
   <soa-xpath-functions version="11.1.1"
    xmlns="http://xmlns.oracle.com/soa/config/xpath" xmlns:sample=
   "http://www.oracle.com/XSL/Transform/java/oracle.sample.SampleExtensionFunctions"
    >
         <function name="sample:toKilograms">
                <className>oracle.sample.SampleExtensionFunctions</className>
                <return type="number"/>
                <params>
                       <param name="pounds" type="number"/>
                </params>
                <desc>Converts a value in pounds to kilograms</desc>
         </function>
         <function name="sample:replaceChar">
                <className>oracle.sample.SampleExtensionFunctions</className>
                <return type="string"/>
                <params>
                       <param name="inputString" type="string"/>
                       <param name="oldChar" type="string"/>
                       <param name="newChar" type="string"/>
                </params>
                <desc>Returns a new string resulting from replacing all occurrences
                      of oldChar in this string with newChar</desc>
         </function>
   </soa-xpath-functions>
   

   Some additional rules apply to the definitions of XSLT extension functions:

   • The functions need a namespace prefix and a namespace. In this sample, they are sample and http://www.oracle.com/XSL/Transform/java/oracle.sample.Sam pleExtensionFunctions.

   • The function namespace must start with http://www.oracle.com/XSL/Transform/java/ for extension functions to work with the Oracle XSLT processor.

   • The last portion of the namespace, in this sample oracle.sample.SampleExtensionFunctions, must be the fully qualified name of the Java class that implements the extension functions.

   • The types and their equivalent Java types can be used for parameter and return values:

     XML Configuration File Type Name	Java Type
     string	java.lang.String
     boolean	boolean
     number	int, float, double
     node-set	oracle.xml.parser.v2.XMLNodeList
     tree	oracle.xml.parser.v2.XMLDocumentFragment

3. Create a JAR file containing both the XML configuration file and the compiled classes. The configuration file must be contained in the META-INF directory for the JAR file. For the example in this section, the directory structure is as follows with the oracle and META-INF directories added to a JAR file:

   • oracle

     • sample (contains the class file)

   • META-INF

     • ext-mapper-xpath-functions-config.xml

   The JAR file must then be registered with Oracle JDeveloper.

4. Go to Tools > Preferences > SOA.
5. Click the Add button and navigate to and select your JAR file.
6. Restart Oracle JDeveloper.

   New functions appear in the Components window under the User Defined page in the User Defined Extension Functions group.

7. To make the functions available in the runtime environment, see How to Deploy User-Defined Functions to Runtime for details.

1. Drag and drop a complex source node to the target element in the XSLT pane. If you are using Map View, then you'd drop the source node to a node in the target pane.
2. Depending on your Auto Map Preferences, the Preferences dialog might appear. Select your Auto Map preferences, and click OK.
3. Depending on your Auto Map Preferences, the Auto Map dialog might appear. Verify the matches created by the Auto Map, and click OK.

1. In the Canvas (center) pane, right-click and select Generate Report for XSLT Map.

   The Generate Report dialog appears, as shown in Figure 40-42. If the map has defined parameters, the appropriate parameter tables appear.

   Figure 40-42 The Generate Report Dialog

   
   Description of "Figure 40-42 The Generate Report Dialog"

   For more information about the fields, see the online Help for the Generate Report dialog.

1. Right-click any node in the source pane and select Add Global Variable from the context menu. Alternatively, click the Add icon, identified by the green plus sign in the XSLT toolbar and select Add Global Variable. This option is also available on the canvas context menu under the Create option.

   The Variable dialog appears.

2. Enter a name for the variable, and an optional namespace and prefix if desired.
3. Click OK.

   The variable node appears at the top of the XSLT pane or target pane depending on whether you are using the XSLT View or Map View.

   The variable also appears in the source tree within the Variables folder. This enables you to map from the variable to XPath expressions or nodes in the target tree.

   Note:

   You cannot define a structure for the variable in the current release. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

1. Right-click an existing node in the target tree (not grayed/italicized) and select Add XSL Instruction > variable from the context menu that appears.

   The Variable dialog appears.

2. Enter a name for the variable, and an optional namespace and prefix if desired.
3. Click OK.

   The variable is added to the target tree, just above the node that you selected.

   The variable also appears in the source tree within the Variables folder. This enables you to map from the variable to XPath expressions or nodes in the target tree.

   To determine if the variable is in scope for a particular XSLT node or XPath expression, select the target tree node or XPath expression. If the variable is in scope for the target tree node or XPath expression, then the variable appears in bold in the source tree. If the variable is not in scope for the selected target tree node or XPath expression, then the variable appears disabled in the source tree.

   Only scalar variables can be defined. You cannot define the structure of a variable. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

In XSLT View, local variables are added in the same manner as other XSLT elements. See How to Add XSLT Statements for details about adding XSLT elements using the context menu or Components window.

So, for example, if you select Insert Sibling Before > XSL > Variable from the context menu of an XSLT node, you get the Variable dialog box. Enter the name of the variable, optionally specify a namespace, and click OK.

The variable appears at the appropriate place in the XSLT/target pane. You can choose to map XPath expressions to the variable to set the value of the variable.

The variable also appears in the source tree under the Variables folder. This enables you to map from the variable to other XPath expressions or XSLT nodes.

To determine if the variable is in scope for a particular XSLT node or XPath expression, select the XSLT node or XPath expression. If the variable is in scope for the XSLT node or XPath expression, then the variable appears in bold in the source tree. If the variable is not in scope for the selected XSLT node or XPath expression, then the variable appears disabled in the source tree.

Only scalar variables can be defined. You cannot define the structure of a variable. If the variable you are referencing represents a complex structure, you can reference nodes within the structure by entering the appropriate XPath expression manually.

<xsl:variable name="myVar">
  <A>
     <B>sometext</B>
  </A>
</xsl:variable>

1. Right-click any node in the source pane, and select Add Global Parameter from the context menu.

   Alternatively, click the Add icon, identified by the green plus sign, in the XSLT toolbar, and select Add Global Parameter. Figure 40-43 shows the XSLT toolbar, which resides at the top of the XSLT Map Editor.

   Figure 40-43 Adding Global Parameter from the XSLT Toolbar

   
   Description of "Figure 40-43 Adding Global Parameter from the XSLT Toolbar"

   You can also right-click anywhere on the canvas (center) pane, and select Create > Add Global Parameter from the context menu.

   The Add Parameter dialog appears. Figure 40-44 shows the Add Parameter dialog.

   Figure 40-44 Add Parameter Dialog

   
   Description of "Figure 40-44 Add Parameter Dialog"
2. Enter a Local Name for the parameter and optionally specify a namespace.

   If the parameter is a complex parameter, you can specify a schema and an element definition for the parameter. Click the Help button in the dialog to get more information on the individual fields.

3. Click OK in the Add Parameter dialog to create the parameter.

1. Right-click a blank area in the XSLT pane, and select New Named Template from the context menu. Alternatively:

   • Right-click a blank area in the canvas (center) pane, and select Create >New Named Template from the context menu.

   • Right-click any source node in the source pane, and select New Named Template from the context menu.

   • Select the Add button, identified by the green plus (+) icon, in the XSLT toolbar, and select New Named Template.

   The Add Named Template dialog appears.

2. Enter a name for the template. Optionally, set a namespace.

   You can click Help to display help on the available options in the dialog.

3. Optionally click the Add button, identified by the green plus (+) icon, to add a parameter. The Add Parameter dialog appears.
4. Enter a name for the parameter. Optionally, set a namespace.

   If the parameter is a complex parameter, you can specify a schema and an element definition for the parameter. Click the Help button in the dialog to get more information on the individual fields.

5. Click OK in the Add Parameter dialog to add the parameter.
6. Add any more parameters required for the named template.
7. Click OK in the Add Named Template dialog to create the named template.

When a named template is first created, it is opened for editing in the XSLT Map Editor. You can switch between editing the named template and editing the XSLT map by using the drop-down list in the XSLT toolbar.

Figure 40-47 shows a named template being edited in the XSLT Map Editor. The top-left hand corner has a drop-down list that lets you choose between the XSLT map and the named template (createStreet).

The source tree, any global parameters, and the named template parameters appear in the source pane on the left. The XSLT pane on the upper right represents the XSLT associated with the named template. If a target schema is used, then the target tree appears at the bottom-right corner of the editor.

Figure 40-47 Editing a Named Template

Description of "Figure 40-47 Editing a Named Template"

1. Ensure that the named template appears in the XSLT Map Editor. To switch to the named template, select the name of the named template from the drop-down list in the XSLT toolbar. See Figure 40-47 for an example.
2. Right-click a source node and select Add Parameter from the context menu. Alternatively:

   • Right-click in a blank area on the canvas (center) pane, and select Create > Add Parameter from the context menu.

   • Click the Add button, identified by the green plus (+) icon, on the XSLT toolbar. Select Add Parameter from the drop-down list that appears.

3. Specify a name for the parameter, and other details, in the Add Parameter dialog. Click the Help button in the dialog to get more information on the individual fields.
4. Click OK in the Add Parameter dialog to add the parameter.

1. Add the xsl:call-template instruction as an XSLT node. You can add the xsl:call-template instruction from the context menu or the Component window. See How to Add XSLT Statements for details about adding XSLT elements.

   The Set Attribute dialog appears.

2. Select the named template to be invoked. Click OK.

   The xsl:call-template instruction is added to the XSLT tree.The parameters (xsl:use-param instructions) are added as child nodes.

3. Map values to the xsl:with-param XSLT nodes to set the values for the parameters.

1. Use one of the following methods to invoke the New Template Rule dialog:

   • Right-click the node in the source pane that is to serve as the match node. Select New Template Rule from the context menu that appears.

   • Right-click a node in the target pane. Select New Template Rule from the context menu that appears.

   • Right-click a node in the XSLT pane. Select New Template Rule from the context menu that appears.

   • Right-click a blank area in the canvas (center) pane. Select Create > New Template Rule from the context menu that appears.

   • Click the Add icon, identified by the green plus (+) sign, on the XSLT toolbar. Select New Template Rule from the list of options that appears.

   The New Template Rule dialog appears. Figure 40-48 shows the New Template Rule dialog.

   Figure 40-48 New Template Rule Dialog

   
   Description of "Figure 40-48 New Template Rule Dialog"

   The New Template Rule dialog contains the following fields:

   • Match Node: Specifies the value for the match attribute in the xsl:template definition.

     The match attribute contains a pattern used to match a node in the input XML document. The XSLT processor executes the instructions within a template when the node it is processing matches the pattern defined in the template match attribute.

   • Initialization Section: Used to determine the content of the new template rule.

     You can choose to select Create empty template to create an xsl:template instruction with no content. Alternatively, you can select Select nodes to generate in template to view and select target schema nodes that you would like to create when the template is executed.

     The Select nodes to generate in template option is available only if a target schema is being used.

   • Search by local name: If the Select nodes to generate in template option is selected, a tree representing the target schema is displayed. This option enables you to search for a node in the target schema tree using its local name.

   The New Template Rule dialog box may have automatically populated fields, depending on the mode you choose to invoke the dialog. Table 40-1 lists the pre-populated fields corresponding to each choice. If the method of invocation is not listed, then no fields are pre-populated.

   Table 40-1 Methods of Invoking the New Template Rule Dialog

   Invoked From	Automatically Populated Information
   A node in the source pane	The Match Node is populated with the absolute path to the source node. You can edit this value, if required. The Create Emty Template option is pre-selected in the Initialization section. You may change this selection, if required.
   A node in the target pane	The Select nodes to generate in template option is pre-selected in the Initialization section and the target schema tree is displayed. The target schema node used to invoke the New Template Rule dialog is pre-selected in the target tree. You may change this selection, if desired. The Match Node field must be populated with the desired match pattern for the template.

2. Set the Match Node as desired. Here are some common examples:

   • /ns0:PurchaseOrder/ns0:ShipToContact/ns0:Region: The template executes when the processor is processing the node with this path.

   • Item: The template executes when the processor is processing any node with the name Item.

   • HighPriorityItems/Items/Item: The template executes when the processor is processing any Item node that is a child of an Items node that in turn is a child of a HighPriorityItems node.

3. Select the content desired in the Initialization section. If you know the output nodes that you would like the template to create, select the Select nodes to generate in template option, and select the output nodes from the target schema tree that is displayed. You can use the Search by local name field to search within the target schema tree. You can select multiple nodes in the target tree by clicking each desired node while holding down the Shift key.
4. Click OK in the New Template Rule dialog to create the template. A new xsl:template statement is inserted at the end of the XSLT.
5. If you do not have pre-existing apply-templates statement that invokes the template rule, then insert an appropriate apply-templates statement to invoke the template rule.

   If an apply-templates statement is not present, you can see a warning icon against the xsl:template statement and question-mark (?) icons against any nodes within the template. The following figure shows an example:

   
   Description of the illustration xslt_missing_app_temps.gif

   In general, the apply-templates statement is inserted at the position where you would like to generate the nodes contained in the template. For example, in the preceding figure, the apply-templates statement needs to be inserted at the point where the Address node and its children need to be created.

   After you insert the apply-templates statement to invoke the template rule, the warning icon and the question mark (?) icons disappear.

You can refactor code from an existing template to create a new template rule. This is useful if the template rule that is created can be reused in multiple places, as was the case with the Address template rule created in the previous section.

The Create in Template option enables you to refactor a section of XSLT instructions into a separate template that can be invoked from multiple places.

In the following example, we refactor an existing mapping to create a template rule.

In the following map, the XSLT that processes each Address element in the source is repeated for each Address node. For easier maintenance, you may want to consolidate redundant code into reusable templates. This way, if the code is later updated, you would not have to update multiple copies.

Description of the illustration xslt_ex_map.gif

In the preceding map, if the XPath concat expression that creates Street from Street1 and Street2 needs to be modified, there are two copies that would have to be modified. However, if the concat function exists in a single template that is reused to produce both Address elements, then only one concat statement needs to be modified in future.

In the following steps, we refactor the existing mapping to create a single template that processes the Address elements:

1. Make sure that you are in the XSLT View. You can click XSLT in the top right corner of the XSLT Map Editor to switch to the XSLT View.
2. Right-click the ShippedTo/Address element in the XSLT pane and select Create in Template from the context menu that appears.
   
   Description of the illustration xslt_creat_in_temp.gif

   The New Template Rule dialog appears.

   
   Description of the illustration xslt_new_temp_rule2.gif

   The Match Node is pre-populated with a suggested match pattern derived from XPath expressions contained under the selected node in the XSLT pane. The elements selected in the target schema tree are the Address node and its children. These elements would be moved to a new template rule.

3. Click OK.

   A new template rule is created and an apply-templates statement is inserted in place of the Address node. The XPath expressions defined for the elements under the Address node in the XSLT pane are updated to contain relative paths to the Address node (context node) for the new template.

   
   Description of the illustration xslt_map_sample.gif

   Next, we use this template for both the ShipTo and BillTo Address elements.

4. Double-click the new template node. The Set Attributes dialog appears.
5. Under Enter Pattern, enter Address.
   
   Description of the illustration xslt_set_attrbs.gif
6. Click OK.
7. Delete the BilledTo/Address element in the XSLT pane.
8. Right-click the BilledTo node and select Add Child > XSL > apply-templates. This creates an xsl:apply-templates statement in place of the Address node.
9. Drag a line from the BillTo/Address node in the source pane to the new BilledTo/apply-templates node in the XSLT pane.
   
   Description of the illustration xslt_map_sample2.gif

   Both BilledTo and ShippedTo Address elements are now created using a single template rule.

You can set breakpoints in the Design view of the XSLT Map Editor. This enables you to debug your XSLT map at runtime, using test data or payload.

Breakpoints appear on the breakpoint bar along the right edge of the XSLT Map Editor. You can choose to see a list of all breakpoints in the XSLT map or the SOA project.

Viewing a List of All Breakpoints in the XSLT Map

Use one of the following methods to see all breakpoints in the current XSLT map:

• Right-click anywhere in the center canvas pane and select Breakpoints from the context menu that appears.

• Right-click anywhere on the breakpoint bar and select Breakpoints from the context menu that appears.

• Click Breakpoints in the XSLT toolbar.

The Breakpoints dialog appears, listing all breakpoints in the XSLT map. If a breakpoint is currently hidden in the XSLT pane, you can navigate to it by clicking the breakpoint in the Breakpoints dialog.

You can also use the Breakpoints dialog to disable or delete one or more breakpoints. A disabled breakpoint would appear as a grey dot on the breakpoint bar.

The Valid column indicates if a breakpoint is currently valid. Breakpoints can become invalid if edits to the XSLT map makes them invalid. You can choose to delete invalid breakpoints. Alternatively, invalid breakpoints can become valid again if you undo the changes made to the XSLT map.

You can set conditions for breakpoints, so that the execution is halted only when the breakpoint condition evaluates to true.

1. Right-click the breakpoint in the Breakpoints window. Select Edit from the context menu that appears.
   The Edit XSLT Breakpoint dialog appears.
2. Under the Conditions tab, enter a conditional expression using javascript syntax.
   For example, the breakpoint below will break when the PartNum attribute in the $Part variable equals p1.
   
3. You can also choose to set a Pass Count for the condition. The pass count tells the debugger to ignore the breakpoint until it has been passed a certain number of times. After the pass count is met, the debugger breaks execution at the breakpoint.
4. Click OK to set the conditions.