TECHNICAL/IMPLEMENTATION INFORMATION
Want to know how this character sheet works? Then this section is for you. You don't need to know any of this if you're just using the sheet, but this information might help if you're trying to create your own.
=== General Introduction to Custom Sheets ===- The Hero Lab user manual includes an introduction to creating custom sheets. Please read that section!
- Hero Lab generates an XML file that contains the character data. What you have to do is provide an XSL stylesheet which Hero Lab will use to convert that XML file into an HTML file that is suitable for display in a web browser. (see http://en.wikipedia.org/wiki/XSL and http://www.w3schools.com/xsl)
- But I want to use Java/C#/etc! You don't have to use XSL; you could write a program in any language and have Hero Lab invoke it to create any output you want. However, you should stick to XSL if you intend to distribute your custom sheet to others, since it is highly portable and doesn't have the security risks and installation issues that go along with executable programs.
- But I want PDF output! See the "Tips & FAQs" section, above. It is very common for users to want a PDF version of their character sheet. The easiest way to support this is to create HTML output and then have your users 'print' the character sheet into a PDF file.
- What other technologies do I need to know? The bare minimum you need to know is XML (the format Hero Lab generates), HTML (the format you're generating) and XSL (to do the conversion from one to the other). You will almost certainly want to know CSS (commonly used to style the HTML). If you want to make your custom sheet configurable at all, you will probably need to know JavaScript. You can use any tool you're comfortable with to work with these languages, ranging from a simple text editor to a full-blown IDE (Integrated Development Environment... I use this one: http://netbeans.org/).
- Create an output.xml file, put it in the right folder, along with your XSL file. On Windows 10, this folder is \ProgramData\Hero Lab\customoutput\pathfinder\your-custom-output-folder.
- If you want to distribute your custom sheet, click "Tools -> Launch HLExport". In the dialog box that appears, click "File -> Create Custom Output Export". Select your custom output folder. This process will create an *.hl file that you can give to anyone with Hero Lab.
=== Introduction to THIS Custom Sheet ===
From a technical perspective, the thing that makes this custom sheet different [at the time of this writing] is its extensive use of JavaScript. Although the XSL parses the Hero Lab XML, it does *not* create the formatted HTML output that you see when you look at your character sheet. This is a big change from previous sheets, including previous versions of this sheet.
Instead, the XSL copies entire sections of XML into the HTML, embedding the XML within <script> blocks. When the sheet is loaded, JavaScript parses the XML to populate Objects with character data when the sheet is loaded into your web browser. More JavaScript then does all of the actual formatting.
Why is it done this way? Well, XSL is a good tool for some uses, but it can be cumbersome -- JavaScript is far more powerful. Also, differences in XSL "engines" can cause problems, and the XSL engine is embedded in Hero Lab (out of the control of the custom sheet author).
The JavaScript libraries used by this sheet are:
=== The Single-File "Requirement" ===
If you're going to distribute your custom sheet, you will probably want everything (images, scripts, css styles) to be contained in the XSL file. This isn't a strict requirement, but it will make life much easier on your users and will make your custom sheet much more reliable.
- Why does this matter? If you don't put everything in the XSL file, then these resources either need to be put into the right place on the users hard drive (an installation issue that's easy to get wrong) or they have to be reachable via the internet (which means that the sheet becomes unusable if the person looses connectivity).
- How do I embed images, scripts and css styles in my XSL file? Through the use of the "data URI" feature (see http://en.wikipedia.org/wiki/Data_URI_scheme). You will need to convert these resources to base 64; do a web search for "base64 converter online" to find sites that will do this for you.
- Isn't it confusing to work with a file that has all of these things in it? It would be. Instead, consider keeping all of these things in separate files while you're working on your sheet. Combine them into a single file right before your final round of testing, and then release the combined file.
- I want to see the source code. Can I get a copy that doesn't have everything encoded in base 64 and jammed into one file? Sure. Here you go: http://dl.dropbox.com/u/10349201/shared_src48.zip
=== Cross-Browser, Cross-OS Support ===
This is an impossibly large topic to cover in detail, so here are just a few key points:
- If you distribute your custom sheet, you have no control over the browser/OS combination your users will have.
- Base your sheet on HTML5. This limits your sheet to the current/modern browser versions, but that isn't much of a limitation.
- Be absolutely strict in your use of correct HTML/CSS syntax. Browsers will often tolerate limited incorrect syntax, but each browser tolerates *different* incorrect syntax.
- Use fonts that are commonly available across operating systems (see http://www.ampsoft.net/webdesign-l/WindowsMacFonts.html).
- Test on as many combinations of browser/OS as you possibly can. You'll be amazed at the seemingly simple things that don't work on one combination or the other.