Custom Formats

The following information is intended for advanced users.

Overview

The Formats supported by Second Site are implemented using a combination of XML and XSLT. Users who are comfortable with XML and XSLT may choose to create a custom Format for their site. You can make modest changes relatively easily by copying one of the existing Formats and modifying the copy. You can also create a brand new Format from the ground up.

Custom Formats are also available for a small fee. Please contact John Cardinal for details.

Format Files

Each Format requires a <name>.xsl file that is an XSLT Stylesheet and defines the structure of the Format.

A Format may also use a <name>.xml file for data used by the XSLT Stylesheet, such as words and phrases that must be translated into multiple languages. The <name>.xml file is optional, and none of the Formats included with Second Site include one because all the strings they require are in the Strings section of the SDF file.

Common.xsl

Second Site includes an XSL import file named common.xsl. It is in the Scripts\Formats\Includes folder and contains templates that are used by all Formats. Users should not modify the common.xsl file or attempt to replace it. If you are creating a custom Format and you want to customize a template in the common.xsl file, you can place a customized version of the template in the main .xsl file for your Format: copy a template from common.xsl into the main .xsl file for your Format and change it there.

Please note that even though there is no <xsl:import> statement in the main .xsl file for your Format, Second Site will process the script as if there was. There are some technical hurdles involved in using <xsl:import> within the context of how Second Site uses XSLT, and to make things work properly, Second Site automates the addition of the <xsl:import> statement during the Make Site process.

User Data Folder

The Format files described above should be placed in the Scripts\Formats subfolder of the User Data Folder.

Making Person Pages

When making a site, Second Site creates an XML document for each person page. Each document is passed to the XSLT Stylesheet which transforms the XML into HTML. (The elements used by Second Site in the XML document are defined in the XML Elements section.)

Unlike many cases where XSLT is used to transform XML into HTML, the XSLT Stylesheet should not produce a complete HTML page. Second Site uses the XSLT Stylesheet to construct the content section of person pages, but the header and footer for the page are created by Page Scripts.

Other Resources

It is beyond the scope of the help pages to describe XML and XSLT in detail, but there are many educational resources for XML and XSLT on the web. w3schools has tutorials and reference guides for XML and XSLT that you may find useful. The official standards are published and maintained by the World Wide Web Consortium. See their XML and XSLT pages for more details.

I recommend XSLT Programmer's Reference, 2nd edition, by Michael Kay, for people who are serious about programming with XSLT.

Custom Formats Contributed by Users

Some users have submitted custom Formats for your use. See the Custom Formats Contributed by Users page.

Processing Instructions

XSL Stylesheets can contain processing instructions that allow documents to contain instructions for applications. Second Site supports the following processing instructions. See the XSL Stylesheets provided with Second Site for examples.

ss-detail-format

The ss-detail-format instruction allows the XSL Stylesheet to control whether TMG Tag data is written to the XML file in sentence format or in raw format, and can be used to override the user's choice for the Body Tags.Detail Format property. If the value is 0, then the XML file will contain only the raw Tag data. If the value is 1, then the XML file will contain only the output data created by processing the Tag's sentence. If the value is 2, then the XML file will contain either the raw data or the sentence data based on how the user set the Body Tags.Detail Format property.

ss-exhibit-format

If ss-exhibit-format is set to 0 ("HTML"), then the XML file will include minimal XML elements for exhibits. The elements are sufficient to produce the HTML to embed or link the exhibit. If ss-exhibit-format is set to 1 (HTML and XML) or "2" (XML only), then the XML data will include extra elements as shown below. all of the Formats included with Second Site set ss-exhibit-format to "0" (HTML); they do not use the extra exhibit elements.

ss-fields-lists

If ss-fields-lists is set to 0 (separate), then Second Site will not combine data for fields and lists into the same output section. If ss-fields-lists is set to 1 (combine), then Second Site will combine data for fields and lists into the same output section.

Formats that show fields and lists mixed together and/or using the same HTML should set ss-fields-lists to 1. Formats that must keep fields and lists separate should set ss-fields-lists to 0.

As of Second Site 5.0, the Three Columns Format has ss-fields-lists set to 1 (combined), whereas the Narrative Format has ss-fields-lists set to 0 (separate).

ss-narrative

If ss-narrative is set to 1, then Second Site will add certain elements to the XML file to improve narrative-style output.

ss-output-format

If ss-output-format is set to 0, then the XML file will include text data and HTML data, and Second Site will write name indexes and the other files supported by full-HTML sites. If ss-output-format is set to 1, then the XML file will include text data only and Second Site will write the person page data only. At this time, ss-output-format=1 is used by the Simple Text Format only.

ss-narrative

If ss-narrative is set to 1, then Second Site will add certain elements to the XML file to improve narrative-style output.

Set the processing instruction at the top of the XSL file following this example:

<?ss-exhibit-format value="1" ?>

XML Elements

Second Site converts TMG data into a set of XML elements. XML elements that are logically related, such as the set of elements used to define all the information for a single person, are nested to indicate their relationship to each other.

Please note that the XML used by Second Site was not designed for general purpose data transfer. It was designed to make it relatively easy to convert the data to HTML.

The basic structure of the XML document created by Second Site is as follows:

<page>
  <ppe>
    <pref>
      <name> ... </name>
      <gender> ... </gender>
      <flagicon> ... </flagicon>
    </pref>
    <lifespan> ... </lifespan>
    <exhibit> ... </exhibit>
    <parent>
      <pref>
         (and others as above for pref)
      </pref>
      <lifespan> ... </lifespan>
    </parent>
    <tag>
      <value type="label"> ... </value>
      <value type="date"> ... </value>
      <value type="place" id="ID-number"> ... </value>
      <value type="memo"> ... </value>
      <pref>
         (and others as above for pref)
      </pref>
      <cref/>
      <exhibit> ... </exhibit>
    </tag>
    <tag>
      (for additional events, etc.)
    </tag>
    <family>
      <partner>
        <pref>
           (and others as above for pref)
        </pref>
        <lifespan> ... </lifespan>
      </partner>
      <child>
       <pref>
        <flagicon> ... </flagicon>
         (and others as above for pref)
       </pref>
       <lifespan> ... </lifespan>
     </child>
    </family>
    <citation> ... </citation>
  </ppe>
  <ppe>
    (as above)
  </ppe>
  ...
</page>

Exhibit Elements

If the ss-exhibit-format processing instruction is set to "1" (HTML and XML) or "2" (XML only), then the XML data will include extra XML elements as shown below.

<exhibit>
  <value type="name"> ... </value>
  <value type="caption"> ... </value>
  <value type="description"> ... </value>
  <value type="width"> ... </value>
  <value type="height"> ... </value>
  <value type="mapname"> ... </value>
  <value type="maphtml"> ... </value>
  <value type="filename"> ... </value>
  <value type="htmldoc"> ... </value>
</exhibit>

Element Reference

The XML elements are defined below.

child: The CHILD element encloses all the data for a reference to a child. There will be one CHILD tag for each child of the subject. CHILD tags are enclosed by a FAMILY tag. The other parent, if known, is defined by the PARTNER tag enclosed by the same FAMILY tag.
cref n="number": The Citation REFerence element defines the source citation that applies to the enclosing element. The CREF element is enclosed by a TAG element, among others.
citation n="number": The CITATION element defines the sentence for a source citation. At least one CREF tag will reference the CITATION tag and will have a matching number.
family: The FAMILY element encloses all the data for a family. There will be one FAMILY element for every spouse/co-parent of the subject. The co-parent is defined by a PARTNER tag. If the co-parent of a child is unknown, there will be no PARTNER tag. There will be on CHILD tag for each child of the subject/couple.
exhibit type="image|text" pos="embed|link" p="0|1" id="number" isalt="0|1" isdoc="0|1": The EXHIBIT element defines the data for an exhibit. If pos=embed, then the exhibit data is either an HTML <IMG> tag or the text of the exhibit. If pos=link, then the exhibit data is a link to another page. The p ("primary") parameter is "1" for true, and "0" (zero) for false. The ID parameter is the exhibit's record number which is unique for each exhibit. If isalt=1, then the image for the exhibit has been replaced by an alternate version from the Second Site Alternage Image Folder. If isdoc=1, then the image is not a valid type to be embedded on an HTML page.

An EXHIBIT tag enclosed by the PPE tag represents a person exhibit. An EXHIBIT tag enclosed by a TAG tag represents an event exhibit.
field pos="1|2": The FIELD element encloses a set of tags that describe a logical element of data such as a TMG flag value, reference field, etc. The data is described by the enclosed VALUE tags. If pos=1 then the field is intended to be displayed near the top of the person page entry. If pos=2 then the field is intended to be displayed near the bottom of the person page entry.
gender: The GENDER element defines the gender of a person. The GENDER element is enclosed by a PREF (person reference) tag.
flagicon loc="a|b": The FLAGICON element supplies HTML that displays an icon. If loc=a, for "after", the icon HTML should be emitted after the name. If loc=b, for "before", the icon HTML should be emitted before the name. The FLAGICON element is enclosed by a PREF (person reference) tag.
name: The NAME element defines the name for a person. The NAME element is enclosed by a PREF (person reference) tag.
lifespan: The LIFESPAN element defines the lifespan (birth and death dates) for a person. The LIFESPAN element is enclosed by various tags.
page: The page element encloses all the elements in the document. In XML terms, it is the root element.
parent p="0|1" ahn="ahnentafel number": The PARENT element encloses information about one of the subject's parents, grandparents, etc. The p ("primary") parameter is "1" for true, and "0" (zero) for false. The ahnentafel number defines the relationship of the person to the subject. The XSLT Stylesheet includes a processing instruction that tells Second Site how many generations of parent's to include. The usual value is 1, and only ahnentafel numbers 2 (subject's father) and 3 (subject's mother) will be included. A PARENT tag can also be enclosed by a PARTNER tag, in which case the PARENT tag describes a parent of the spouse/co-parent.
partner: The PARTNER element encloses all the data for a spouse or co-parent. The PARTNER tag is enclosed by the FAMILY tag.
ppe: The Person Page Entry element encloses all the data for a single person. There will be one PPE tag in the XML document for each person on the current page.
pref id="ID-number" p="0|1": The Person REFerance element encloses a set of tags that describe a reference to a person. The ID parameter is the person's TMG ID number. There will be at least one PREF tag for each PPE tag, the PREF for the subject of the PPE entry. There are usually other PREF tags that describe people who shared events or relationships with the subject. Those PREF tags are enclosed by other tags such as PARTNER or CHILD. When the PREF is associated with an event tag, the PREF will include a "p" parameter, for principal, where p="1" indicates a principal and p="0" indicates a witness.
pup: The PUP element defines the HTML tags for the Second Site's Pop-Up Pedigree feature.
role: The ROLE element defines the role of a person in an event. The ROLE element is enclosed by a PREF (person reference) tag that is in turn enclosed by a TAG element.
tag type="tag type group" l="label" p="0|1" w="0|1" id="ID-number": The TAG element encloses the data for a single TMG name, event, or relationship tag. The data for the name, event, or relationship is defined by VALUE tags for the label, date, sentence, etc. The p ("primary") parameter is "1" for true, and "0" (zero) for false. The w ("witness") parameter is "1" for true, and "0" (zero) for false.
value type="value-type": The VALUE element is a general purpose data element. Depending on where it is used, it will contain a label, date, sentence, memo or place. The type parameter indicates the type. When type="place", an additional id="ID-number" parameter provides the unique place number.