salaminizer
Colorado Internacional
How to: view XML as customized HTML with XSLT (you only need a browser)
I've started modding recently and finally got to the point of editing the Tech XML file, which with the help of a PHP script became easier. However, checking out every field is still messy. My first idea was writing a parser with Python that would generate HTML, which seems to be a good idea, until you remember you already worked with XSL, STILL work with it and WILL work for a long time! In the end I spent more time finding out how to parse XML in Python than creating the XSL stylesheet.
Objective: from a XML file, generate an HTML file containing the fields selected in the XSL stylesheet, so we can see our Civ4 XML files in a nice way in our browser
.
What do I need?: a browser, the input file and a XSL stylesheet file.
What do I need to KNOW?: you need to know HTML and you SHOULD know XSL and/or XPath. If you don't know XSL, you'll learn basic commands in this tutorial that will probably be enough for simple tasks. I hope that after you read this tutorial you will think XSL is wonderful and will look forward to learn it
1. What is XSLT and XPath?
If you already know what they ARE, you can skip to section 2.
From W3Schools:
A XSL file is much like a CSS file, as it "intercepts" a XML file and TRANSFORM it, generating whatever content you want, plain text, another XML, HTML or XHTML, etc. With XSLT, we can reorder elements, filter anything, modify attributes and content, etc.
From the same W3Schools:
2. The root of all documents
Every stylesheet begins with <xsl:stylesheet> or <xsl:transform>, which is what defines the document as a stylesheet.
We'll create a new xsl file named "techs.xsl" and it will look like this:
I won't get into details about namespaces, but we need to add xmlns:xls in order to use XSLT elements, attributes and features (the purpose of this tutorial is getting an HTML file from a XML file, not teaching XSLT - to do your own stuff after you read this, you won't need to know about namespaces.)
I said that XSLT "intercepts" XML. To do that, we have the Template tags that match XML elements using XPath. Too complicated? Consider our CIV4TechInfos.xml:
What we want to do is intercept the Civ4TechInfos tag and manipulate every descendant (TechInfos, TechInfo, Type, OrPreReqs, PrereqTech). Our template tag must match Civ4TechInfos. NOTE: I will use a PREFIX for our matches, which will prevent us from messing with the XML file. Remember the namespaces? Imagine it as an ownership, or a context. The prefix will be the namespace that tell us that we're transforming XML from Civ4.
It goes like this:
Above we've added the xmlns:civ namespace, which is the same xmlns (XML namespace) that CIV4TechInfos.xml uses. So, when in our stylesheet, we call civ:TechInfos, it knows that we're talking about the same elements in both files. There's the xsl: output too, which defines our output content and a few options (indentation is one).
We've also added the xsl:template tag matching "/", which is the document element (the whole document). Our stylesheet now "holds" the whole document, which means we can start processing the first element from the XML file, which is Civ4TechInfos.
As you can see, the result from the XSL we have right now will be an empty table, because we "intercept" the whole document but don't process its descendants. We will know use the apply-templates command, which is again kinda self-explanatory: it picks the first descendant and finds an appropriate template for it, which means it will look for a template matching Civ4TechInfos (if it doesn't exist, it will output everything to the screen).
And that's what we'll do:
I've gone far enough to add the sort command, which will sort TechInfos descendants by iCost. This new template matches TechInfos and will apply the appropriate template to its descendants, sorting by iCost before looking for it.
3. The complete stylesheet
From now it's pretty straightforward so I'll complete our example before explaining it:
After matching TechInfos, we applied a template to the sorted TechInfo's (not TechInfos!). We defined the template which will appropriatelycrazyeye match TechInfo. Now every TechInfo will be processed by this template. Now we apply the templates to the elements we want to show on the screen: Type, iCost, bGoodyTech and the OrPrereqs. All these templates use the xsl:value-of command to output the CONTENTS of the element.
Type and OrPrereqs need special attention because we use a new command: xsl:attribute, which does exactly what it says: it adds an attribute to the preceding element. For every Type tag, we've added the name attribute and for every PrereqTech we've added a link. Just because it needed special attention doesn't mean it's NOT obvious
Now we just need to add one line to our XML file so that when we open it in our browser, we'll see the result HTML:
If you want to show other elements, all you need to do is add a xsl:apply-template command selecting the element that you want and the appropriatecrazyeye template matching it (and remember the "civ:" prefix).
And that's it. We can also do other complex stuff such as previewing iGridX and iGridY by outputting techs to a table (which I will try to do later). And of course we're not restricted to Tech files This will work with every file out there and with a bit of work you can link between different XML files and I'm looking forward to play around with the text files too.
One thing that you might have noticed: XSL is a FUNCTIONAL language, which means it works as a pipeline: it receives the XML document and outputs another document. We can use immutable variables and there's a for-each command which works much like apply-templates, and with some extensions we can use mutable variables. However, natively, XSL is meant to be fully functional.
And that's it. I didn't read everything I wrote so there might be some errors.
Note: instead of using the civ: prefix, we could have removed the xmlns attribute from CIV4TechInfos.xml. As we're working with a copy of CIV4TechInfos and have already added the xml-stylesheet, it shouldn't be a problem, however I didn't test the CIV4TechInfos with the xml-stylesheet tag, so *maybe* it works perfectly with Civ.
Below there's a reference of terms and commands you will see again if you decide to learn XPath and XSL.
Reference of XPath terms used:
Root/Document
Descendant
Preceding
Reference of XSL commands used:
And a final note: originally I did this using the open-source version of SAXON, a XML/XSL processor. There are many processors out there, which means you're not restricted to a browser. However, SAXON is ran from the command-line so I thought it would be much easier to use your favourite browser, and you can view your results from any PC with a "modern" browser too
I've started modding recently and finally got to the point of editing the Tech XML file, which with the help of a PHP script became easier. However, checking out every field is still messy. My first idea was writing a parser with Python that would generate HTML, which seems to be a good idea, until you remember you already worked with XSL, STILL work with it and WILL work for a long time! In the end I spent more time finding out how to parse XML in Python than creating the XSL stylesheet.
Objective: from a XML file, generate an HTML file containing the fields selected in the XSL stylesheet, so we can see our Civ4 XML files in a nice way in our browser
.What do I need?: a browser, the input file and a XSL stylesheet file.
What do I need to KNOW?: you need to know HTML and you SHOULD know XSL and/or XPath. If you don't know XSL, you'll learn basic commands in this tutorial that will probably be enough for simple tasks. I hope that after you read this tutorial you will think XSL is wonderful and will look forward to learn it
1. What is XSLT and XPath?
If you already know what they ARE, you can skip to section 2.
From W3Schools:
A XSL file is much like a CSS file, as it "intercepts" a XML file and TRANSFORM it, generating whatever content you want, plain text, another XML, HTML or XHTML, etc. With XSLT, we can reorder elements, filter anything, modify attributes and content, etc.
From the same W3Schools:
2. The root of all documents
Every stylesheet begins with <xsl:stylesheet> or <xsl:transform>, which is what defines the document as a stylesheet.
We'll create a new xsl file named "techs.xsl" and it will look like this:
Code:
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
</xsl:stylesheet>I won't get into details about namespaces, but we need to add xmlns:xls in order to use XSLT elements, attributes and features (the purpose of this tutorial is getting an HTML file from a XML file, not teaching XSLT - to do your own stuff after you read this, you won't need to know about namespaces.)
I said that XSLT "intercepts" XML. To do that, we have the Template tags that match XML elements using XPath. Too complicated? Consider our CIV4TechInfos.xml:
Spoiler :
What we want to do is intercept the Civ4TechInfos tag and manipulate every descendant (TechInfos, TechInfo, Type, OrPreReqs, PrereqTech). Our template tag must match Civ4TechInfos. NOTE: I will use a PREFIX for our matches, which will prevent us from messing with the XML file. Remember the namespaces? Imagine it as an ownership, or a context. The prefix will be the namespace that tell us that we're transforming XML from Civ4.
It goes like this:
Spoiler :
Above we've added the xmlns:civ namespace, which is the same xmlns (XML namespace) that CIV4TechInfos.xml uses. So, when in our stylesheet, we call civ:TechInfos, it knows that we're talking about the same elements in both files. There's the xsl: output too, which defines our output content and a few options (indentation is one).
We've also added the xsl:template tag matching "/", which is the document element (the whole document). Our stylesheet now "holds" the whole document, which means we can start processing the first element from the XML file, which is Civ4TechInfos.
As you can see, the result from the XSL we have right now will be an empty table, because we "intercept" the whole document but don't process its descendants. We will know use the apply-templates command, which is again kinda self-explanatory: it picks the first descendant and finds an appropriate template for it, which means it will look for a template matching Civ4TechInfos (if it doesn't exist, it will output everything to the screen).
And that's what we'll do:
Spoiler :
I've gone far enough to add the sort command, which will sort TechInfos descendants by iCost. This new template matches TechInfos and will apply the appropriate template to its descendants, sorting by iCost before looking for it.
3. The complete stylesheet
From now it's pretty straightforward so I'll complete our example before explaining it:
Spoiler :
After matching TechInfos, we applied a template to the sorted TechInfo's (not TechInfos!). We defined the template which will appropriately
crazyeye match TechInfo. Now every TechInfo will be processed by this template. Now we apply the templates to the elements we want to show on the screen: Type, iCost, bGoodyTech and the OrPrereqs. All these templates use the xsl:value-of command to output the CONTENTS of the element.Type and OrPrereqs need special attention because we use a new command: xsl:attribute, which does exactly what it says: it adds an attribute to the preceding element. For every Type tag, we've added the name attribute and for every PrereqTech we've added a link. Just because it needed special attention doesn't mean it's NOT obvious
Now we just need to add one line to our XML file so that when we open it in our browser, we'll see the result HTML:
Code:
<?xml version="1.0"?>
[b]<?xml-stylesheet type="text/xsl" href="techout.xsl"?>[/b]
<!-- edited with XMLSpy v2005 rel. 3 U (http://www.altova.com) by Soren Johnson (Firaxis Games) -->
<!-- edited with XMLSPY v2004 rel. 2 U (http://www.xmlspy.com) by Jon Shafer (Firaxis Games) -->
<!-- Sid Meier's Civilization 4 -->
<!-- Copyright Firaxis Games 2005 -->
<!-- -->
<!-- Tech Infos -->If you want to show other elements, all you need to do is add a xsl:apply-template command selecting the element that you want and the appropriate
crazyeye template matching it (and remember the "civ:" prefix).And that's it. We can also do other complex stuff such as previewing iGridX and iGridY by outputting techs to a table (which I will try to do later). And of course we're not restricted to Tech files
This will work with every file out there and with a bit of work you can link between different XML files and I'm looking forward to play around with the text files too.One thing that you might have noticed: XSL is a FUNCTIONAL language, which means it works as a pipeline: it receives the XML document and outputs another document. We can use immutable variables and there's a for-each command which works much like apply-templates, and with some extensions we can use mutable variables. However, natively, XSL is meant to be fully functional.
And that's it. I didn't read everything I wrote so there might be some errors.
Note: instead of using the civ: prefix, we could have removed the xmlns attribute from CIV4TechInfos.xml. As we're working with a copy of CIV4TechInfos and have already added the xml-stylesheet, it shouldn't be a problem, however I didn't test the CIV4TechInfos with the xml-stylesheet tag, so *maybe* it works perfectly with Civ.
Below there's a reference of terms and commands you will see again if you decide to learn XPath and XSL.
Reference of XPath terms used:
Root/Document
Descendant
Preceding
Reference of XSL commands used:
Code:
<xsl:stylesheet>
<xsl:template>
<xsl:output>
<xsl:value-of>
<xsl:apply-template>
<xsl:sort>And a final note: originally I did this using the open-source version of SAXON, a XML/XSL processor. There are many processors out there, which means you're not restricted to a browser. However, SAXON is ran from the command-line so I thought it would be much easier to use your favourite browser, and you can view your results from any PC with a "modern" browser too
