Word Circuits Connection Muse
User's Guide

Version 1.0

Copyright (c) 2000 - 2005
Jean-Hugues Réty and Robert Kendall

 

Getting Started

 

Terms of Use

Connection Muse is free open-source software that you may use without charge and freely distribute to other users in accordance with the GNU General Public License. If you use the system in a published hypertext, we ask that you include a credit on the title page or credits page. For example:

"This work uses the Word Circuits Connection Muse"

We would also appreciate a link back to the Connection Muse Web site at http://www.wordcircuits.com/connect.

 

How the System Works

Connection Muse consists of two components: the Connection Library and the Connection Toolkit. The Library is a collection of JavaScript functions contained in a file called connect.js. This is the code that makes the system work and it must be loaded by any HTML document in which you wish to use Connection features. The Toolkit aids you in adding Connection elements to your hypertexts.

Connection elements (such as Conditional Links or randomly generated text) are created by inserting JavaScript functions into your text at appropriate places. When the document is viewed in a browser, the JavaScript functions you have added call the main library to perform their tasks. You can add Connection functions to your work in two ways. You can type in the JavaScript functions manually or you can use one of the Connection Tools to automatically generate the function code you need.

Many of Connection Muse's features rely upon a reading history that is created while your hypertext is read. The history is a list of all the nodes (that is, HTML pages) that have been visited during a reading and it is updated every time a new node is viewed by the browser. The history is stored in a cookie, which is a collection of data that a browser can save on the hard disk after visiting a Web site. Your readers must therefore have cookies enabled on their browsers for Connection Muse to work properly. They must also have JavaScript enabled.

 

Demos

To see Connection Muse in action, you can run the Connection Muse Demos:

The Simple Demo presents the basics of Connection Muse link and text functions.

The Component Demo presents some more sophisticated approaches. There are two windows in this demo, and you can read the story either by clicking on links in the main window or clicking on the squares in the Story Component window that appears at the left of the screen. More about this demo.

 

System Limitations

Currently a history record can safely contain a maximum of about 1,400 nodes. This limit is the result of restrictions imposed on cookie length by Microsoft Internet Explorer. To achieve this maximum history capacity, the author must create a list of node names that the system will use to generate short IDs for nodes. If the list of node names is not created, the history record will be limited to approximately 400-1,000 nodes with Microsoft Internet Explorer and about 8,000-16,000 nodes with Netscape Navigator. The exact number of nodes that can be accommodated depends upon the length of HTML filenames that are used in the hypertext. (Netscape Navigator will support a history record up to 80,000 characters long, while Microsoft Internet Explorer limits the history to 4,000 characters.) Without the list of node names, performance may also be slow with very large hypertexts.

 

Preparing Your Hypertext to Use the System

 

Basic Procedures

1. Copying the System Files

The Connection Muse system files are contained in the compressed file MuseDoc&Files1.zip in a folder called system.

It is easiest to use the system if all the HTML files that constitute your hypertext are in one directory, though the system does support multiple directories. Copy the system files connect.js and config.js into the directory where your hypertext is located (or the root directory of your hypertext if it uses multiple directories).

2. Editing the Configuration File

Open config.js in an ASCII text editor (such as Notepad in Windows or SimpleText on the Mac). This file contains the configuration information for your hypertext. Find the following line:

histCookieName = "HypertextName"

Change HypertextName to a name that represents your hypertext. The name cannot include spaces, commas, or semicolons. Be sure to leave the quotation marks intact.

You will also see a line that reads as follows:

totalNodes = 0

This tells the system how many nodes your hypertext contains. Providing this information is only necessary if you wish to use functions that determine how much of the total work has been read. If you wish to use these features, change the "0" to the total number of nodes. (Do not put quotation marks around the number.) If the number of nodes changes, you will have to manually change this number, so it is best to wait until the work is finished before you set this variable.

3. Adding the Library-Loading Code

Any HTML page that makes use of Connection System features must contain in its header the JavaScript code that loads the two system files (connect.js and config.js). Any node you want recorded in the history must also load these files. Each time connect.js is loaded, the node that loads it is added to the history. If you are working with a very large hypertext and want to use the features designed to accommodate large works, skip the rest of this section and follow the instructions in the next section, Working with Very Large Hypertexts. If your hypertext contains multiple directories, see Working with Multiple Directories.

If you are beginning a new hypertext. Use the file template.htm as a template for creating any new page that should load the system files. This is a blank HTML page that contains the code for loading the files.

If you are adding Connection System features to an existing hypertext. You must add the appropriate code to each page that should load the system files. To add this code, view your document in ASCII or HTML editing mode and insert the following text between the <HEAD> and </HEAD> tags:

<SCRIPT LANGUAGE="javascript" SRC="config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="connect.js"></SCRIPT>

The easiest way to do this is to use a text editor or HTML editor to perform a global search and replace on all the HTML files in your hypertext. Replace this text:

</HEAD>

with this text:

<SCRIPT LANGUAGE="javascript" SRC="config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="connect.js"></SCRIPT>
</HEAD>

Working with Very Large Hypertexts

Connection Muse provides special features for accommodating very large hypertexts containing more than 100 nodes or so. These features improve performance and allow history records of up to about 1400 nodes. (See System Limitations for more about history length limits.)

Short IDs

To allow more history information to be stored in the history record, the system can substitute 1-3 character IDs for full filenames. To use this feature, you must create an array (or list) containing the filename of every node in your hypertext. To do this, you must add a line to the end of your config.js file using the following syntax:

var nodesList = [filename1, filename2,...filenameN]

Replace filename1, filename2, and so on, with the names of the files in your piece. If the nodes in your piece were called "node1.htm," "node2.htm," "node3.htm," "node4.htm," and "node5.htm," the added line would look like this:

var nodesList = ["node1.htm", "node2.htm", "node3.htm", "node4.htm", "node5.htm"]

If you accidentally omit a few filenames from the list, this will not cause any errors in program execution but will reduce the amount of space available in the history record.

It's recommended that you store the short IDs in a Persistent System Frame, as described in the next section. This will guarantee the fastest performance.

If you choose not to use a Persistent System Frame, you must follow these steps: Copy the file ids.js from the frame folder (which is located inside the system folder) into the directory where your hypertext is located (or the root directory of your hypertext if it uses multiple directories). Then add the appropriate code to your hypertext so that each page loads ids.js. Open each page in ASCII or HTML editing mode and insert the following text between the <HEAD> and </HEAD> tags:

<SCRIPT LANGUAGE="javascript" SRC="ids.js"></SCRIPT>

Alternatively you can do a global search and replace to make these changes.

Persistent System Frames

To improve performance and simplify working with Short IDs or multiple directories, you can create a frame in your hypertext that is used solely to store system information so that this information won't have to be reloaded every time a new page is displayed.

If you are not using short IDs, copy all the files from the frame folder (which is located inside the system folder) into the directory where your hypertext is located (or the root directory of your hypertext if it uses multiple directories). If you are using short IDs, copy all the files from the frame_ids folder (which is also located inside the system folder) into the directory where your hypertext is located.

The file frameset.htm (or frameset_ids.htm if you are using short IDs) contains a frameset containing a Persistent System Frame. You can use this frameset as the starting file for the hypertext. (You can rename this file to anything you want.)

If you want to add a Persistent System Frame to an existing frameset rather than using frameset.htm or frameset_ids.htm, you must name the new frame "systemFrame." Since this frame will be used only to store variable values, you should locate it in an unobtrusive place, such as at the bottom of the window, and set its size to "1" (which is the smallest size value the browser will accept). This new frame must then load the file system.htm (or system_ids.htm if you are using short IDs).

start.htm will be the first node in your hypertext, so you can modify this file as appropriate. (If you rename this file, you will also have to revise the frame definition in frameset.htm or frameset_ids.htm accordingly.) Each new node in your hypertext should be created from a copy of frame_template.htm. Both start.htm and frame_template.htm are blank pages containing JavaScript in their headers.

If you are adding the Persistent System Frame to an existing hypertext, you must update all the pages in the hypertext so that each file contains the following lines of code in its header (between the <HEAD> and </HEAD> tags):

<SCRIPT LANGUAGE="javascript" SRC="config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript">var connectWin=parent.systemFrame</SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="connect-f.js"></SCRIPT>

The easiest way to do this is to use a text editor or HTML editor to perform a global search and replace on all the HTML files in your hypertext. Replace this text:

</HEAD>

with this text:

<SCRIPT LANGUAGE="javascript" SRC="config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript">var connectWin=parent.systemFrame</SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="connect-f.js"></SCRIPT>
</HEAD>

Note that if your files already contain this line:

<SCRIPT LANGUAGE="javascript" SRC="connect.js"></SCRIPT>

you should delete it. This line should only appear in system.htm.

Working with Multiple Directories

If your hypertext files are contained within more than one directory, put Connection Muse files in the root directory. Then follow the appropriate instructions below, depending upon whether or not you are using a Persistent System Frame.

When Using a Persistent System Frame

Any new pages added to subdirectories under the root directory must be created from copies of the file subdir_frame_template.htm (which is located inside the system/subdir folder). For example, if the root directory is /hypertext and you create new pages in a directory called /hypertext/chapter1, these pages must be based upon subdir_frame_template.htm.

Any pages not based upon the template must have the following lines of code added to their headers:

<SCRIPT LANGUAGE="javascript" SRC="../config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript">var connectWin=parent.systemFrame</SCRIPT>

<SCRIPT LANGUAGE="javascript" SRC="../connect-f.js"></SCRIPT>

When Not Using a Persistent System Frame

Any new pages added to subdirectories under the root directory must be created from copies of the file subdir_template.htm (which is located inside the system/subdir folder).

Any pages not based upon the template must have the following lines of code added to their headers:

<SCRIPT LANGUAGE="javascript" SRC="../config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="../connect.js"></SCRIPT>

The following line must be added to config.js:

var baseDirectory="directoryName"

directoryName should be the name of the root directory. For example, if the root directory is /hypertext, the line should read:

var baseDirectory="hypertext"

When Using More Than One Level of Subdirectory

Any pages located in a subdirectory within a subdirectory (for example, in /hypertext/chapter1/part1) must use ../../ instead of ../ in their header code, as in the following example:

<SCRIPT LANGUAGE="javascript" SRC="../../config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="../../connect.js"></SCRIPT>

Node Names

Whenever a node name is used in an array or as a parameter to a function, it should be preceded by a forward slash (/) and include the directory name if the node is not located in the root directory. For example, if node1.htm is located in /hypertext and /hypertext is the root directory, the correct name for it would be "/node1.htm" in a function such as this:

link("/node1.htm", "click here")

If node1.htm is located in /hypertext/chapter1, the correct name for it would be "/chapter1/node1.htm":

link("/chapter1/node1.htm", "click here")

Preparing an Entry Page

When a reader returns to your hypertext after having read part of it, you may want the opening page to give that reader the options of continuing the reading where it was left off or starting a new reading from the beginning. You can do this by creating an Entry Page. If the reader has not read any of the hypertext, when the Entry Page is loaded it displays a link labeled "Come In," which leads to the first node of the hypertext. If the reader is returning to the hypertext, the following message and options will be presented when the Entry Page is loaded:


You have returned to a reading in progress. Choose an option:
  • Resume the reading where you left off.
  • Start over and delete the current history.

Clicking on the first option takes the reader to the last node read during the previous reading session. Clicking on the second option deletes the history record and takes the reader to the first node of the hypertext.

The Entry Page will also present the reader with a list of filenames of all the nodes that have been read. If you create a Title Array, the titles of nodes will be included in the list as well.

Letting the reader delete the history record when starting a new reading ensures that all the functions will perform accurately and keeps the record from becoming longer than necessary and slowing down performance. It also will prevent the reader from filling up the history record when rereading a very long hypertext.

Follow these steps to create an Entry Page:

  1. Copy entry.htm (located in the system folder) into the directory that contains your hypertext. If you are using a Persistent System Frame, copy the file entry-f.htm (located in the frame folder within the system folder) instead, if it has not already been copied into your hypertext directory.

  2. Open this file in an ASCII text editor (or in HTML source editing mode in your HTML editor) and find the following line:

    firstNode="node.htm"

    Change "node.htm" to the name of the node that starts your hypertext.

  3. Copy the file entry.js into your hypertext directory.

  4. Add any desired text or formatting elements to complete the entry page.

 

Excluding Pages from the History

There may be times when you wish to use Connection functions in a page but don't want that page to be recorded as part of the history. To prevent a page from being recorded in the history record when it loads connect.js, you can add the expression "var noHistUpdate = true" to the page's header before the line that loads connect.js, in the following manner:

<SCRIPT LANGUAGE="javascript">var noHistUpdate = true</SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="config.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" SRC="connect.js"></SCRIPT>

If you are not using any of the functions that depend upon the history record, you can add the following line to the config.js file to prevent any nodes from being recorded in the history:

var noHistUpdate = true

The Connection Toolkit

The Connection Toolkit provides the easiest method for working with the system. There are two versions of the toolkit, one that is an add-on for Dreamweaver and one that runs in a Web browser. The Dreamweaver version is the more sophisticated of the two, while the browser version will work with any editor. The basic functionality of the two versions is the same.

Both versions of the toolkit generate not only function code but also explanatory comments for each function so that the workings of all Connection System elements will be fully documented within the hypertext itself. This is important for archival purposes.

Currently not all Connection System features are supported by the Toolkit. Some elements can only be implemented by manually inserting JavaScript code in your document (see Function Reference).

Connection Toolkit for Dreamweaver

Before you can use the Connection Toolkit for Dreamweaver, it must be properly installed.

To install the Toolkit for Dreamweaver:

  1. In Dreamweaver, go to the Commands menu and select Manage Extesions. This will open the Dreamweaver Extension Manager.
  2. In the Extension Manager go to the File menu and select Install Extension. Select the file ConnectionMuse1.mxp and click Install.
  3. Follow the prompts to install the Connection Muse Extensions.
  4. Close the Extension Manager when you're done.
  5. If Dreamweaver is currently running, you must exit the program and restart it before you can use the Toolkit.

To add a Connection element to your hypertext:

  1. Choose ConditionalLink in the Insert bar, either by clicking on the appropriate tab or selecting it from the pull-down menu. (You can also select the Connection elements from the Insert menu.)

  2. Position the cursor in your document at the point where you wish to add the element, then click on the icon in the Insert bar for the element you want. For all elements except Item Array, you can alternatively drag the icon from the Insert bar into your document. Do not drag Item Array into your document. (See Explanation of Individual Tools below for discussion of the different Connection elements.)

  3. Enter the requested information into the dialog box.

  4. Click OK and the element will appear in your document as a Dreamweaver JavaScript icon: (Be sure that Dreamweaver is configured to display these script icons. If they don't appear in your document, go to the Edit menu, select Preferences, click "Invisible Elements" in the Category list, and check the checkbox for Scripts.)

To change the values of an element after it has been inserted into a document:

  1. Select the element by clicking on the icon in your document.

  2. Click the Edit button in the property inspector.

  3. Edit the variable values in the JavaScript code that appears in the Script Editor.

If you don't feel comfortable with editing JavaScript code, simply delete the element and recreate it with the new values.

How Connection elements are displayed in Dreamweaver and rendered in browsers:

Every Connection element (such as a Conditional Link or random text) that you add to your document will be displayed in Dreamweaver as a JavaScript icon (). When the document is displayed in a browser, the icon will be replaced by the HTML element (text, a graphic, a link, etc.) that you specified when defining the element.

Here is an example of how a Conditional Link will appear in Dreamweaver and in a browser:

In Dreamweaver:

to follow the Conditional Link.

In a browser:

Click here to follow the Conditional Link.

Replacing conventional links with Conditional Links

The Toolkit will not convert conventional links to Conditional Links or MultiLinks. Instead you must delete the link and create a Conditional Link in its place.

 

Connection Toolkit for Browsers

To add a Connection element to your hypertext:

  1. Select a tool and load it into your browser. (You can do this by clicking on "Open browser version" in the explanation of the tool below.)

  2. Enter the requested information into the form.

  3. Click the Create Script button. The JavaScript code for the element you want will be generated in the text box at the bottom of the form.

  4. Select and copy all the text that is generated in the text box at the bottom of the form.

  5. Open your Web document in HTML view in your editing program (or open it in an ASCII text editor) and paste the text into the document at the location where you wish the new element to appear.

(Note that the scripts generated will not work properly unless the Connection Library is loaded by the HTML page.)

To change the values of an element after it has been inserted into a document:

  1. Open your Web document in HTML view in your editing program (or open it in an ASCII text editor) and find the JavaScript code for the element you wish to change. (Each element will be preceded by the tag <SCRIPT LANGUAGE="javascript"> and followed by the tag </SCRIPT>.)

  2. Edit the variable values that appear in the code.

If you don't feel comfortable with editing JavaScript code, simply delete the element and recreate it with the new values.

 

Explanation of Individual Tools

Click on an icon to open the browser version of the corresponding tool.

Conditional Links

[Open browser version]

In the form area labeled "Condition," you must specify the condition that determines what will be displayed in your document. Click on a radio button to select a condition and then fill in any necessary values.

In the remaining form fields you must specify:

  1. The link to be displayed if the condition is true.
  2. What will be displayed if the condition is false. You can choose to display the same text but without a link, to display nothing, or to display a second alternative link.

MultiLink

[Open browser version]

This tool lets you create a link with a destination that is selected on the fly from a set of specified nodes. You can specify the selection criteria that will determine which node in the set will serve as the link destination.

If you have defined an array of node names in the configuration file (config.js), you can enter the name of the array in the first field of the tool's dialog box. (See Item Arrays and Item Array Tool.) Alternatively you can type a list of node filenames into this field, separating the filenames with spaces or commas.

Click a radio button to specify whether the set of possible destination nodes should be treated as 1) a sequence in which the first node matching the selection criteria is selected or 2) a constellation of unordered nodes in which the nodes are evaluated in random order until one is found that meets the selection criteria.

Specify the selection criteria. If you include a JavaScript expression in the selection criteria, it must evaluate to either true or false. You should use "filename" as the parameter for functions that accept a single node name as a parameter. For example, to limit selected nodes to those visited less than three times, you would enter the following in the "JavaScript expression" field:

nbVisits(filename) < 3

Specify an alternative destination node in case none of the specified nodes fit the selection criteria. In the Linked Text field, type the text that will serve as the link. If you have defined a Title Array in the configuration file, you can click the radio button that specifies the linked text should be the title corresponding to the destination node.

Conditional Text

[Open browser version]

In the form area labeled "Condition" you must specify the condition that determines what will be displayed in your document. Click on a radio button to select a condition and then fill in any necessary values.

In the remaining form fields you must specify the text to be displayed if the condition is true and the text to be displayed if the condition is false. These fields will accept multiple lines and HTML tags. In fact, you can copy an entire page of HTML source code into either of these fields and the tool will format it so that it will be displayed properly in your document.

Random Text

[Open browser version]

The Random Text element randomly selects and displays a text item from among a series of text items that you specify.

To specify each text item, type it into the field labeled "Alternative text items" and then click the "Add" button. Each item you add will appear in the "List of alternative items." Separate items will appear in the list enclosed in quotation marks and separated by comments. To remove an item from the list, you must edit the list.

Item Array

[There is no browser version of this tool]

The Item Array Tool lets you automatically create sets of filenames or other items that can be used by other Connection Muse functions. (See Item Arrays.) There are two methods for adding items to an array:

To add a group of filenames to an array:

  1. In the Dreamweaver Site Panel, select the files you want to add to your array.
  2. Open the Item Array Tool by clicking on its toolbar icon.
  3. Enter a name for your array.
  4. Click the Add Selected Nodes button and the selected filenames will appear in the List of Array Items. You can edit the contents of this list if you wish.
  5. Click the Save Item Array button and your array will be added to your config.js file.
  6. Click the Close button to close the dialogue box.

To add filenames or other items one at a time:

  1. Open the Item Array Tool by clicking on its toolbar icon.
  2. Enter a name for your array.
  3. Add items to the List of Array Items either by typing in the text of each item and clicking the Add Text Button or clicking the Add Node button and selecting a filename from the popup list. You can add as many items as you wish using either method.
  4. Click the Save Item Array button and your array will be added to your config.js file.
  5. Click the Close button to close the dialogue box.

To change an item array after it has been saved, you must open config.js with the Dreamweaver text editor, find the name of your array in the file, and edit the list that follows the name.

 

Configuration Options

 

There are a number of factors you can control globally throughout the hypertext, such as the appearance of links or other elements. You control these factors by entering configuration parameters in the configuration file (config.js). Open config.js in an ASCII text editor and follow the instructions below for changing configuration options.

 

1. General Properties

History Name

histCookieName = string

The history record for your hypertext is stored in the cookie, which must be given a unique name. If your history name duplicates that of another hypertext stored on the same Web site, the history will become corrupted. To create a history name, find the following line in config.js.

histCookieName = "HypertextName"

Change HypertextName to a name that represents your hypertext. The name cannot include spaces, commas, or semicolons. Be sure to leave the quotation marks intact.

History Recording

noHistUpdate = true | false

By default, every time the Connection Library is loaded, it adds the current node to the history record. If you wish to disable history recording, add the following line to config.js:

noHistUpdate = true

Disabling history recording is recommended if you want to use only features that don't rely on the history, such as randomly displayed text or links.

Hypertext Length

totalNodes = integer

The system can determine what proportion of your total hypertext has been read and use this information to perform conditional functions. To use this feature, though, you must tell the system how many nodes your hypertext contains. To do this, find the following line in config.js:

totalNodes = 0

Change the "0" to the total number of nodes. (Do not put quotation marks around the number.) If the number of nodes changes, you will have to manually change this number, so it is best to wait until the work is finished before you define this attribute. Providing this information is only necessary if you wish to use functions that rely on how much of the total work has been read.

2. Link Appearance

You can control the way links are displayed throughout the document by adding attribute definitions to config.js. Add the line of text indicated to the end of the file.

Color

linkColorDefault = color

Specifies an HTML color value that determines the color of the linked text for all the links throughout the hypertext created with the link() function. Its value may be the name of a color enclosed in quotation marks ("red", "green", etc.), a hexadecimal color value, or a JavaScript color property (document.fgColor, document.linkColor, etc.). The default value is null, which specifies that the browser's default color will be used.

For example, the following line sets the default link color to green:

linkColorDefault = "green"

Embellishments

linkPrefixDefault = embellishment
linkSuffixDefault = embellishment

linkPrefixDefault specifies text or HTML code to be placed immediately before every link and linkSuffixDefault specifies text or HTML code to be placed immediately after every link. This can be used to put bullets in front of or brackets around all the links in a hypertext. The default value is no embellishments.

For example, the following lines enclose links in brackets:

linkPrefixDefault = "[ "
linkSuffixDefault = " ]"

This line adds a graphic before links to serve as a bullet:

linkPrefixDefault = '<IMG SRC="bullet.jpg" WIDTH="37" HEIGHT="29">'

Inactive Link Appearance

deadLinkColor = color
deadLinkStyle = "text" | "link"

When a Conditional Link becomes inactive you have the option of hiding the linked text or displaying it as unlinked text (a "dead link"). These attributes determine how these dead links are displayed throughout the hypertext. deadLinkColor sets the color of the dead link. Its value may be the name of a color enclosed in quotation marks ("red", "green", etc.), a hexadecimal color value, or a JavaScript color property (document.fgColor, document.linkColor, etc.). The default color is null, which causes the document text color to be used. If deadLinkStyle is set to "text," the dead link will be displayed as plain text. If this attribute is set to "link," the dead link will be displayed as underlined text.

For example, the following lines set dead links to appear as plain text in the same color as live links:

deadLinkColor = document.linkColor
deadLinkStyle = "text"

This line sets dead links to green:

deadLinkColor = "green"

 

3. Annotated Text

annotatedTextColorDefault = color
annotatedTextCSS = value
annotatedTextPrefixDefault = embellishment
annotatedTextSuffixDefault = embellishment

annotatedTextColorDefault sets the color of annotated text created with the display() function. Its value may be the name of a color enclosed in quotation marks ("red", "green", etc.), a hexadecimal color value, or a JavaScript color property (document.fgColor, document.linkColor, etc.). The default value is null, which causes the default link color to be used. (When the mouse pointer is moved over annotated text, a message is displayed in either a pop-up text box or the status bar.)

The following line sets annotated text to gray:

annotatedTextColorDefault = "gray"

annotatedTextCSS determines whether annotated text is underlined. The default setting is

annotatedTextCSS = "text-decoration: none"

which turns underlining off. The following setting will turn underlining on and display annotated text as if it were a link:

annotatedTextCSS = ""

annotatedTextPrefixDefault specifies text or HTML code to be placed immediately before every piece of annotated text and annotatedTextSuffixDefault specifies text or HTML code to be placed immediately after every piece of annotated text. This can be used to mark all the annotated text in a hypertext. The default value is no prefixes or suffixes.

For example, the following line puts an asterisk after all the text created with the display() function:

annotatedTextSuffixDefault = "*"

 

4. Annotations

popupTextDefault = string
popupTextColorDefault = color
popupBgColorDefault = color
popupAttDefault = values
statusTextDefault = string
deadLinkPopup = true | false
deadLinkStatus = true | false
titlePopup = true | false
titleStatus = true | false

These attributes control annotations for links or annotated text that appear as pop-up text messages or status bar messages. popupTextDefault specifies a default text string that will be displayed in a pop-up box whenever the mouse pointer is moved over a link created with link() or text created with display(). The default is "null" for no pop-up display.

popupTextColorDefault specifies the color of pop-up text. This may be either the name of a color enclosed in quotation marks ("red", "green", etc.) or a hexadecimal color value. The default value is null, which causes the text color of the document to be used. popupBgColorDefault determines the background color of the pop-up text. The default setting is "#FFFFCC", which sets the background color to pale yellow.

popupAttDefault specifies attributes that determine the appearance of the pop-up text. This text is formatted by means of an HTML table, so popupAtt will accept any string of attributes allowed by the HTML <TABLE> tag. The attributes are entered in the following format:

popupAttDefault = 'attribute1="value1" [attribute2="value2"]'

This example sets a specific width for the pop-up box:

popupAttDefault = 'width="100"'

The pop-up text feature relies on DHTML and therefore will only work in version 4 or later browsers. [Note: A bug in the current version prevents pop-up text from working properly in Netscape Navigator if the relevant link appears in text that is centered or in a table.]

statusTextDefault functions the same way as popupTextDefault, except the specified annotation appears in the browser's status bar. The default is "null" for no status bar message.

Both popupTextDefault and statusTextDefault can be overridden by specifications made in individual coals to either link() or display().

If deadLinkPopup or deadLinkStatus is set to "true," the specified pop-up or status bar annotation will be displayed by dead links. (See Link Appearance for discussion of dead links.) The default for both these attributes is "false."

If titlePopup or titleStatus is set to "true," node titles specified in a Title Array will be used as pop-up or status bar annotations for links to the corresponding nodes. The default for both these attributes is "false."

For example, the following lines specify default text to appear in the status bar and specify that node titles be displayed as pop-up annotations for live and dead links.

statusTextDefault = "Be brave. Click here."
deadLinkPopup = true
titlePopup = true

To create a Title Array, add the following line to config.js:

titleArray = new Array()

Then assign titles to file names using the following syntax:

titleArray[filename] = title

For example, the following Title Array will cause "Node 1" to be displayed as pop-up text for every link to node1.htm, "Node 2" for every link to node2.htm, and so on:

titleArray = new Array()

titleArray["node1.htm"] = "Node 1"
titleArray["node2.htm"] = "Node 2"
titleArray["node3.htm"] = "Node 3"
titleArray["node4.htm"] = "Node 4"

 

5. Item Arrays

Many of the Connection functions support multiple items as parameters, allowing you to perform such operations as randomly selecting one of several node filenames (see Function Reference). If you wish to use the same set of items repeatedly in different functions, you can define the set as an item array in config.js. You can then use the array name as a function parameter instead of entering each individual item name as a separate parameter. You can use the Item Array Tool to create item arrays.

Item arrays take the following form:

arrayName = [item1, item2, item3, ...]

For example, this line added to config.js defines an array of four node filenames:

someNodes = ["1.htm", "2.htm", "3.htm", "4.htm"]

The array name someNodes can then be used in functions instead of the names of the four nodes. For example, this code would create a link to one of the four nodes selected at random:

<SCRIPT LANGUAGE="javascript">
link(select("random", someNodes), "random link")
</SCRIPT>

Arrays of other types of items may be created for use with multi-parameter selection or evaluation functions.

 

6. Optimizing Performance

fileExtension = "htm|html"

By default, the system expects node names to end with the extension ".html" and treats ".htm" extensions as exceptions. If most or all of your HTML filenames end with the ".htm" extension, you can gain a slight increase in both performance and the capacity of the history record by adding the following line to config.js:

fileExtension = "htm"

The default setting is:

fileExtension = "html"

This fileExtension variable has no effect if you are using Short IDs.

 

7. Automatic Function Execution

executeAfterLoading()

If you wish to execute a particular function every time any node is loaded, you can declare the executeAfterLoading() function in the config.js file. This function will be executed every time connect.js is loaded. Because it is executed after the system files are loaded, it can make use of any Connection System functions. The function is declared by adding the following lines to config.js:

function executeAfterLoading() {
   JavaScript expressions
}

JavaScript expressions are the lines of JavaScript code you wish to execute. The following example updates a Table of Contents page (contents.htm) in a frame called leftFrame every time a node is loaded.

function executeAfterLoading() {
   parent.leftFrame.location = "contents.htm"
}

You cannot define parameters for this function.

If you wish to prevent executeAfterLoading() from being executed on a particular page, add the following lines to the header of that page:

<SCRIPT LANGUAGE="JavaScript">
noExecuteAfterLoading = true
</SCRIPT>

 

Using Connection System Features

 

Conditional and Random Text

Connection Muse lets you add conditional elements to your text using the Conditional Text Tool. These are fragments of text that are either displayed or not displayed on the page, depending upon conditions that you specify (such as whether or not a particular node has been read). You can also create several alternative text fragments and specify conditions that will determine which of the fragments will be displayed when the node is read.

You can add random elements to your text by creating several alternative text fragments and specifying that one of these be selected randomly and displayed in your page when it is read. This can be done with the Random Text Tool.

Conditional or random text elements can be any length and can include any HTML tags, so they can contain graphics, tables, audio elements, or JavaScript. You can specify as many alternative text fragments as you wish within a random text element.

When to Use Conditional and Random Text

Conditional text can alter a text so that it will better fit into multiple contexts, creating syntactic or narrative transitions as needed. This lets you provide the reader with more options for rearranging the hypertext in different ways during a reading.

Conditional text can also make node recurrence more interesting and meaningful. When reading a hypertext, the reader is likely to periodically encounter nodes she's already read. Rereading these nodes can be more fruitful for the reader when something new is revealed in them. Changing a few words in the text when it is read a second or third time can bring out meanings that were only implied the first time around. Context-sensitive variant versions of a node can ensure that reading the node in different contexts (that is preceded by different nodes) reveals new meaning in it. Different implications of a text passage may be brought out when it is preceded by different nodes, and subtle conditional alterations to the text can make these implications more explicit. Random variations can create a more unpredictable type of variety upon rereading.

It can sometimes be useful to suppress or add certain information conditionally within a node. If a particular node containing background information about an event or character has already been read, that information can be omitted from other nodes by means of conditional text. For example, you could specify that whenever the name "Mary" first appears in a node, it is preceded by the phrase "Bob's wife," unless another node referring to Mary has already been read, in which case Mary will already have been identified as Bob's wife.

Conditional text can also be used to create alternative plot lines. For example, after a reader encounters a node in which Mary is killed, Mary could be eliminated from subsequent nodes by suppressing some of the text in those nodes. If the reader never encounters the node containing Mary's death, Mary can continue to figure in the story until the end.

Adding several random elements within the same node can create interesting and unpredictable textual juxtapositions, such as those found in Surrealist or Dadaist writings.

 

Conditional Links and MultiLinks

The Connection System lets you create a wide variety of Conditional Links using the Conditional Links Tool. You can specify that a Conditional Link is to be activated (that is, made clickable) only if certain conditions are met, or you can specify that the destination node for a Conditional Link should vary depending on specified conditions.

To create a simple Conditional Link, you define a link and then specify a condition, such as whether or not a particular node or a specified number of nodes has been read. You then specify what will happen if the condition is met or not met. Generally you will want the link to be displayed and activated if the condition is met. If the condition is not met, you can substitute an alternative destination, you can deactivate the link (display it as text that is not clickable), or you can hide the link altogether.

To create a MultiLink, you specify a number of alternative destination nodes for the link using the MultiLink Tool. You can then specify that the destination should be chosen randomly or according to whether or not certain conditions are met. You can also combine random and conditional selection, so that a destination is chosen randomly from all nodes that meet a specified condition (such as all nodes not yet visited by the reader).

When to Use Conditional Links

Simple Conditional Links can serve many useful purposes. You can deactivate or hide links that lead to nodes that have already been read. This can be useful if you want to steer readers to new material but for aesthetic reasons don't want to use an alternative vlink color for followed links. If you are using clickable graphics for links, you can specify that an alternative graphic image be displayed for links that lead to previously read nodes.

Conditional Links can be useful for controlling the reader's access to certain material. To maintain suspense in a story, you might want to withhold certain passages (such as the one revealing whodunit in a mystery tale) until most of the hypertext has been read. You can do this by using Conditional Links as the reader's only means to get to the restricted passages. The links could then be hidden or deactivated until a specified number of nodes has been read.

For the sake of coherence and logical development in a narrative, you might want to ensure that certain widely scattered passages within the hypertext are encountered in a particular order. You can do this by creating Conditional Links to the passages, specifying that the links remain hidden or inactive until the prerequisite nodes have been read. For example, Conditional Links could restrict access to a node that describes a certain action--this node would be inaccessible until other nodes had been read that establish the motivation for this action.

Conditional Links can help with character development. Suppose you want to ensure the progressive development of a character named Mary. First, you could categorize all the nodes dealing with Mary as belonging to one of three stages in her development. Conditional links could then ensure that none of the Stage 2 nodes are visited until all of the Stage 1 nodes have been read. Similarly, you could ensure that no Stage 3 nodes are available until all Stage 2 nodes have been read.

Conditional Links can also implement alternative plot elements in a manner similar to that described in the section on conditional text. If the reader encounters a node in which Mary dies, this could deactivate all the links to nodes in which Mary is depicted as being still alive and activate links to nodes that deal with the consequences of her death.

Random Links and Other MultiLinks

MultiLinks can randomly take the reader to a new destination. This can be useful if you want to achieve a highly fragmented style along the lines of, say, one of William Burroughs' "cut-up" novels. MultiLinks can also be used in a more structured way, as described in the following section on text components.

You can specify the alternative destinations in the MultiLink Tool by entering the names of all the destination nodes in the Nodes field. If you wish to create a number of different MultiLinks that use the same set of destination nodes, it is better to create an Item Array that contains the names of all the nodes. Then whenever you create a MultiLink you need only enter the name of the Item Array in the MultiLink Tool. Item Arrays should also be used to implement Text Componenets as described in the next section.

 

Text Components and Organic Hypertext

Connection Muse provides features for handling large-scale structural elements of a story or poem. You can define the large-scale narrative or thematic components of your text and then specify parameters for how these text components should unfold and interact with each other during a reading. In other words, you can assign behaviors to the important elements of your text.

This component and behavior approach lets you define structure as process and create what we call organic hypertext. There are two facets to the concept of organic hypertext:

  • The individual parts of the hypertext contain their own predefined behaviors for growth so they can unfold during the reading with relative independence when necessary.
  • At the same time, these individual parts are able to adapt to the unique circumstances of a particular reading so that the parts can better serve the whole

Here we provide a brief introduction to components and organic hypertext. For a more in-depth discussion, see Toward an Organic Hypertext.

What Are Text Components?

Text components are any structural or conceptual elements that are likely to cohere as distinct entities in the reader's mind during the reading process. For example, the reader may encounter passages about a particular character scattered throughout the text. The reader will mentally piece the content of these passages together to form a conceptualization of that character's personality and history. Here are some categories of text components, along with some specific examples of these components that we will use in a demo for a hypothetical story:

Settings of time or place

  • Chicago
  • New York

Characterizations

  • Susan
  • Jacob
  • Shirley

Plot lines

  • Affair between Susan and Jacob
  • Susan's childhood
  • Jacob's sexual abuse of his niece, Shirley

Themes, unifying metaphors, symbolic elements, and so on

  • guilt and atonement
  • sexual obsession

Here is a diagram of the text component structure of this hypothetical story. Note how some text components are contained within others (for example, Susan's childhood is set in New York), while others overlap (the theme of sexual obsession overlaps with both Jacob's affair and his abuse of his niece).

Using Text Components

You define a text component by specifying a group of nodes that contain the relevant textual material. Components may not always be clear-cut, so the contents of different components can overlap with each other--that is, the same nodes can be contained within more than one component. The content of components can even be changed dynamically by adding or removing nodes during the reading. Once components are defined, you determine their behavior. You can then create links directly to a text component instead of to an individual node. The component's predefined behavior will determine which specific node within the component will serve as the link's destination.

You define the contents of a component by creating an Item Array in your config.js file. The Item Array lists all of the nodes that constitute the component, and you can access these nodes as a group by using the name of the array.

The nodes in a component can behave as an ordered or an unordered set. If the order of the nodes is governed by a logic of chronology or exposition, you can treat the nodes as an ordered sequence. An example of this is a group of nodes that relate a particular plot line, such as the affair between Susan and Jacob in our hypothetical story. Ordered components are represented as ovals in the diagram. You can specify that every time the reader returns to an ordered component, she is taken to the first unvisited node in the sequence. This type of component is called a retentive path, and it lets a reader easily return to a narrative thread and pick up where she left off.

If the nodes are clearly connected in content but don't inherently demand a particular ordering, they can be treated as unordered. An example of this is a group of nodes that contribute to the reader's understanding of a particular character, locale, object, or event or simply share a philosophical outlook or style of writing. All the nodes that bear upon Susan's personality could constitute an unordered component. Unordered components are represented as rectangles in the diagram. (Note that in the diagram the unordered components representing locale contain ordered plot components within them. Part of a component can behave as an ordered sequence while the rest behaves as unordered.)

Other more complex behaviors are also possible. For example, particular nodes can be included in a component or excluded from it depending on whether all or part of some other component has been read. Once a component and its behavior are defined, links can be created directly to a component instead of to an individual node within the component. The component's behavior will determine which node the link leads to.

In the current version of the system, the behavior of a component must be specified every time a link is created. You create links to a component with the MultiLink Tool, and you specify the behavior by filling out the fields in the MultiLink Tool. In our prototype for a future version, behaviors need be specified only once, since they will be stored centrally with the components themselves.

The Component Demo

We've created a hypertext prototype for part of the hypothetical story referred to above. Note that this is just a rough outline for demonstration purposes and not meant to be a real piece of fiction. After clicking on the link above to launch the demo, you will see the main text window on the right and a component map for navigational purposes in a smaller window on the left. The demo text consists of 3 text components, which are represented by icons in the component map:

  1. The Affair (between Susan and Jacob) is a sequence of 7 nodes that unfold a short chronological plot thread. This is a retentive path.
  2. The Susan component consists of all the nodes about Susan that don't require any chronological ordering. These five nodes merely describe aspects of her character and they could be slipped in anywhere within the plot line and presented in any order. This is an unordered component.
  3. The Jacob component is an unordered component of five nodes describing Jacob.

All the links in both windows of this demo are made directly to one of these three components, and the component's behavior determines the exact destination node. All of the links to The Affair lead to the first unvisited node in the sequence. All of the links to Susan or Jacob lead to a randomly selected unvisited node in the respective component. Once all of a character's nodes have been read, previously visited nodes are presented instead of new nodes.

If you wish, you can read all the text by simply clicking repeatedly on the 3 icons in the map. These icons shrink in proportion to the amount of text within the component that has been read, and moving the mouse pointer over an icon shows the percentage of the component read. You can also navigate by following links in the text itself.

Clicking on the Susan or Jacob icon or a link on a character's name in the text always yields new material about that character, as long as new material is available. This guarantees that a link to a character from anywhere in the hypertext will always let you continue to flesh out your knowledge of that character and allow you to keep moving forward with the reading.

After reading several Susan or Jacob nodes, you can return to the story line at any time by clicking on either The Affair in the map or "return to the steamy stuff" in the text. This lets you resume the story line exactly where you left off, no matter where you are in the hypertext.

The way these links function is an example of allowing the different parts of the text to grow independently, one of the goals of organic hypertext. This approach makes for a very smooth reading experience. In this short hypertext the chances of prematurely looping (that is, encountering previously read material) and the need for backtracking to find new material are virtually eliminated, even if the reader doesn't use the map. This wouldn't be the case if all the links in this work were static and fixed. It is easier for the reader to achieve closure in the reading, since it's always clear what remains to be read. The component map also makes it much clearer to the reader how she is interacting within the large-scale structure of the text.

More Complex Approaches

In a larger, more complex hypertext a component map, retentive paths, and other Connection System elements can be even more valuable for the reader. Their use may also become more complex than in our component demo. Suppose you were to implement all of the components you see in our component diagram and then add some new ones. You might then want to control the reader's access to material by manipulating links in the text and on the map. You might want the map to dynamically hide or display some components, rather than presenting them all at once. For example, a component might appear on the map only after the reader has already encountered it through links in the text. You might not want to give the reader access to Jacob's sexual abuse until she's read some background material about Jacob or Shirley.

You might not want the reader to be able to read through the entire Affair sequence without interruption; you might want to create suspense by withholding the last node or two until a lot of other material in the hypertext has been read. You may want the reader to be able to read a plot thread by jumping around in it occasionally and encountering some events out of order. You might feel the need to use mutually exclusive alternative text elements, such as different outcomes for a single plot line. You may decide to combine certain components or exclude nodes from a component under certain circumstances. All of these things are possible with the system. They are examples of the individual parts of the text adapting themselves to serve the needs of the whole, the second goal of organic hypertext

 

Recognized Problems

Pop-up Text

In Netscape Navigator, pop-up text doesn't work properly when connected to text that is centered or placed in tables.

In Internet Explorer, pop-up text doesn't wrap properly when it reaches the edge of the window. This may cause some text to be cut off.

In Internet Explorer, when pop-up text is added to a link or to hot text presented with the display() function, any space inserted after the link or the hot text is not displayed. This problem does not occur if pop-up text is not used. For example, this code:

Place your mouse pointer

<script language="JavaScript">
text = "here"
popupText = "this is the pop-up text"
display(text)
</script>

to view the pop-up text.

should be displayed like this:

Place your mouse pointer here to view the pop-up text.

Instead it is displayed like this:

Place your mouse pointer hereto view the pop-up text. [no space between "here" and "to"]

Here is a workaround for the problem:

Place your mouse pointer

<script language="JavaScript">
text = "here"
popupText = "this is the pop-up text"
display(text)
</script>&nbsp;to

view the pop-up text.

Opening First Page in New Window

The connect.js library file may not load properly when a Connection System page is opened in a new browser window by right-clicking on a link and selecting "Open in new window." To avoid this problem, it is best not to use Connection System functions in the opening page of a hypertext, since a reader may open this page in a new browser window when following a link to it from another Web site.