Getting started


his chapter explains how to install LiveWire, gives an overview of LiveWire Application Manager, and walks you through some sample applications.

Installing LiveWire

Note: For installation instructions specific to your platform, refer to the README.TXT file. Before installing LiveWire, you need to determine your development environment configuration. In general, it is recommended that you develop applications on a system other than your deployment (production) server because development consumes resources (for example, communications ports, bandwidth, processor cycles, memory). Development might also disrupt end-user sessions.

A LiveWire development environment consists of

If you are creating a database application, you must also install the database client software on your development and deployment servers, and the database server on a workstation. The database server can be on the same machine as a Netscape server; however, it is recommended that development and deployment platforms be distinct.

To install LiveWire, run the self-extracting archive file livewire.exe. On Windows NT, this will create a program group and program icons. After you install LiveWire, you must stop and restart your Netscape server.

Enabling LiveWire

Note: If you do not enable LiveWire, applications will not run. To run LiveWire applications on your server, you must enable the LiveWire runtime from your Server Manager by clicking Programs and then choosing LiveWire. Then at the prompt "Activate the LiveWire application environment?", choose "Yes," and then click OK.

Protecting Application Manager

As described in the next section, Application Manager provides control over LiveWire applications. Because of its special capabilities, you should protect it from unauthorized access. If you don't restrict access to Application Manager, anyone can add, remove, modify, start, and stop applications on your server. You don't want that.

Note: You are strongly advised to restrict access to Application Manager. When you enable LiveWire in the Server Manager by clicking Programs and choosing LiveWire, a prompt will ask you whether to restrict access to Application Manager. Choose "Yes" to do so, then click OK. This will apply the LiveWire configuration style to Application Manager and the DBAdmin sample application. You will then be required to enter the Server Manager username and password to use Application Manager and DBAdmin. (DBAdmin enables you to connect to databases and execute SQL statements interactively).

If your server is not using the Secure Sockets Layer (SSL), the username and password for Application Manager will be transmitted unencrypted over the network. If an attacker intercepts this data, he can get access to Application Manager; if you use the same password for your administration server, he will also have control of your server. Therefore, it is recommend that you:

Using Application Manager

Before learning how to create LiveWire applications, you should become familiar with the LiveWire Application Manager. Using Application Manager, you can

Application Manager is itself a LiveWire application. Although it uses some special functions not available to other applications, it demonstrates the power and flexibility of LiveWire.

Note: For convenience, bookmark this page in Navigator.

If you are using Windows, you can run Application Manager by double-clicking the Application Manager icon in the LiveWire program group. On other platforms, you run Application Manager by loading the following URL in Navigator:

http://server.domain/appmgr
You will see the following:

Application Manager displays all applications currently installed on the server in a scrolling list in the left frame. Select an application by clicking its name in the scrolling list.

For the selected application, the right frame will display the

Click the task buttons in the left frame to perform the indicated action on the selected application. For example, to modify the installation parameters of the selected application, click Modify.

Click Help for instructions on using Application Manager. Click Config to configure the default settings for Application Manager.

Installing a new application

You must install (add) an application with LiveWire Application Manager before you can run it. To install a new application, click Add. You will see the following form in the right frame:

Note: You can install up to 1024 LiveWire applications on one server. Use this form to enter the following information:

Application URLs

When you install an application, you must enter a name for the application. This name determines the application URL, the URL that clients use to access a Livewire application. Application URLs are of the form

http://server.domain/appName/page.html
where server is the name of the HTTP server, domain is the Internet domain (including any subdomains), appName is the application name you enter when you install it, and page is the name of a page in the application.

For example, if your server is named "coyote" and your domain name is "acme.com," the application URL for the Hello World sample application is

http://coyote.acme.com/world/hello.html
When a client requests this URL, the server generates HTML for the specified page in the application and sends it to the client.

Important: Before you install an application, be sure the application name you choose will not usurp an existing URL on your server. LiveWire will route all client requests for URLs that match the application URL to the directory specified for the web file. This will circumvent the server's normal document root.

Using the previous example, any requests for URLs that begin with

http://coyote.acme.com/world
will look for documents in the livewiresamplesworld directory and not in your server's normal document root. The server will also serve pages in the directory that are not compiled into the application.

Initial and default pages

If a user does not request a specific page in an application, LiveWire will serve

Controlling access to an application

When you install an application, you may want to restrict the users that can access it. You can do this by applying a server configuration style to the application. For detailed instructions, see "Restricting access to applications." For general information on configuration styles, see your server Administrator's Guide.

Note: Controlling access to applications with configuration styles is available only with Netscape's version 2.0 servers.

Modifying installation parameters

To modify an application's installation parameters, select the application name in the left frame and click Modify.

You can change any of the parameters defined when you installed the application, except the application name. To change the name of an application, you must remove the application and then reinstall it.

If you modify the parameters of a stopped application, Application Manager automatically starts it. When you modify parameters of an active application, Application Manager automatically stops and restarts it.

Removing an application

To remove the selected application, click Remove. This action removes the application from running with LiveWire but does not delete files from the server. Clients will no longer be able to access the application.

If you delete an application, and you subsequently want to run it, you must install it again.

Starting, stopping, and restarting an application

To start an installed application that is stopped, click Start. If LiveWire can start the application successfully, then clients will be able to run the application.

To stop an active application, click Stop. The application's status changes to "stopped," and clients can no longer run the application. You must stop an application if you want to move the web file or update an application from a development server to a deployment server.

To restart a running application, click Restart. For the changes to take effect, you must restart an application after you compile it.

You can also start, stop, and restart an application by entering a special URL of the form

http://server.domain/appmgr/control.html?name=appName&cmd=action
where appName is the application name and action is either "stop," "start," or "restart."

Running and debugging an application

To run an installed application

  1. Select the application name in Application Manager, and then click Run. This will open a new Navigator window to access the application.
  2. Load the application URL in Navigator by typing it in the Location field.

Tip: Add a Navigator bookmark for often-used applications. If you attempt to run a stopped application (one that is not active), then Application Manager will try to start it first.

To debug the selected application

  1. Select the application name in Application Manager, and then click Debug. This will run the application and display the application trace, either in a separate window or in the same window, but in a different frame, depending on the configuration settings of Application Manager.

    Note: For more information on debugging, see "Debugging applications."

  2. Load the application's debug URL, as described in "Using debug URLs."

Configuring default settings

Click Config to configure default parameter settings for Application Manager. You will see the following form in the right frame:

The default settings you can specify are

Under the hood

Application Manager is a convenient interface for modifying the configuration file livewirebinlivewire.conf. In case of catastrophic errors, you may need to edit this file yourself. In general, this is not recommended, but the information is provided here for troubleshooting purposes.

Each line in livewire.conf corresponds to an application. The first item on each line is the application name. The remaining items are in the format

name=value
where name is the name of the installation parameter, and value is its value. The names are:

The livewire.conf file is limited to 1024 lines, and each line is limited to 1024 characters. If the parameters entered in Application Manager cause a line to exceed this limit, the line is truncated. This will usually result in loss of the last item, external library files. If this occurs, reduce the number of external libraries entered for the application, and add the libraries to other applications. Because installed libraries are accessible to all applications, the application will still be able to use them.

If you manually edit livewire.conf, you must ensure that there is a line break at the end of each line, and there are no spaces in any line. Otherwise, it will not work properly.

LiveWire sample applications

When you install LiveWire, several sample applications are also installed. For an introduction to the capabilities of LiveWire, run them. Both the source files and the web files for these applications are installed in the LiveWire samples directory. The sample applications are:

Running Hello World

In this section, you will run Hello World, the simplest sample application, and get an introduction to

What Hello World does

This application illustrates two important LiveWire capabilities: maintaining a distinct client state for multiple clients and maintaining a persistent application state. Specifically, it

The first time you access this page, the values for both names ("this time" and "last time") are null. The number of times you have previously accessed the page is zero, and the total number of times it has been accessed is one.

Type in your name and click Enter. The page now shows the name you entered following the text "this time you are." Both numbers of accesses have been incremented. This action illustrates simple form processing. Enter another name and click Enter. The page now shows the new name following the text "this time you are" and the previous name following the text "last time you were." Again both numbers of accesses have been incremented.

If you access the application from another instance of the Navigator (or another computer), the page displays the total number of accesses and the number of accesses by each instance of Navigator.

Looking at the source script

Now take a look at the LiveWire source script for this application. Using your favorite text editor, such as Windows Notepad, open the file samplesworldhello.html in the directory where you installed LiveWire. Later, you can use Navigator Gold for editing, but for now it is instructive to examine the HTML source code directly.

The file begins with some typical HTML:

<HTML>
<HEAD> <TITLE> Hello World </TITLE> </HEAD>
<H1> Hello World </H1>
<P>Your IP address is <SERVER>write(request.ip)</SERVER>
The SERVER tags in the bottom line enclose server JavaScript code. In this case, the statement write(request.ip) displays the ip property of the request object, which is the IP address of the client accessing the page.

The write function is very important in LiveWire, because you use it to display the values of JavaScript expressions in HTML.

The next statement

<SERVER>client.oldname = request.newname; // Get new name from form 
input.</SERVER>
assigns the value of the newname property of the request object to the oldname property of the client object. The request and client objects are part of the LiveWire built-in object framework. For a full description of the objects and properties built in to LiveWire, see Chapter 4, "Using the LiveWire object framework."

The value of request.newname is set when a user enters a value in the form. Look further down the file to the form statements:

<FORM METHOD="post" ACTION="hello.html">
<INPUT TYPE="text" NAME="newname" SIZE="20">
Note:

Next, there is a SERVER tag, indicating that the following lines are JavaScript statements. The first group of statements is

if (client.number == null)  // Initialize number of accesses by this 
client
	client.number = 0
else
	client.number = parseInt(client.number) + 1
This is a conditional if...then statement that checks if the number property of the client object has been initialized. If it has not, then it initializes it to zero; otherwise, it increments number by one using the JavaScript parseInt function (parseInt converts the string value to a number).

Note: Because LiveWire objects have only string property values, you must use parseInt or parseFloat to convert them to numbers. Because number is a property of the client object, it will be distinct for each different client that accesses the application. This value indicates the number of times "you have been here."

To track the total number of accesses, you need to use the project object, because it is shared by all clients accessing the application. The next group of statements does so:

project.lock() // Initialize or increment total number of accesses.
if(project.number == null)
	project.number = 0
else
	project.number = parseInt(project.number)++
project.unlock()
The first statement uses the special lock method of the project object. This gives the client temporary exclusive access to the project object. Another if...then statement checks whether project.number has been defined. If not, then it initializes it to zero; otherwise, it increments it by one using parseInt. Finally the unlock method releases the project object so that other clients can access it.

The final statements in the file display the values of client.number and project.number.

<P>You have been here <SERVER>write(client.number)</SERVER> times.
<BR>This page has been accessed <SERVER>write(project.number)</SERVER> 
times.

Modifying Hello World

Now you are going to modify, recompile, and restart the sample application. To edit the source file, you must first determine where it is. If you don't remember, Application Manager shows the directory path of the web file. The source file, hello.html, should be in the same directory. Edit the file with Navigator Gold or your favorite text editor. The HTML looks like this:

<HTML>
<HEAD>
<TITLE> Hello World </TITLE>
</HEAD>
<BODY>
<H1> Hello World </H1>
<P>Your IP address is <SERVER>write(request.ip)</SERVER>
<SERVER>
write("<P>Last time you were " + client.oldname + ".")
</SERVER>
<P>This time you are <SERVER>write(request.newname)</SERVER>
<SERVER>client.oldname = request.newname // Remember name for next time.
</SERVER>
Add a line that displays the type of browser the user has:

<P>You are using <SERVER>write(request.agent)</SERVER>
If you want, you can also personalize the heading of the page; for example, you could make the title "Fred's Hello World."

Now, run LiveWire Site Manager by double-clicking the Site Manager icon (single-click in a Unix environment). Then follow these steps:

  1. In the left frame of Site Manager, select the world directory in the LiveWire samples directory (livewiresamples, by default).
  2. Choose Site | Manage to bring the application under site management (if it is not already).
  3. Choose Site | Build Application to compile the application. Next, restart the application with Application Manager. Now, run the application again by clicking Run in Application Manager. You will see the changes you made to the application.

Running Hangman

In this section, you will run and modify the Hangman sample application and learn some new concepts, including how to

What Hangman does

Hangman is a classic word game in which you try to guess a secret word. The unknown letters in the word are displayed on the screen as asterisks, which are replaced as you guess the correct letters. When your guess is incorrect, one more part of the hanged man is drawn. The game also shows the incorrect letters you have guessed.

When the hanged man is completely drawn, you lose the game. If you guess all the letters in the word before the man is hanged, then you win. In this simple version of the game, there are three possible secret words. After you play a game, you can choose to play again (and use the next secret word) or you can choose to quit.

Run the Hangman application by selecting "Hangman" in Application Manager and clicking Run. Alternatively, you can load the application URL in Navigator:

http://server.domain/hangman
You will see the following:

Play the game a little to get a feel for it.

Looking at the source files

Hangman contains the following:

There is also a file called rules.html that is not compiled with the application, but includes some text explaining the game. It is included primarily as an example of a non-compiled application page that is part of the same site.

Examine hangman.js, an example of a JavaScript-only source file. It defines two functions, InitAnswer and Substitute, used in the application. Notice that you do not use SERVER tags in a JavaScript-only file.

Most of the application logic is in hangman.html. The basic logic is simple:

  1. For a new game, initialize the secret word and other variables.
  2. If the user guessed a letter, substitute it into the answer
  3. If the guess was wrong, increment the number of wrong (missed) guesses
  4. Check to see if the user has won or lost.
  5. Draw the hanged man, using a GIF image based on the number of wrong guesses.
The JavaScript code to initialize a new game is:

if (client.gameno == null) {
client.gameno = 1
client.newgame = "true"
// Initialize secret word, answer, and used for each new game.
if (client.newgame=="true") {
	if (client.gameno % 3 == 1)
		client.word = "LIVEWIRE"
	if (client.gameno % 3 == 2)
		client.word = "NETSCAPE"
	if (client.gameno % 3 == 0)
		client.word = "JAVASCRIPT" 
	client.answer = InitAnswer(client.word)
	client.used = ""
	client.num_misses = 0
}
client.newgame = "false"  // set flag so don't initialize next time
The first statement determines if you've played before, by checking if client.gameno exists; if not, it initializes it to one and sets client.newgame to true. Then, some simple logic assigns the "secret word" to client.word. There are just three secret words that you cycle through as you play the game; client.gameno keeps track of how many times you've played. The final part of initialization uses InitAnswer, a function defined in hangman.js, to initialize client.answer to a string of asterisks.

Then comes a block of statements to process the user's guess:

if (request.guess != null) {
	request.guess = request.guess.toUpperCase()
	debug(request.guess)
	client.used = client.used + request.guess + " "
	request.old_answer = client.answer
	client.answer = Substitute(request.guess, client.word,
		client.answer)
	if (request.old_answer == client.answer)
		client.num_misses = parseInt(client.num_misses) + 1
}
The if statement determines if you have made a guess (entered a letter in the form field). If you have, then the script calls Substitute, another function defined in hangman.js, which substitutes the guessed letter into client.answer where it matches; so client.answer is the current answer the user has so far (for example, "N*T**AP*").

Note:You must always use parseInt to work with integer property values of LiveWire objects The second if statement checks if client.answer has changed since the last guess; if not, then it increments client.num_misses to keep track of the number of missed guesses. You cannot use parseInt(client.num_misses)++, because parseInt returns an integer, so this would be like trying to do 2++.

The final if statement in the JavaScript code checks if the user has won or lost, and redirects the client accordingly:

if (client.answer == client.word)
	redirect("youwon.html")  // redirect if you win.
else if (client.num_misses > 6)
	redirect("youlost.html")  // redirect if you lose.
Then, the JavaScript ends and HTML begins. The hanged man is drawn by using a backquoted JavaScript expression inside an HTML IMG tag:

<IMG SRC=`"images/hang" + client.num_misses + ".gif"`>
The entire expression between the two backquotes (`) is a JavaScript string. It consists of the string literal "images/hang" concatenated with client.num_misses (which represents an integer but is stored as a string), concatenated with the string literal ".gif". There are six GIF files containing the hanged man in different stages of completion: image0.gif, image1.gif, and so on. The backquoted JavaScript generates HTML of the form:

<IMG SRC="images/hang0.gif">
Then the line

<PRE><SERVER>write(client.answer)</SERVER></PRE>
displays the value of client.answer, that is, the word containing all the correctly guessed letters. The next lines

You have used the following letters so far: 
<server>write(client.used)</server>
display all the guessed letters.

The remainder of the file consists of standard HTML. One important thing to notice is that the ACTION attribute of the FORM tag specifies hangman.html as the URL to which to submit the form. That means when you submit the form, the page will be reloaded with the specified form values.

Modifying Hangman

You may have noticed that the application does not check your guess to make sure it is a single letter. You are now going to make a simple change to ensure that only a single letter is guessed. Edit the source file hangman.html and look for the following line:

request.guess = request.guess.toUpperCase() // Need to change to limit 
guess to one letter
Make the following change to the line:

request.guess = request.guess.toUpperCase().substring(0,1)

The string method substring returns a subset of a string, so this will truncate request.guess to one letter.

To make your change take effect, you must recompile and restart the application.

To compile, invoke Site Manager (in Windows NT, click on the icon; in Unix, enter the command line). Then select the LiveWiresampleshangman directory and choose Site | Build Web File. You will see messages from the compiler; the final message will be "Compiled and linked successfully."

To restart, access Application Manager, select hangman, then choose Restart. Then run the application by choosing Run. A window will open running Hangman. Try entering multiple letters for the guess, to confirm that only the first letter is accepted.

Debugging Hangman

You can experiment more with LiveWire to get the hang of developing applications. One important task to master is debugging. In Application Manager, select hangman and choose Debug. A window will open with the application in one frame and debugging information in a narrow frame along the left side of the window, looking something like this:

Notice that the URL is

http://yourserver.domain.com/appmgr/debug.html?name=hangman
You can add a bookmark for this URL as a convenience while you are working on Hangman. Then you don't have to go through Application Manager.

Try adding a function to Hangman that checks to make sure the user's guess is a letter (not a number or punctuation). You can use the function InitAnswer defined in hangman.js as a starting point. After compiling and restarting the application, use your bookmark to run the application in debug mode.

Moving on

Now that you've tried your hand at LiveWire, you can start working on your own applications, or take a look at some of the other sample applications that come with LiveWire. You should at least review the material in Chapter 3, "Developing applications" and look at the material in some of the other chapters to become familiar with LiveWire and its capabilities.

If you are interested in creating database applications, you should read Chapter 6, "Creating database applications."