Terry's Second Site Tips - Customizing Formats

I have with past versions of Second Site found customizing the Formats supplied with the program to be a helpful way to obtain exactly the results I wanted in my website. However, features added with each new version have provided means for me to achieve more of the results I wanted by use of the available options within Second Site, and starting with version 5 I am no longer creating custom Formats. I urge any users who have used custom Formats in the past, or who are considering creating one, to examine the available options, many of which are described in other articles in my Second Site Section, before undertaking this task.

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.

What are Formats?

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 styles within the person page. A Format consist of a file with the extension .xsl, and optionally another with the same name but extension .xml. All standard 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. In addition, 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. The output of the Formats can be customized by use of the many options on the Second Site user interface.

Getting Started

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. The Format file has the extension .xsl. Copy this file into your custom Formats folder. Change the name of it to the name you want to use for your custom Format, keeping the .xsl extension. The new Format should immediately appear on the drop-down list of Formats in the Pages > Person Entry section.

Note that the standard Formats use a "common.xsl" file which contains some templates that are common to all the Formats. The common section is found in a sub-folder of the Formats folder, and is automatically accessed by the program when a site is made. If part of the Format you intend to modify is actually a template in the "common" file, you should copy that template into your custom Format and modify it (or write your own template from scratch in the Format file). When a template of the same name appears in both places, the one in the Format file itself is used rather than the one in the common file. Do not modify the common file, nor copy it into the User Data Folder.

There can also be a second file of the same name as the format, with the extenion .xml that may be used for data used by the .xsl Stylesheet, such as words and phrases that must be translated into multiple languages. The standard Formats supplied with Second Site do not use an .xml file.

Editing the Format Pages

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 aids 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. I use Dreamweaver, which I have because I use it to produce the part of my website not created with Second Site. It works very well for this task, but is quite expensive. There are a number of free and low-cost editors available, but I've not tried enough of them to make any recommendations.

The .xml file, if used, controls 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 find the term you want to change, then the line for it associated with the "Site Language" you are using in the Data > Language section of Second Site. Change the term in that line.

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 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 tags. While lower case is actually correct for both, XSL, unlike HTML, insists that pairs of tags be in the same case. So, for example, a tag must be paired with a tag, and not . But in most cases these changes do not require a custom Format, but are more easily done by use of Stylesheets. See my articles on Customizing with Stylesheets and Customizing with User Styles for many examples of such changes.

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 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.

Maintaining Your Custom Formats

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 changes which may affect custom Formats. 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 "Information for Customizers," which will identify any area needing updating.

For most users who make some minor modifications to a standard Format, the best strategy is to make a fresh copy of the updated standard Format, and make your modifications again. That way you know your format incorporates the latest features. The key to being able to do this 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:

<xsl:template match="parent">
 
 <li>
 <xsl:value-of select="value[@type='label']" disable-output-escaping="yes"/>
 <xsl:text>: </xsl:text><xsl:apply-templates select="pref"/>
 <xsl:apply-templates select="cref"/>
 <xsl:text> </xsl:text><xsl:apply-templates select="lifespan"/>
 </li>
</xsl:template>

Note the comment codes – "" – 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 prior custom version to a newly updated standard Format when you want to make similar changes to an updated 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.

Conclusion

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.