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

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 production server because development will consume resources (for example, communications ports, bandwidth, processor cycles, memory). Development might also disrupt end-user sessions.

A LiveWire development environment includes

To install LiveWire from the CD-ROM, run the setup.exe file. This will install all the software. On Windows NT, it will create a program group and program icons. After you have installed LiveWire, you must stop and restart your Netscape server.

Note: For beta releases, refer to the online release notes for specific installation instructions.

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; it uses some special functions not available to other applications, but it demonstrates the power and flexibility of LiveWire.

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 on its name in the scrolling list.

For the selected application, the right frame will display the

  • Application name at the top of the frame
  • Path of the application .web file on the server
  • Default and initial pages for the application
  • External libraries (if any)
  • Client object maintenance technique
  • Status of the application: active or stopped. Users can only run active applications. Stopped applications are not accessible. 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 Application Manager's default settings.

    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:

    Use this form to enter the following information:

    After you have entered all the required information, click Enter to install the application, Reset to clear all the fields, or Cancel to cancel the operation.

    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 sub-domains), 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 that you pick will not to 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 samples\world in the LiveWire directory and not in the world sub-directory of your server's normal document root. The server will also server page 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

    You may want to restrict the users that can access a particular application. You can do this by applying a configuration style to the application. For more 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 the installation parameters for an application, 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 for the application name. To change the name of an application, you must remove it and then reinstall it.

    If you modify the parameters of a stopped application, Application Manager will automatically start it. When you modify parameters of an active application, Application Manager will automatically stop and restart it.

    Removing an application

    To remove the selected application, click Remove. This action will remove the application from running with LiveWire, but will not actually delete any 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 will change to "stopped" and clients will no longer be able to 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. You must restart an application after you compile it, for the changes to take effect.

    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

    Tip: add a Navigator bookmark for often-used applications
    To debug the selected application

  • Select the the application name in Application Manager, then click Debug. This will run the application and display the application trace, either in a separate window or in the same window, but a different frame, depending on Appllication Manager's configuration settings.
  • Load the application's debug URL, as described in "Using debug URLs" on page 64. For more information on debugging applications, see "Debugging an application" on page 63.

    Configuring default settings

    Click on 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:

    The default installation parameters will be the default settings when you install a new application.

    LiveWire sample applications

    When you install LiveWire, the following sample applications are also installed:

    For an introduction to the capabilities of LiveWire, run one of the sample applications.

    Note: The video and DBAdmin sample applications will only work if you have a supported database server installed on your network. For more information, see Chapter 6, "Creating database applications".

    Running Hello World

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

    What Hello World does

    This application illustrates two important capabilities of LiveWire: 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 will now show the name you entered following the text "this time you are." Both numbers of accesses will be incremented. This illustrates simple form processing. Enter another name and click Enter. The page will show 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 will be incremented.

    If you access the application from another instance of the Navigator (or another computer), the page will display 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. Open the file, samples\world\hello.html, in the directory where you installed LiveWire. Open this file in your favorite text editor, such as Windows Notepad. Later, you can use Navigator Gold for editing, but now you will examine the HTML source code.

    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 encloses 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 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 = 1 + parseInt(client.number,10)
    
    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. Notice the comments following the double slash.

    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." Because LiveWire object properties are always stored as strings, you have to use the parseInt function when you increment it. The parseInt function takes a string and converts it into an integer of the specified radix or base (in this case, 10).

    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 = 1 + 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 if project.number is defined. If it has not, then it initializes it to zero; otherwise, it increments it by one. 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 the sample application, recompile, and restart it. To edit the source file, you must first determine where it is. If you don't remember, Application Manager will show the directory path of the web file. The source file, hello.html, should be in the same directory. Edit the file with your favorite text editor. You will see the following:

    <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 pane of Site Manager, select the world directory in the LiveWire samples directory (livewire\samples, 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

    What Hangman does

    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
    

    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, and each correct letter that you guess is inserted into the word as you guess it. When you guess a wrong letter, one more part of the hanged man is drawn; the game also shows you all the wrong letters you have guessed.

    When the hanged man is drawn completely, he is hung and you lose the game. If you guess all the letters in the word, 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.

    Viewing the source script

    TBD.

    Modifying Hangman

    TBD.

    Debugging Hangman

    TBD.