Creating Site Definition Files
Overview
JSite reduces the task of defining the structure of your web site to that of describing it using a hierarchical collection of plain text files with the extension .web:
And finally, each page typically has an HTML document Text.htm. This file may in turn reference other HTML documents (e.g., through hyperlinks in <a> tags) as well as images (e.g., in <img> tags). These may reside on the web site's own server or be distributed across the Internet. Images stored locally are typically reside in an images subdirectory under the directory from which they are generally referenced. JSite utilizes the same class library as our companion JDoc product to render these HTML document files within your applet.
Setting up the File Structure
The directory structure. In most cases clarity and ease of maintenance are improved by using your server's directory structure to mirror the structure of your web site, resulting in a directory tree of the form:
public_html
| |_index.html
| |_Site.web
| |_images
| |_Logo.JPG
| |_Line.JPG
| |_Home_Page_Icon.JPG
| |_[other
image files]
|
|_java
| |_[other
class directories/files]
| |
| |_symantec
[classes referenced by EarthStones' classes]
| |
| |_earthstones
| |_JSite.class
| |_...[other
EarthStones class files]
|
|_Section_X
|_Section.web
|_images
| |_Banner.JPG
| |_[other
image files]
|
|_Chapter_Y
|_Chapter.web
|_images
| |_Header.JPG
| |_[other
image files]
|
|_nn
[Page nn]
|_Text.htm
|_[other
HTML files]
|_images
|_[any
image files]
In describing how JSite works, the above directory structure will be assumed. It can, of course, be modified to suit your particular needs. What is important, particularly in managing a large web site, is maintaining some predictable organization so that new content can be added and obsolete material deleted with a minimum of confusion. The hierarchical structure suggested here facilitates this work. For example, this structure makes it readily apparent what files can be deleted when an entire section or chapter becomes obsolete.
This matter is complicated, however, by the complex web of connections made possible by hyperlinks: The chapter you delete because it is obsolete (or move to a new position in the directory structure) may in turn have pages linked to many other web pages. There is simply no manual way to keep track of this web of links. Web management software such as Microsoft's Front PageTM or a comparable product is a godsend for this job. Finally, note that changes made to the directory structure must be reflected not only in any referenced HTML document but also in EarthStones .web files. For example, changing a chapter's directory name requires that its chapter_id be modified accordingly in its Section.web file. This process can be automated somewhat by using the Find in Files feature of many editors (including Symantec's VisualCafeTM).
A note about paths and URLs. Part of the power of the world wide web is that a unique, absolute URL (also referred to as a fully qualified web address starting with a protocol specifier such as http://) allows anyone (who has the appropriate permissions) to access a particular document located on some server in some distant corner of the globe. When setting up a website, on the other hand, this ability to pinpoint a particular file location in the whole world becomes a liability in the very common event that you wish to move the website from one server or development environment to the next. To make such portability possible without extensive recoding, absolute URLs should be used only to refer to files located outside the site itself. Within the website, only relative URLs should be employed.
This raises the question: relative to what? As described elsewhere, JDoc assumes that file references are relative to the HTML document in which the tag containing the URL reference resides. For example, assume that the file public_html/Home/Contents/01/Text.htm contains the following hyperlink tag:
<a href="../../../Portfolio/Spirits_in/04/Text.htm">Go to Portfolio</a>
Any HTML viewer (including JDoc) will expect to find a file public_html/Portfolio/Spirits_in/04/Text.htm to which it can navigate when the link is clicked. Or, suppose that the same file contains this <img> tag:
<img src="images/MyImage.jpg" ... >
Here the relative path will be interpreted as pointing to the file public_html/Home/Contents/01/images/MyImage.jpg.
In the case of images referenced in the .web files, paths are interpreted as relative to the directory in which the .web file resides, as noted explicitly below.
Directory and file names. Finally, since many servers use Unix, it is desirable to develop a directory system compatible with that operating system. This means that (unlike the world of DOS and Windows) file and directory names are case sensitive and embedded blanks are not allowed.
Site.web
The JSite parameters that can be set either in the Site.web file or in JSite's (or JDoc's) <applet> tag have been described elsewhere (see JSite Applet Parameters).
In addition, the following parameters can be set in Site.web:
Parameter | Default Value | Comments |
name | The web site's name (e.g., EarthStones). Optional. | |
desc | A short description of the web site (e.g., at the intersection of art and technology on the world wide web). Optional. | |
baseDirectory | [various] | The web site's root directory. For applications using EarthStones' class libraries, this parameter is set by default; for example, JDocViewerApp sets the default base directory to C:/Progra~1/EarthStones/. Currently optional for applets (no default value). |
webServer | www.earthstones.net | The network location of the website's server. |
siteLogo | Logo.JPG | A logo image that will appear in the banner panel. By default, this file is assumed to be named Logo.JPG. It may be changed to any valid file name (e.g., My_Logo.gif) by specifying siteLogo. Note that this name is CASE-SENSITIVE and should not contain blanks. Regardless of its name, JSite assumes that this image file will be found in AN images (note lower case) SUBDIRECTORY UNDER THE WEBSITE'S ROOT DIRECTORY. If the expected file is not found, no error condition will result. |
rulingLine | Line.JPG | A ruling line image that will appear at the bottom of the banner panel and the top of the footer panel. By default, this file is assumed to be named Line.JPG. It may be changed to any valid file name (e.g., My_Line.gif) by specifying rulingLine. Note that this name is CASE-SENSITIVE and should not contain blanks. Regardless of its name, JSite assumes that this image file will be found in AN images (note lower case) SUBDIRECTORY UNDER THE WEBSITE'S ROOT DIRECTORY. If the expected file is not found, no error condition will result. |
footer | Default | Name of footer (e.g., "Default" or "Portfolio," etc.). A footer is assumed to appy to an entire website section (i.e., to all its chapters and pages). JSite will first look to see is there is a footer with the same name as the section's id (see below). If not, the Default footer will be used. Each footer definition begins with the line footer=footername and is followed by the list of icons that may be displayed in that footer, one icon per line, as described next. Note that not all the icons listed in a particular footer definition will appear for every chapter of the section: Each chapter may include a footericons parameter which lists the name of the icons to be displayed in the footer for that chapter. The pupose of the following icon definitions is to link the icon's name with its filename and hintstring. Each icon that will be referenced in a footericons specification in Chapter.web in must appear in the footer's definition in Site.web. |
icon | A comma-separated list of the following three values: name of icon, icon's filename, hintstring (e.g., home, Home_Page_Icon.JPG, Return to Home Page). The icon's name is arbitrary but will be used internally to refer to the icon. The icon's image filename is CASE-SENSITIVE and should not contain blanks. JSite assumes that these icon images will be found in AN images (note lower case) SUBDIRECTORY UNDER THE WEBSITE'S ROOT DIRECTORY. The hintstring is an optional string that will appear in a pop-up message and in the browser's status window when the mouse enters the icon. | |
sections | This parameter is used to indicate the beginning of the list of sections in the website. It takes no value but must appear on a separate line. The "=" sign is optional so both section and section= are acceptable. | |
[section_id] | The list of section ids, one per line. These must be the exact names of the section subdirectories under the root directory (e.g., Home or About_this_Web_Site). These names are CASE-SENSITIVE and should not contain blanks. The ids are used only internally by JSite. Each section's Section.web file will define a descriptive name to be displayed to the viewer. |
Section.web
The following parameters can be set in Section.web:
Parameter | Default Value | Comments |
name | The section's name or title (e.g., Online Portfolio). Required if automatically-generated section list is used (e.g., in table of contents or list box). | |
desc | A short description of the section (e.g., featuring sculpture and photography by Stephen Schultz). Required only if description is to appear in auto-generated table of contents. | |
sectionBanner | Banner.JPG | By default, JSite will display a section logo file (typically, including the section's name) in the website's banner panel when the user navigates to each section. The default name for this file is Banner.JPG. It may be changed to any valid file name (e.g., My_Logo.gif) by specifying sectionBanner. Note that this name is CASE-SENSITIVE and should not contain blanks. Regardless of its name, JSite assumes that this image file will be found in AN images (note lower case) SUBDIRECTORY UNDER THE SECTION'S SUBDIRECTORY. If the expected file is not found, no error condition will result. |
bannerShowHeader | false | When set, the banner will also show a chapter header logo file. By default, the chapter header is not shown. |
chapterHeader | Header.JPG | If bannerShowHeader is set for the website section, JSite will display a chapter logo file (typically, including the chapter's name) in the website's banner panel when the user navigates to each chapter. The default name for this file is Header.JPG. It may be changed to any valid file name (e.g., My_Logo.gif) by specifying chapterHeader. Note that this name is CASE-SENSITIVE and should not contain blanks. Regardless of its name, JSite assumes that this image file will be found in AN images (note lower case) SUBDIRECTORY UNDER THE CHAPTER'S SUBDIRECTORY. If the expected file is not found, no error condition will result. |
chapters | This parameter is used to indicate the beginning of the list of chapters in the section. It takes no value but must appear on a separate line. The "=" sign is optional so both chapters and chapters= are acceptable. | |
[chapter_id] | The list of chapter ids, one per line. These must be the exact names of the chapter subdirectories under the section's subdirectory (e.g., Contents or Cover_Page). These names are CASE-SENSITIVE and should not contain blanks. The ids are used only internally by JSite. Each chapter's Chapter.web file will define a descriptive name to be displayed to the viewer. |
Chapter.web
The following parameters can be set in Chapter.web:
Parameter | Default Value | Comments |
name | The chapter's name or title (e.g., About the Artist). Required if automatically-generated section list is used (e.g., in table of contents or list box). | |
footericons | A comma-separated list of up to four icon names (e.g., next, jump, view, home). Commas must be used as place holders where no icon is to appear in one of the icon locations (e.g., next, jump, , tips). Note that all icons named in a footericons list must have been previously defined by the footer and icon parameters of the Site.web file. | |
pages | This parameter is used to indicate the beginning of the list of pages in the chapter. It takes no value but must appear on a separate line. The "=" sign is optional so both pages and pages= are acceptable. | |
[page_id], [name], [image_id], [graphic_width], [text_scroll], [alt_source], [alt_scroll] | A comma separated list of page parameters, one page per line: page_id: This must be the exact name of each page's subdirectory under it's corresponding chapter subdirectory (typically 01, etc., but descriptive names can be used as well). These names are CASE-SENSITIVE and should not contain blanks. The ids are used only internally by JSite. name: The descriptive name for the page which will be displayed to the viewer. image_id: An image id defined in Images.web which will be displayed in the graphic panel when the page is loaded. If no id is specified, the default value of 1000 is used which is interpreted by JSite as a blank image. In addition, setting the image id to -1 will result in the display of a randomly-selected image, chosen from the 0,...,randomImages-1 defined in Images.web. graphic_width: The width of the graphic panel. Default value for 1024x768 screen resolution is 420. The document panel's width is set to: screenWidth - graphic_width - margins; by setting graphic_width = 0, the entire screen width is assigned to the document panel. text_scroll: A boolean value indicating whether or not the document panel will have a vertical scroll bar. The default value is true. alt_source: If specified, sets the source file for the alternate document panel displayed in place of the graphic panel. Path is assumed to be relative to the directory containing the Chapter.web file. alt_scroll: A boolean value indicating whether or not the alternate document panel will have a vertical scroll bar. The default value is false. Note: Except for page_id and name, parameters are optional and trailing commas are unnecessary; however, commas must be used as place holders where subsequent parameters are not skipped (e.g., 01, Sign, -1 is okay). |
Images.web
The following parameters can be set in Images.web:
Parameter | Default Value | Comments |
randomImages | 0 | The number of images in the subsequent image list available for random display |
images | This parameter is used to indicate the beginning of the list of images. It takes no value but must appear on a separate line. The "=" sign is optional so both images and images= are acceptable. | |
[image_id], [orient], [source], [title], [desc], [top], [width], [height], [scale] | A comma separated list of image parameters, one image per line: image_id: a unique integer reference to the image. Images for random display must be referenced by the integers 0,...,randomImages-1; skipped numbers with generate runtime errors. Additional images that will not be randomly displayed may be referenced by integers greater than 1000. The image id = 1000 is interpreted by the Page object as a blank image (see Chapter.web parameters for more). orient: the image's orientation: portrait (PRT) or landscape (LSC); the default is PTR. source: the images's source file. Path is assumed to be relative to the directory containing the Images.web file (i.e., relative to the website's root directory). title: An optional title for the image which will be wrapped as a caption under the image. Title will be printed in bold face and followed by a period. desc: An optional additional descriptive string which will be appended to the title and printed in nonbold face; if title is specified, a space separates title and desc. top: An optional distance between the top of the graphic panel and the top of the image; the default is 0. width: The image's width. If 0 or unspecified, 300 is assumed for a portrait image, 420 for a landscape image. height: The image's height. If 0 or unspecified, 420 is assumed for a portrait image, 300 for a landscape image. scale: An optional scaling factor; the default is 1.00f. Note that the f is required to specify a float value and that this scale factor is in addition to the automatic scaling that will occur for the viewer's screen resolution. Note: Except for image_id and source, parameters are optional and trailing commas are unnecessary; however, commas must be used as place holders where subsequent parameters are not skipped (e.g., 45, , myDirectory/myFile.jpg is okay). |