Second Site News #018

Second Site Version 1.7 (Build 2) Released

This is a maintenance release that fixes a few minor problems in the Version 1.7 (Build 0) release.

• Fixed a bug where the Surname Index page did not have the right links at the bottom of the page: the Master Index link was missing, replaced by a link to the Surname Index.
• Fixed a bug where source page exhibits were not included in sites that use any of the XML Formats.
• Added the Links.Include Master Index Link and Links.Include Surname Index Link properties; the Master Index and Surname Index links are now optional.

These changes, and others, are described in the Second Site Change Log.

All existing customers should download this free upgrade. If you are a registered Second Site user and the About Second Site window (Help > About command) does not show the same version number and build number as above, I recommend that you download this new version and install it. You will not lose any SDF files or sites you have already made.

You may need your registration information when you install the new version.

Personalized CDs

During testing, one of the beta testers suggested a great use for the Relationship feature. He or she—I don't remember who it was—planned to customize each copy of the next CD they distributed by setting the Subject ID for the Relationship calculator to the ID number of the recipient. In that way, everyone who received the CD would have a copy of the site that shows how they are related to the people included on the site.

Editor Window

One of the under-used features in Second Site is the Editor Window. You can open the Editor Window to edit any text property, and it is especially handy when editing long text values. The most convenient way to open the Editor Window is to press [F7] when the text cursor is in a text property.

Here's something that even experienced Second Site user's may be surprised to learn: you can use the Editor Window from many of the dialog windows that you open in Second Site. For example, if you need to key a long URL in the Edit User Link window, click on the URL textbox and press [F7] to open the Editor Window. Likewise, you can use the Editor Window in the textboxes in the Custom Index Definition and Set Flag Icon windows.

The Editor Window supports the usual Edit commands, including Undo, Cut, Copy, Paste, etc. It also supports the Paste HTML Text command, which is designed to work in conjunction with web browsers that put HTML text on the clipboard when you copy a section of a page. This can be helpful when you are trying to copy part of a web page to include on your own site.

Advanced Topic: The Second Site Include (SSI) Facility

The information in this article is out of date as of Second Site Version 2. The SSI facility still exists, but the introduction of Page Scripts has changed many of the details described below.

This article is intended for Second Site users who have made advanced customizations to the program or who want to know more about how Second Site works. You do not need to understand this article to use Second Site.

I introduced the Second Site Include (SSI) facility in Second Site version 1.7. The SSI facility makes it possible to share scripts among the template files that make up a Theme, and as a result, centralizes the logic required by the various template files.

I added the SSI facility because I needed to simplify maintenance of the template files that make up Themes. Prior to the introduction of the SSI facility, I was reluctant to add new features to Second Site if they required template file changes. Changing template files was tedious for me and for users who have created their own Themes. The average Theme includes about a dozen template files, so for me, with six Themes to maintain, any feature that affected the template files would usually mean changing six dozen files or more. Users who have defined a custom Theme would only have to change a dozen files, but they also had to figure out what the change should be, an easier task for me given my inside knowledge. As a result of adding the SSI facility, updating a Theme to take advantage of a new feature usually requires changing only a single file.

When Second Site executes the Make Site command, it looks in the template (-t) folder for SSI files (*.ssi). It reads the subroutines and functions in those files and saves them in memory. Later, when a template file is processed, such as when person_page_template.htm is used to make a person page, the scripts in the template file can call the subroutines or functions defined in any of the SSI files.

At the present time, the Themes provided with Second Site use a single SSI file, scripts.ssi, to hold all the subroutines and functions used by the template files. Users are free to add additional SSI files.

Let's look at the old and new versions of the person_page_template.htm file from the Standard Theme to demonstrate the impact of the introduction of the SSI facility. Before we do, though, let's review some of the basics of Second Site scripts and templates.

Template files contain a mixture of HTML and script statements or expressions. The <% and %> characters are used before and after script statements. Anything outside of <% and %> is assumed to be HTML and is written to the output document. Everything within the <% and %> characters is assumed to be script statements or expressions. There are a couple fundamental objects, Site and Page, that are used to access information about the site and the current page, respectively. The Site object provides access to all the properties defined in the SDF file. The Page object provides access to characteristics of the current page, and includes the Page.TextOut and Page.LineOut methods, which write text to the output file. Page.LineOut adds a carriage return to the output, Page.TextOut does not. The <%=expression%> notation is a shortcut that is exactly the same as <%Page.TextOut expression%>.

Here's the old version of the person_page_template.htm file:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<!-- Second Site Standard Theme, person_page_template.htm -->
<HEAD>
 <META NAME="Generator" CONTENT="Second Site">
 <META HTTP-EQUIV="Content-Type" CONTENT="text/html;charset=iso-8859-1">
 <LINK TYPE="text/css" REL="STYLESHEET" HREF="site.css">
 <%
   If TemplateFileExists("favicon.ico") Then
     Page.TextOut "<LINK REL=""SHORTCUT ICON"" HREF=""favicon.ico"">"
   End If
 %>
 <SCRIPT TYPE="text/javascript" SRC="browser.js"></SCRIPT>
 <SCRIPT TYPE="text/javascript" SRC="scripts.js"></SCRIPT>
 <%=Page.Styles%>
 <TITLE><%=Wrapper("", Title, " - ")%><%=Page.Title%> <%=Page.Number%></TITLE>
</HEAD>
<BODY ONLOAD="javascript:init('<%=Page.Context%>');"<%=Background%>>
<P CLASS=Header><%=SOSText("Title")%><BR><SPAN CLASS=<%=PageTitleStyle%>><%=Page.Title%> <%=Page.Number%></SPAN></P>
<P>
<%
  If Site("Links.Include Main Page Link")="1" Then
    Page.TextOut "<A CLASS=nav HREF=""index.htm"">" & Site("Page Strings.Main Page Name") & "</A> - "
  End If
%><A CLASS=nav HREF="master_index.htm"><%=Site("Page Strings.Master Index Name")%></A> - <A CLASS=nav HREF="surname_index.htm"><%=Site("Page Strings.Surname Index Name")%></A><%=Wrapper(" - ", SOSText("CustomIndexLinks"), "")%><%=Wrapper(" - ", Site.ChartLink(), "")%><%=Wrapper(" - ", SOSText("HeaderLinks"), "")%>
<%=Wrapper("<BR>", Page.PageLinks("nav", " - "), "")%>
<HR>
<BR>
<%=Page.Data%>
<BR>
<HR>
<%=Wrapper("", Page.PageLinks("nav", " - "), "<BR>")%>
<%
  If Site("Links.Include Main Page Link")="1" Then
    Page.TextOut "<A CLASS=nav HREF=""index.htm"">" & Site("Page Strings.Main Page Name") & "</A> - "
  End If
%><A CLASS=nav HREF="master_index.htm"><%=Site("Page Strings.Master Index Name")%></A> - <A CLASS=nav HREF="surname_index.htm"><%=Site("Page Strings.Surname Index Name")%></A><%=Wrapper(" - ", SOSText("CustomIndexLinks"), "")%><%=Wrapper(" - ", Site.ChartLink(), "")%><%=Wrapper(" - ", SOSText("FooterLinks"), "")%>
<%=Wrapper("<P CLASS=footing>", SOSText("Compiler"), "</P>")%>
<%=Wrapper("<P CLASS=footing>", SOSText("Build"), "</P>")%>
</BODY>
</HTML>

Here's the new version of person_page_template.htm:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<% MakeHeadTags %>
 <TITLE><%=Wrapper("", Title, " - ")%><%=Page.Title%> <%=Page.Number%></TITLE>
</HEAD>
<BODY ONLOAD="javascript:init('<%=Page.Context%>');"<%=Background%>>
<P CLASS=Header><%=SOSText("Title")%><BR><SPAN CLASS=<%=PageTitleStyle%>><%=Page.Title%> <%=Page.Number%></SPAN></P>
<% MakePageHeader %>
<HR>
<BR>
<%=Page.Data%>
<BR>
<HR>
<% MakePageFooter %>
</BODY>
</HTML>

Obviously, the new version is much shorter. In the HEAD section, the META, LINK and STYLE tags have been removed, replaced by <% MakeHeadTags %>. Similarly, in the BODY section, a mix of HTML and script has been replaced by <% MakePageHeader %> near the top and <% MakePageFooter %> near the bottom.

But where are MakeHeadTags, MakePageHeader and MakePageFooter defined?

All three are subroutines in the scripts.ssi file. Let's take a look at the MakeHeadTags subroutine.

Sub MakeHeadTags()
 Page.LineOut " <META NAME=""Generator"" CONTENT=""Second Site"">"
 Page.Lineout " <!-- Second Site Standard Theme, " & Page.Template & " -->"
 Page.LineOut " <META HTTP-EQUIV=""Content-Type"" CONTENT=""text/html;charset=iso-8859-1"">"
 Page.LineOut " <LINK TYPE=""text/css"" REL=""STYLESHEET"" HREF=""site.css"">"
 Page.LineOut " <SCRIPT TYPE=""text/javascript"" SRC=""browser.js""></SCRIPT>"
 Page.LineOut " <SCRIPT TYPE=""text/javascript"" SRC=""scripts.js""></SCRIPT>"
 If TemplateFileExists("favicon.ico") Then
     Page.LineOut "<LINK REL=""SHORTCUT ICON"" HREF=""favicon.ico"">"
 End If
 Page.TextOut Wrapper(" ", Page.Styles, "")
End Sub
 

Notice that literal tags in the old person_page_template.htm file have been changed to Page.LineOut script statements. The scripts.ssi file is not an HTML file, so it should not contain HTML tags unless they are part of quoted strings. Any HTML that you want to write to the output file (the result of processing the template) must be written by one of the two output methods. So, the first LINK tag in the old version looks like this:

<LINK TYPE="text/css" REL="STYLESHEET" HREF="site.css">

It changes to a Page.LineOut call in the new version:

Page.LineOut " <LINK TYPE=""text/css"" REL=""STYLESHEET"" HREF=""site.css"">"

In script statements, quote characters (") are used around literal text. To specify a quote that is part of literal text, rather than a delimeter, you must specify two quotes. The LINK tag output has quotes around the HTML parameters, so in the script version, those quotes are doubled.

The HEAD tag section of the old version of the person_page_template.htm file included a short section of script to add a LINK tag for the shortcut icon (aka "favicon"). The LINK tag is only added if the user has placed a favicon.ico file in the template (-t) folder. The old and new versions of the script statements are identical. Only the loction has changed: the script statements have moved from the person_page_template.htm file to the scripts.ssi file.

<%
  If Site("Links.Include Main Page Link")="1" Then
    Page.TextOut "<A CLASS=nav HREF=""index.htm"">" & _
        Site("Page Strings.Main Page Name") & "</A> - "
  End If
%>

If Site("Links.Include Main Page Link")="1" Then
  Page.TextOut "<A CLASS=nav HREF=""index.htm"">" & _
      Site("Page Strings.Main Page Name") & "</A> - "
End If

A complicated section of all the old template files was the script statements that wrote the links and other content at the top and bottom of the page, the header and footer. Here's the header portion of the person_page_template.htm file:

<%
  If Site("Links.Include Main Page Link")="1" Then
    Page.TextOut "<A CLASS=nav HREF=""index.htm"">" & _
        Site("Page Strings.Main Page Name") & "</A> - "
  End If
%><A CLASS=nav HREF="master_index.htm"><%=Site("Page Strings.Master Index Name")%></A> - <A CLASS=nav HREF="surname_index.htm"><%=Site("Page Strings.Surname Index Name")%></A><%=Wrapper(" - ", SOSText("CustomIndexLinks"), "")%><%=Wrapper(" - ", Site.ChartLink(), "")%><%=Wrapper(" - ", SOSText("HeaderLinks"), "")%>
<%=Wrapper("<BR>", Page.PageLinks("nav", " - "), "")%>

It was difficult to maintain that part of the template. The basic challenge was that Second Site supports many languages and a variety of other options that affect the links in the page header. In addition, browsers did not produce uniform spacing between the links unless all the tags were on the same text line in the HTML file. That's why one of the statements is very long: notice that the text above scrolls way to the right! Add in a confusing combination of special character sequences and the result is very difficult to read and modify. I was going to rewrite that part of all the template files and convert it to a section of pure script statements (rather than a mixture of HTML and script) but I decided to implement the SSI facility instead.

For comparison, here's the new code for writing the header section:

Sub MakePageHeader()
   Dim s, sDelim, kDelimeter
   kDelimeter = " - "
   Page.TextOut "<P STYLE=""margin:0px;"">"
   If Site("Links.Include Main Page Link")="1" Then
      Page.TextOut sDelim & "<A CLASS=nav HREF=""index.htm"">" & _
          Site("Page Strings.Main Page Name") & "</A>"
      sDelim = kDelimeter
   End If
   If Page.Template<>"master_index_template.htm" Then
      If Site("Links.Include Master Index Link")="1" Then
         Page.TextOut sDelim & "<A CLASS=nav HREF=""master_index.htm"">" & _
            Site("Page Strings.Master Index Name") & "</A>"
         sDelim = kDelimeter
      End If
   End If
   If Page.Template<>"surname_index_template.htm" Then
      If Site("Links.Include Surname Index Link")="1" Then
         Page.TextOut sDelim & "<A CLASS=nav HREF=""surname_index.htm"">" & _
             Site("Page Strings.Surname Index Name") & "</A>"
         sDelim = kDelimeter
      End If
   End If
   If MakeCustomIndexLinks(sDelim, kDelimeter)>0 Then
      sDelim = kDelimeter
   End If
   If Page.Title<>Site("Chart Strings.List Header") Then
      s = Site.ChartLink()
      If s<>"" Then
         Page.TextOut sDelim & s
      End If
      sDelim = kDelimeter
   End If
   Page.TextOut Wrapper(sDelim, SOSText("HeaderLinks"), "")
   Page.TextOut Wrapper(vbNewLine & "<BR>", Page.PageLinks("nav", " - "), "")
   Page.LineOut "</P>"
End Sub

The text above is longer than the text it replaces in the template file, but there are some important advantages:

1. These statements are formatted in a more legible manner. There are no extremely long lines. The output file will still have most of the tags on the same line, but that is controlled by the use of the Page.TextOut method, which does not append a carriage return to the output.
2. These statements do more than the statements they replace. For example, the master index link and surname index link are now optional. They were not optional in the person_page_template.htm version.
3. These statements work for all template files. The original code would only work in the person page template. For example, there are extra If statements to determine whether the script is writing HTML for the master index, the surname index, or the chart list.

Despite my preference for the new SSI approach, I am concerned that the script statements above look more complicated than they are, and that will discourage people from creating custom Themes. I believe that the script above is easier to read and understand, but some users may be scared off because it looks more like a program than the previous version.

I am not going to discuss all the script statements in the scripts.ssi file, I will explain a few and leave the rest to you.

If Site("Links.Include Main Page Link")="1"

The If statement above tests the value of the Links.Include Main Page Link property. The default method of the Site object is the Item method, which returns the value of the specified property. In this case, if the Include Main Page Link property is checked, the statements within the If block will be executed. Checkbox properties like Include Main Page Link have the value zero if they are not checked, and one if they are.

Page.TextOut sDelim & "<A CLASS=nav HREF=""index.htm"">" & _
    Site("Page Strings.Main Page Name") & "</A>"
sDelim = kDelimeter

The Page.TextOut statement follows the If statement explained above. The statement spans two source lines; the underscore at the end of the statement is a continuation character in VBScript. The ampersand (&) is a concatenation operator; the terms in the expression are spliced together to form a single string. In this case, the sDelim variable is combined with 3 other terms to make an HTML link (A) tag.

The sDelim variable deserves some explanation. It will be empty or it will be set to " - " (space-dash-space), the sequence of characters that separate header links in the Standard Theme and the value of the kDelimeter variable. sDelim is written prior to all the link (A) tags. The trick is setting sDelim to kDelimeter after the first link has been written. Setting it to kDelimeter multiple times is not a problem, so every If block that writes a link also includes the sDelim = kDelimeter statement. Using this approach, the MakePageHeader subroutine will produce the proper output no matter whether all, some, or none of the links are enabled.

If you have considered customizing a Theme to produce a site that meets a specific requirement you have, I hope this lengthy description of the SSI facility will encourage you to take the plunge! It's not as hard as it looks.

Downloads

Second Site is available via download only. See the Downloads page.

Purchases

For purchasing information, see the Purchases page.