Living Internet Web Site Template User Manual
Version 2006-01-01
(c) William Stewart 2006
–
Updates may be obtained at 
LivingInternet.com/tsourcecode.htm

Copyright (c) 2006 William Stewart.  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is available at www.gnu.org.

Contents

1.     Introduction

2.     License, Warranty, and Support

3.     Build A Gardening Web Site

          3.1   Top-Level Pages

          3.2   Chapters

          3.3   Sections

          3.4   Subsections & Pages

          3.5   Contents Pages

          3.6   Source Code Updates

          3.7   Navigation buttons

4.     Maintaining The Site

          4.1   Adding Pages

          4.2   Deleting Pages

5.     Site Development Tools

6.     Suggested Future Work

7.     Version History

Appendix A – Source Code

1.  Introduction

This manual describes the Living Internet Web Site Template, modeled on the structure and source code programming developed for LivingInternet.com.  The template provides a simple, open-source, easy method of building and maintaining web sites consisting of multiple pages of information, and provides automated support for standard web site navigation functionality including Contents, Previous, Up, and Next features.

The site described in this document is based on a gardening theme, where enough pages are defined to provide a complete working example that can be used as the starting point for development of your own web site.  The programming was designed for ease of maintenance, so the information the source code requires to process a page is mainly stored in the name of the page itself.  The only source code updates required are edits of a list of pages and a list of chapter identifiers.

The web site template and source code is built entirely from the two most standard web languages, HTML and JavaScript, so it doesn't require third-party programs to operate, and should run on any standard browser, anywhere.  

You can obtain a copy of the GNU GPL license, the current version of the source code, and a current version of this user manual at the following address:

     http://www.LivingInternet.com/tsourcecode.htm

2.  License, Warranty, Support

As specified on the title page, this manual is released under the GNU Free Documentation License.  If you update the source code, you can update this manual as well.

The source code is released under the GNU General Public License published by the Free Software Foundation, as further described in the header of the source code copied in Appendix A of this document.  

The source code and this manual are provided "as-is".  There are no warranty or support services available.  Use at your own risk.  The following web pages have more information about HTML and JavaScript:

     HTML:        http://www.livinginternet.com/w/ww_html.htm

     JavaScript:   http://www.livinginternet.com/w/ww_applets.htm

3.  Build A Gardening Web Site

This section describes how to build a web site by building a site modeled on a gardening theme.  You can then start from scratch or with a copy of the gardening site and use the same approach to create your own web site, changing page formats, location of navigation buttons, and other look and feel aspects to customize it to your own purposes.  If you have a small site, you can define a single chapter and only a few top-level pages.  Start with a few pages and test the site as you go along to make sure it is working as intended.  You can then easily add and delete pages as described in Section 4.

You can perform basic surfing of a site in progress from the storage folder on your computer simply by opening any page in a browser, enabling you to test pages and links without posting the site to the net.  However, due to programming restrictions the navigation buttons and source code will only work in their natural habitat when the site is hosted on an Internet domain such as LivingInternet.com.  If you don't have a web site, you can find low-cost starter packages from many companies large and small by searching the web for the phrase "web hosting".

If your site is more than a handful of pages, it is useful to maintain a "site index" listing the pages in order.  The index for the start of the gardening web site is shown below, where the individual pages are built as described in the following subsections.  

                Gardening Web Site Index

Created	Web Page	Folder	File Name (.htm)	
2006-01-01	About page	/	tabout	
2006-01-01	Contact information	/	tcontact	
2006-01-01	Help information	/	thelp	
2006-01-01	Links page	/	tlinks	
2006-01-05	Fruits - Contents	/	ttoc_f	
2006-01-05	Nuts - Contents	/	ttoc_n	
2006-01-05	Vegetables - Contents	/	ttoc_v	
2006-01-02	Fruits 	f	f	
2006-01-03	  Types 	f	ft	
2006-01-04	    Aggregate	f	ft_aggregate	
2006-01-04	    Multiple	f	ft_multiple	
2006-01-04	    Simple	f	ft_simple	
2006-01-04	      Fleshy	f	ft_simple_fleshy	
2006-01-04	      Dry 	f	ft_simple_dry	
2006-01-04	         Dehiscent	f	ft_simple_dry_deh	
2006-01-04	         Indehiscent	f	ft_simple_dry_ind	
2006-01-03	  Growing	f	fg	
2006-01-03	  Cooking	f	fc	
2006-01-03	  Storing	f	fs	
2006-01-02	Nuts 	n	n	
2006-01-03	  Types 	n	nt	
2006-01-03	  Growing	n	ng	
2006-01-03	  Cooking	n	nc	
2006-01-03	  Storing	n	ns	
2006-01-02	Vegetables 	v	v	
2006-01-03	  Types 	v	vt	
2006-01-03	  Growing	v	vg	
2006-01-03	  Cooking	v	vc	
2006-01-03	  Storing	v	vs	

3.1   Top-Level Pages

3.1.1  Design

Top-level pages usually relate to the overall site itself, such as Help and Contact pages.  Top-level pages reside in the top folder of the site and start with the letter "t".  

3.1.2  Example

The gardening site could start with the following top-level pages: 

Created	Web Page	Folder	File Name	
2006-01-01	About page	/	tabout	
2006-01-01	Contact information	/	tcontact	
2006-01-01	Help information	/	thelp	
2006-01-01	Links page	/	tlinks	

3.2   Chapters

3.2.1  Design

Chapters are usually used for separate subject areas of the site, although there can be only one chapter for a smaller site.  Each chapter is given an identifying one-letter name and stored in a folder with that name, all files in the chapter start with the same letter, and the chapter home page has the same one-letter name.  

Any lower-case letter can be used to identify a chapter except "t" which is reserved for top-level pages and "z" which is used as a stop character, so you can define up to 24 chapters.  The letter doesn't have to be the same as the first letter of the chapter name, but where possible it will make it easier to remember.  

3.2.2  Example

The gardening site could start with the following three chapters, each with its own folder and home page as shown below:

Created	Web Page	Folder	File Name (.htm)	
2006-01-02	Fruits Home Page	f	f	
2006-01-02	Nuts Home Page	n	n	
2006-01-02	Vegetables Home Page	v	v	

3.3   Sections

3.3.1  Design

Each chapter can have one or more sections, usually major subject areas within each chapter.  Similar to chapters, each section is associated with an identifying lower-case letter (in this case unrestricted from the 26 lower-case letters of the alphabet) that is used as the second letter of all pages in that section.  The  home page for a section therefore has a two-letter name: the chapter letter followed by the section letter.  Sections may be different between chapters.

3.3.2  Example

Although not required, the gardening site could provide uniformity for sections and use the same categories for each chapter -- Types, Growing, Cooking, Storing, each identified respectively by the letters "t", "g", "c", and "f" – with home pages for each section as shown below.

Created	Web Page	Chapter	File Name (.htm)	
2006-01-03	Types 	f	ft	
2006-01-03	Growing	f	fg	
2006-01-03	Cooking	f	fc	
2006-01-03	Storing	f	fs	
2006-01-03	Types 	n	nt	
2006-01-03	Growing	n	ng	
2006-01-03	Cooking	n	nc	
2006-01-03	Storing	n	ns	
2006-01-03	Types 	v	vt	
2006-01-03	Growing	v	vg	
2006-01-03	Cooking	v	vc	
2006-01-03	Storing	v	vs	

3.4   Subsections & Pages

3.4.1  Design

Lower-level subsections and web pages can have multiple-letter names, where levels are separated by underscores, and may be as numerous as desired.

3.4.2  Example

The gardening site could start by breaking the Types section down into three areas, the Simple type down into two areas, and identify two varieties of Dry, as shown below.

Created	Web Page	Chapter	File Name (.htm)	
2006-01-04	Aggregate	f	ft_aggregate	
2006-01-04	Multiple	f	ft_multiple	
2006-01-04	Simple	f	ft_simple	
2006-01-04	  Fleshy	f	ft_simple_fleshy	
2006-01-04	  Dry 	f	ft_simple_dry	
2006-01-04	    Dehiscent	f	ft_simple_dry_deh	
2006-01-04	    Indehiscent	f	ft_simple_dry_ind	

3.5   Contents Pages

3.5.1  Design

Contents pages for each chapter are kept in the top-level folder, and named "ttoc_" followed by the identifying first letter of the chapter.  If you don't have or need contents pages, then simply remove the Contents button from your pages.

3.5.2  Example

The gardening site could include a contents page for each chapter as shown below.

Created	Web Page	Chapter	File Name (.htm)	
2006-01-05	Fruits - Contents	/	ttoc_f	
2006-01-05	Nuts - Contents	/	ttoc_n	
2006-01-05	Vegetables - Contents	/	ttoc_v	

3.6   Source Code Updates

3.6.1  Design

The template is designed to maximize automatic operation based on the page name, and so requires minimal code updates when you update the site:

     a.  Page List.  The source code uses a list of pages called "page_list" to power the Previous and Next buttons.  It looks up the current page in the list to find out which pages are before and after.  You don't have to add new pages of the site to this list, but if a page is not included then it will be skipped by the Previous and Next functions.  If you remove a page from the site, you need to remove it from this list so that it won't get visited by mistake.

     b.  Chapter Index.  The source code uses a string of the chapter letters called "chapters_index" to recognize valid chapter pages and assemble the names of contents pages.  If you add a new chapter, you need to add its corresponding identifying letter to this string.

3.6.2  Example

     a.  Page List.  The web site index provided at the start of Section 3 has a useful list of all the site pages in the File Name column in the order of the site layout.  You can copy this column, paste it into a new document as text, and then edit it to add quotes and commas to create the required full site page list.  The list of all of the pages in the gardening example -- with the exception of the top-level pages "tlinks", "tcontact", and the contents pages -- have been assigned to "page_list" at the top of the source code in Appendix A, as shown below:

          var page_list = new Array(
               "/", "tabout", "thelp", "f", "ft", "ft_aggregate", "ft_multiple", "ft_simple",
               "ft_simple_fleshy", "ft_simple_dry", "ft_simple_dry_deh", "ft_simple_dry_ind",
               "fg", "fc", "fs", "n", "nt", "ng", "nc", "ns", "v", "vt", "vg", "vc", "vs"
          );

     b.  Chapter Index.  The list of identifying chapter letters is stored in the variable "chapters_index" in Appendix A.  The order of the letters is not important.

          chapters_index = "fnv" ;

3.7  Navigation Buttons

3.7.1  Design

You can put the navigation buttons anywhere on your pages you wish.  The buttons can be links as used in the gardening template, custom buttons, images, or other objects as long as they call the required source code function as listed below:

     Button              Function
     -----------------------------------
     Home:             Site_home ( )
     Contents:         Site_contents ( )
     Previous:         Page_previous ( )
     Up:                  Page_up ( )
     Next:               Page_next  ( )

3.7.2  Example

The garden site could take the same approach as the LivingInternet.com site, and include all five buttons on a navigation bar along the top of the window, and include three of the basic buttons for convenience at the bottom of each page.  Wherever located, each such link must directly call the corresponding JavaScript function.

4.  Maintaining The Site

The template was designed to make maintenance as simple as possible.  Since the source code uses the information in the page name to drive its operation, as long as the page is properly named and stored in the appropriate folder, then adding and deleting pages can be done quickly and easily as described below.  

4.1  Adding Pages 

You can add a new page to the site as follows:

     a.  If you wish the page to be accessible through the Previous and Next buttons, add the page name to the appropriate place in "page_list".

     b.  If you have a contents page, add a link to the new page to the contents page.

4.2  Deleting Pages

You can delete a page from the site as follows:

     a.  Remove the page name from the "page_list" array.

     b.  Remove links to the page on any contents page.

5.  Site Development Tools

Your web site can be edited with any program capable of editing HTML, including a simple text editor.  However, if you are going to create many pages with the same structure, then it will help to use a development application with a "page template" function that lets you define standard elements of a web page, such as the background, navigation bars, etc., and then apply the template to multiple pages automatically, saving considerable manual effort when the structure is updated.

Any page template should reference the site source code in a separate file, so that you only have to make changes to the programming in one place and then have it automatically propagated throughout your site, for example as follows:

     <script src = "/site_source_code.js" type = "text/JavaScript"> </script>

6.  Suggested Future Work

The LivingInternet.com web site template and source code could be developed further in several areas, some of which are described below.

6.1  Generalize Chapter and Section Names

The current version of the software is limited to 24 chapters, each with up to 26 sections.  As described in Section 3, this is because chapters use one-letter identifiers as the corresponding folder name and first letter of each file in that folder.  Similarly for sections.  To remove this restriction, the code must be generalized to enable a file like "v/vt" to become something like "vegetables/vegetables_types".  An approach is suggested below:

     a.  Perform a code analysis to determine where changes would be necessary to enable full names for chapters and sections separated by an underscore character "_", for example to change "v/vt" to "vegetables/vegetables_types".  Note that the chapter name must still be usable as a folder name across computer systems, and so needs to start with a letter and consist of only letters, numbers, hyphen, and underscore.

     c.  Either maintain the rule excluding chapter names beginning with the special characters "t" and "z", or make the code changes necessary to remove those restrictions.  For example, a code analysis may well indicate that the "z" restriction is not required, or can be eliminated with minor changes.  Changes in the use of "t" as the designator of a top-level page could involve the code changes necessary to change all top-level page names to start with the characters "top_" as in "top_help".

6.2  Make Location Independent

Currently, the source code assumes the web site is at the top-level of a domain, and so it doesn't function when the site is located at a different level such as "livinginternet.com/garden/" or in a folder on a computer.  An approach to generalize this would be to set a variable like

                 site_home = "livinginternet.com/garden/"
                                or
                 site_home = " C:\Documents\Site-Files\Garden\"

Then anywhere the source code assumes home is the default folder "/", change it to "site_home" so the site will run from any specified location.

6.3  Application Support

A wrapper application could be developed to support convenient development of web sites based on the template.  For example, providing automated management of the web site index, page_list, and chapter_index.  

7.  Version History

The following versions of the source code have been released.

Version 2006-09-01

First release.  The source code is driven by the name of each page, and automates standard web site navigation functionality, including Contents, Previous, Up, and Next features.

Appendix A - Source Code

The Living Internet source code is provided below in the JavaScript language with explanatory comments.  

//------------------------------------------------------------
//
// Living Internet Source Code, Version 2006-01-01
// Copyright (c) 1999-2006 William Stewart
//
// The Living Internet source code is free software; you can redistribute
// it and/or modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software 
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA
//
// Documentation, a copy of the GNU GPL license, and additional information
// about this software can be obtained at LivingInternet.com/tsourcecode.htm
//------------------------------------------------------------
//
// Global variables:
//
//   chapters_index:  String of single letter designators for chapters
//   current_page:  The index of the current page in "page_list"
//   page_list:  List of pages of the site
//   page_list_length:  Number of entries in "page_list"

// Misc storage variables

var s1, s2 ;
var i, j, k, m ;

// page_list is the list of pages used by the Previous and Next
// functions to determine the next and previous page.
// This is the only code update needed to add or delete a page from
// the site: add it to the proper spot in the list, or delete it.
// Note that if you don't add a page to this list, it can still be visited
// from a link, and the ^Up and Contents functions still work as normal.

var page_list = new Array(
"/","tabout","thelp","f","ft","ft_aggregate","ft_multiple","ft_simple","ft_simple_fleshy","ft_simple_dry","ft_simple_dry_deh","ft_simple_dry_ind","fg","fc","fs","n","nt","ng","nc","ns","v","vt","vg","vc","vs"
);

var page_list_length = page_list.length ;

// chapters_index is a string of the letters used to correspond to chapters, 
// used for the folder name for each chapter, and used as the first letter
// of every page name in that chapter.  The chapters_index string is used
// by the functions to recognize these letters in the names of pages, and
// to assemble the appropriate contents page on selection of the Contents
// function. If you add a new chapter, you need to add its corresponding
// letter to this string.

var chapters_index ;
chapters_index = "fnv" ;

//------------------------------------------------------------
//
// Code initialization:
//
// Reset current_page, then get the page name and set the correct page 

var current_page = 0 ;
s1 = location + "misc" ;
s2 = Get_page_name(s1) ;
Set_current_page(s2) ;

//------------------------------------------------------------
//
// Functions:
//
//   Get_page_name:  Extract the page name from the URL of the
//      current page. 
//   Page_next:  Go to the next page of the site.   
//   Page_previous:  Go to the previous page of the site.
//   Page_up:  Go to the index page one level up from the current page.
//   Set_current_page:  Cycle through page_list to find a
//      match with the current page name.
//   Set_page_name:  Format the page name, add the chapter folders and htm.
//   Site_contents:  Based on the first letter of the page name, load
//      the chapter table of contents.
//   Site_home:  Reset to the site home page.
//   
//------------------------------------------------------------

function Get_page_name(s) {

// Extract the page name from the current URL

 var i, j, k, s1, s2 ;
 
 s1 = s + "misc" ;
 i = s1.indexOf(".htm") ;
 j = i - 2 ;
 k = -1 ;

 // Run backwards from the .htm until you find a slash, or hit the
 // beginning (supposedly impossible, but the guard makes fail-safe)

 while ( (j >=0) && (k == -1)) {

  if (s1.substring(j,j+1) == "/") { k = j; } ;
  j = j - 1 ;

 }

 // Extract the page name, from after the slash to before the .htm

 var s2 = s1.substring(k+1, i) ;

 return s2 ;

}

//------------------------------------------------------------

function Page_next() {

// Load the next page of the site.
// If current_page is not at the end of page_list, add 1, otherwise
// set to the first page.  
// Ask Set_page_name to format the name of the page, then load.

 var s1 ;

 (current_page < page_list_length - 1 ) ? 
   current_page = current_page + 1 : current_page = 0 ;

 s1 = Set_page_name () ;
 location = s1 ;
 
}

//------------------------------------------------------------

function Page_previous() {

// Load the previous page of the site.
// If the current_page is not at the beginning of page_list, subtract 1, 
// otherwise set to the last page.  
// Ask Set_page_name to format the name of the page, then load.

 var s1 ;
 
 (current_page > 0) ? 
   current_page = current_page - 1 : current_page = page_list_length - 1 ;
 
 s1 = Set_page_name () ;
 location = s1 ; 

}

//------------------------------------------------------------

function Page_up() {

// Load the index page one level up from the current page:
//    ft_simple_dry.htm  -->  ft_simple.htm
//    ft                 -->  f
//    f                  -->  /
//    thelp              -->  /

 var char1, j, k, x, s1, s2, s3, s4 ;

// Get the current page, and check its first character

 s1 = page_list[current_page] ;
 char1 = s1.substring(0,1) ;

 // If a top-level page, return the home page

 if (char1 == "t") {
  current_page = 0 ;
 } else {

  // Starting from the end of the page name, search for the previous "_"

  s2 = s1 + "///" ;
  j = -1 ;
  k = 0 ;
  x = -1 ;
  while ( (j == -1) ) {
    s3 = s2.substring(k,k+1) ;
    if (s3 == "_") {
     x = k ;
    }
    if (s3 == "/") {
     j = 0 ;
    }
    k = k + 1 ;
  }

  // If found a "_", then select from the start to one char before

  if ( x != -1 ) {
   s5 = s2.substring(0,x) ;
  } else {

   // If second char of name is folder separator, then the page is a
   // one letter chapter name, so return the home page as the Up page

   s4 = s2.substring(1,2) ;
   if ( s4 == "/" ) {
    s5 = "/" ;
   } else {

    // Page must be a two letter section home page, so select the
    // first character to get the chapter home page

    s5 = s2.substring(0,1) ;
   }
  }

  // Run the page name through page_list to set current_page

  Set_current_page(s5) ;
  
 }

 // Format the page name for loading, then display

 s1 = Set_page_name () ;
 location = s1 ;
 
}

//------------------------------------------------------------

function Set_current_page(s) {

// Run through page_list to find the specified page name,
// and set current_page as an index used by other functions

 var index = 0 ;
 var i = 0 ;
 var found_page = -1 ;

 // Run to end of page_list unless page match found

 while ( (i<=page_list_length) && (found_page == -1) ) {
  if (s == page_list[i]) { found_page = i } ;
  i++ ;
 }

 // Set current_page if match found

 if (found_page != -1) { current_page = found_page; }
 
}

//------------------------------------------------------------

function Set_page_name () {

// Format the page name indicated by current_page for loading

 var s1, s2 ;
 
 s1 = page_list[current_page] ;
 s2 = s1.substring(0,1) ;

 // If the home page, then return just the home page
 
 if (s1 == "/") {
   s1 = "/" ;
 } else {

  // If not top-level page, then add chapter folder name

  if (s2 != "t") {
   s1 = s2 + "/" + s1 ;
  }

  // Add the home designator, and the htm page suffix

  s1 = "/" + s1 + ".htm" ;

 }
 
 return s1 ;
 
}

//------------------------------------------------------------

function Site_contents() {

// When on a top level page, display the main site contents page.
// When on a chapter page, display that chapter's contents page.

 var char1, i, s1, s2, s3 ;
 var on_chapter = -1 ;
 var chapter_toc = "/ttoc_" ;

 // Add the top level help page to the end of the URL, so the home
 // page will be interpreted as a top level page, as in:
 //    livinginternet.com/  -->  livinginternet.com/thelp.htm

 s1 = location + "thelp.htm" ;
 
 // Get page name and check if chapter page
 
 s2 = Get_page_name(s1) ;
 char1 = s2.substring(0,1) ;
 i = chapters_index.indexOf(char1) ;

 // If not a top-level page and confirmed as a valid chapter page, 
 // then assemble the appropriate contents page name and load

 if ((char1 != 't') & (i != -1)) {
  on_chapter = 0 ;
  chapter_toc = chapter_toc + char1 + ".htm" ;
  location = chapter_toc ;
 }

 // If not found to be a chapter page, then display site contents

 if (on_chapter == -1) { location = "/ttoc_site.htm" ; }

}

//------------------------------------------------------------

function Site_home () {

// Load the home page

 location = "/" ;

}

//
// End Living Internet source
//
//------------------------------------------------------------