This page updated 24 Apr 2008
Version note: Applies to TMG 6 & 7; and Second Site 2
As described in my article on Creating
a Minimalist Web Site, I have found customizing the Formats
supplied with Second Site a helpful way to obtain exactly the results I wanted
in my website. Customizing Formats is not a practice for the faint of heart.
But if you are adventuresome, and particularly if you have some experience in
working with HTML, the language of web pages, you may find this rewarding. If
all this seems too daunting, stick with the multitude of options offered within
Second Site, and leave the modification of Formats to those who by
some strange quirk of character find it entertaining.
I'm by no means an expert in HTML or XSL, nor in creating Formats for Second Site. This article does not pretend to be a comprehensive treatment of how to create Formats. Rather, it offers a few tips for those that want to experiment with modifying the Format supplied with Second Site to customize their results beyond the options available in Second Site user interface.
Formats control a specific aspect of the generated site, the layout of the genealogy information on the person pages. They tell Second Site how to arrange each data element – names, events, parents, children, sources, etc. – into narrative, columnar, bullet, or other style within the person page. Formats consist of a pair of files, with the same name except for the extension; one is .xsl and the other .xml. All Formats are stored in a folder called "Formats," which is itself a subfolder under the folder in which Second Site is installed.
Formats control whether the data extracted from the TMG files is displayed in the generated site as narratives, in columns, bullet items, or whatever. And within those styles, Formats control the flow of one data item to the next, that is, exactly how such items as subject name, lifespan, parents, events, children, and source citations are displayed. Formats can be customized by many of the options on the Second Site user interface.
First, do not edit the original Format files installed with your program. In doing so you lose the original information in those files, and if your attempts are unsuccessful you may have to reinstall the program to recover. Further, should future updates to the program include updates to the existing Formats, your modifications will be lost when the update is installed.
Custom Formats should be placed in a separate folder, known to Second Site as the "User Data Folder." This folder can be anyplace - I recommend making it a sub-folder of "My Documents," or wherever you keep your documents, for ease of including it in backups. Set up the User Data Folder by opening Second Site, but with no site definition file open. Use the File > Preferences > Set User Data Folder menu command to specify the folder you want to use.
Once you have have established your User Data Folder, open Windows Explorer and create a new subfolder under it named "Scripts." Then create a subfolder under that folder named "Formats."
For most of us, the best way to create a custom Format is to copy a standard one that is similar to what you want and then modify the copy. To do so, find the Scripts/Format folder under the Second Site installation folder, and locate the Format you want to copy. Note that there are two files with the name of the Format, one with the extension .xsl, and the other with .xml. Copy those two files into your custom Formats folder. Change the names of them to the name you want to use for your custom Format, keeping the .xsl and .sml extensions. The new Format should immediately appear on the drop-down list of Formats in the Pages > Style section.
The first question is what tool to use for editing the files. My editing of Formats has been pretty basic and I have found NotePad to be an adequate tool for the job. But more advanced editors, especially those designed for editing the various formats used in web page construction, provide some helpful aid such as color-coding the various parts of the file. They also identify line numbers which is helpful in deciphering error messages if you make a mistake in coding. There are a number of free and low-cost editors available, but I've not tried enough of them to make any recommendations.
We have seen that there are two files in each Format. The .xml file is used to control the translation of certain stings used by that format for different languages. It may be useful if you want to change a specific term used by the Format. To edit it, open it in a text editor like Notepad, and change the term for the "Site Language" you are using in the Data > Language section of Second Site.
The .xsl file contains the script that is the heart of the Format. This script tells Second Site how to generate the contents of the Person Pages for each subject that appears there. It's written in XSL, a language that has some some HTML-like formatting codes, but is more like a programming language. It has branching and looping features that will be familiar to those who have done any work with programming.
Examination of the existing file, and comparison with the output it produces, can reveal where changes can be made. The easiest changes are those involving simple formatting - font sizes, bold, etc. They are generally managed the same way as in HTML pages. But be careful with upper and lower case when editing the commands - unlike HTML, this language insists that pairs of tags be in the same case. So, for example, a <B> tag must be paired with a </B> tag, and not </b>.
If you are familiar with the flow of programming languages, you may also be able to make modifications that change the output more substantively, by rearranging the code lines. Those more proficient in XSL can make more fundamental changes, by creating new code to do produce whole new results.
Unless you are quite proficient in working with XSL, I suggest you make changes to one small section at a time and test you work as you go. When testing, either use a small Data Set, or create a Flag which marks a small number of people in a larger Data Set and use that to control which people are included. That way it doesn't take much time when you tell Second Site to make the site for each test. You can leave the Format file open in Notepad; just save the file when you are ready to test and have Second Site make the site again, then review the results in your browser.
New releases of Second Site from time to time will include changes that require revisions to customized Formats. More often, new releases will include new features that you may want to utilize in your site. The standard Formats supplied with Second Site are updated to accommodate these changes. But for those you customize you will need to make any updates yourself. John Cardinal has been very careful to document all the necessary changes. If you have created customized Formats, each time a new release of Second Site is made you need to look at the end of the Change Log for a section labeled something like "Information for Theme and Format Authors," which will identify any needed changes.
The key to being able to update your custom Formats is knowing exactly what you have modified. The easiest way to do that it document your changes as you make them by adding comments to your modified Format file. I suggest doing that in two places. First, near the top of each xsl file, John has a list of changes he has made to the standard Format. I add notes there for each change I make as well, to make it easier to later find the sections I have modified. For example, this section from my custom bullets Format:
Then, in the body of the file, where, add specific comments at the location of each change. For example, this section again from my custom bullets Format:
Note the comment codes – "<!--" and "-->" – around the added comment. These codes are also useful if you want to disable a section of the standard Format. By "commenting out" the section rather than simply removing it, you can more easily see later exactly what was removed. That makes it easier to compare your custom version to a newly updated standard Format when you want to update your custom Format to take advantage of new features. Another example from my custom bullets Format:
Here, the comment codes added before and after the standard section convert them to "comments" which are ignored when the Format is used to make a site.
This description is necessarily general because of the variety of
Formats supplied and the wide number of items one might want to customize. Success
depends on at least some knowledge of programming languages and HTML, careful
examination of the standard Format pages, and some experimentation. As I said
in the beginning of this article, if this isn't your cup of tea, leave it to
those that enjoy it.
My new book, A Primer for The Master Genealogist, is now available.
Details are available here.
Copyright 2000-2009