Welcome to the XSLT data transformation tutorial series. In this 10 minute tutorial we will explore how the XCS Data Mapper is used to create data transformations using XSLT. By the end of the lesson you will be able to create a new XSLT mapping in the XCS Data Mapper, load a Source or Target format from an XML sample file or XML schema, build a simple transformation using XSL template, XSL value-of, XSL for-each, and XSL if elements, and test that transformation.
What you see in front of you is the XCS Data Mapper. The Data Mapper has three panels. The panel on the left represents the Source format. The panel on the right represents the Target format. The panel in the middle will be populated with the logical mapping between the Source and Target data elements.
In our example we’ll be converting between two XML formats that represent species of fish. FishXML.xml, located in the data folder, is our Source format. It has a FishXML root tag and then Fish tags with varying details about the fish – its order, family, species, common name, and the url of an available image.
FishXML.xsd is an XML schema that contains the details about the FishXML format.
SimpleFishList.xml represents our Target format. This contains very similar information to what we saw in the FishXML, but it’s structured a little bit differently. Here we have SimpleFishList as the root, and then a set of ListItems, each with a name to contain the common name of the fish, and then a sub-element with attributes for details about the order and scientific name.
Our first step is to load the Source and Target data formats. Click the Load Source Format button above the Source Format panel.
The Select Format dialogue will appear. This allows us to select a Format Reader, which will read in an artifact that describes the structure of our Source or Target format. Since we have an XML schema for our Source format, we’ll choose the XSD Format Builder.
We’ll then use the Browse button to browse to the FishXML.xsd…
And click Open.
We click Read Format and then a tree appears on the left hand side. The tree contains blue node. are nodes which have attributes and child nodes. generally they pretty interchangeable. using a good analogy you can think of it this way: node is like fruit an element apple. apple kind class=”lexicon-term”>nodes representing the structure of our FishXML.
Next, we load our Target format. We click the Open Target Format icon above the Target pane. This time we select the XML Format builder.
We navigate to our SimpleFishList.xml sample and click Open. We then click Read Format.
When prompted to use our XML file as the Target sample data click Yes.
We can now browse both our Source and Target formats in a hierarchical fashion.
Our next step is to generate the XSLT that we’ll map between the two. When we create a new mapping we see only a yellow stylesheet node. are Nodes which have attributes and child nodes. generally they pretty interchangeable. using a good analogy you can think of it this way: node is like fruit an element apple. apple kind class=”lexicon-term”>node at the root of our XSLT tree.
Clicking the XSLT view tab will show us the XSLT as we generate it. Here again, we see only an XSL stylesheet tab.
Back in the mapping view, the first thing we’ll want to do is c
hoose the root element that we’re interested in working with. The root element in our Source is FishXML, so we’ll drag that on top of the stylesheet tag.
A blue FishXML Node will appear, which corresponds to an XSL template tag being created in the XSLT view. This will match each FishXML element in the inbound document, there should only be one, and will execute the rules that are a child of that template to determine what to output.
Since we want to output a SimpleFishList tag as the root of our output document, each time we see the FishXML root of our input document, we’ll drag the SimpleFishList node on top of the FishXML node. A green node will appear in our mapping panel…
Which will correspond with the SimpleFishList output tag appearing as a child of our FishXML template.
Next, we want to create one ListItem element for each instance of a Fish element that we see in our Source. To accomplish this, we’ll take our first look at the XSLT pallet. The pallet of functions above the mapping panel allow us to manipulate the inbound data. Choose the XSLT Structures tab and the Flow Control sub-tab to locate the for-each node. Hovering over a pallet entry will provide information about how that pallet entry can be used. A for-each is used to iterate over a repeating node set from the Source.
To use this we drag the element on top of its desired parent – in this case SimpleFishList. A for-each node will appear.
We want to iterate over each Fish in the inbound document, so we now take the Fish node and drag it onto the for-each. The corresponding XSL for-each structure is created in our mapping.
Now, we need to determine what we want to output for-each fish that we encounter. Since we want to output a ListItem we drag that onto the for-each.
We also want all of the children and descendents of ListItem, so we’ll drag those over as well. Note that as nodes are dragged from the right hand side into the mapping they should always be placed onto their appropriate parent, or in their correct location.
Now, for each Fish that we encounter in the transform, we’ll be generating an empty ListItem, Name, and Classification tag. We now need to go about mapping the elements from our Source into the elements from our Target. Since we want to populate Name with the common name of the fish, we’ll take CommonName from our Source and drag it on top of the new Name node in our mapping.
Again, returning to the XSLT view, we can see our first use of the xsl value-of element. XSL value-of is used to take a value from the Source and place it into the result. The value to be taken is represented as an XPath in the Select attribute. In this case, it’s the CommonName underneath our current context, our context being Fish.
We’ll now want to repeat this process to map family, name, and order to Family, Species, and Order from the Source.
After dragging and dropping those nodes, we can review the classification tag in the XSLT. This time the syntax is a little bit different. Since we’re populating an attribute, curly brackets rather than XSL value-of tags are used. However, the semantics are basically the same. We’re taking the value of Family and using it to populate the Family attribute, just as we took CommonName to populate the Name tag. You can think of {} as a shorthand for value-of select.
Now let’s test the mapping. Click on the Testing tab.
We can load our Source format by clicking the Folder icon in the Source Format area. We’ll choose FishXML.xml and click Open.
Then, to execute the transformation we can click the gear icon in the upper toolbar.
The transformation will execute and the results will appear in the Results area.
We’re almost done. Let’s go ahead and add one simple condition to reduce our results a bit. Let’s say we’re only interested in a particular order of fish. In this case let’s grab the Perciformes.
Returning to the mapping tab, and again looking at our pallet, we can use the if function to limit what we output. Drag the if component from the Flow Control toolbar and place it between the for-each and the ListItem.
Since we want to limit based on Order, drag Order onto the if’s test attribute.
Then double click this node and enter the condition Order = ‘Perciformes’. Click Enter to accept the entry. Now we’ve added logic that ensures that any time the Order of the current Fish is Perciformes, we’re going to execute the instructions that are a child of this if.
We now need to make the ListItem a child of the if. To do that we take ListItem and drag it on top of the yellow if node.
Reviewing in the XSLT view we can now see our newly inserted XSL if, and its corresponding condition, and the Lis
tItem as its child.
Returning to the Testing Mode, we can execute the test again, and we can see slightly modified results.
This time, only Perciformes is output. Well, congratulations! That’s all there is too it. You’ve built your first XSLT transformation, and you’ve done it using the XCS Data Mapper. Things only get more interesting from here, so feel free to take a look at the other tutorials in the series.