Developing Applications

his chapter describes how to develop server applications with LiveWire and JavaScript. For information on using JavaScript in client applications, see the JavaScript Guide.

LiveWire essentials

Normally, HTML is static: you write an HTML page, and it is fixed. The fixed content is transmitted from the server to the client when the client accesses the page's URL. With LiveWire, you can create dynamic HTML pages that change based on changing data and actions by users.

As illustrated in Figure 3.1, the basic procedure to create and run a LiveWire application is

Creating and running a LiveWire application

The tools

You use the following tools in developing applications with LiveWire:

The basic steps

 The basic steps in building a LiveWire application are:

  1. Create the source files with Navigator Gold (or a text editor) and save them on the server.
  2. Build the application by either
  3. Use Application Manager to either
  4. Run the application by clicking Run in Application Manager or entering the application URL in your browser. For example, to run "Hello World", load: http://server.domain/world/. You may also debug the application by clicking Debug in Application Manager.

Creating and editing source files

 The first step in building a LiveWire application is to create and edit the source files. LiveWire source files can contain

Using forms

 Forms are the bread and butter of a LiveWire application, because they are the primary mechanism by which data is transferred from the client to the server. To submit values from a form to a LiveWire application, use the application URL as the ACTION attribute of the FORM tag. If the document containing the form is in the same application, you can simply supply the name of the page instead of a complete URL. For example, here is the form tag from the Hangman sample application:

<FORM METHOD="post" ACTION="hangman.html">
LiveWire forms can use either "get" or "post" as the value of the METHOD attribute.

Note: LiveWire applications cannot perform file upload; that is, you cannot have an INPUT element of TYPE="file" that is submitted to a LiveWire application.

Embedding JavaScript in HTML

 There are two ways to embed a JavaScript statement in HTML:

Using the SERVER tag

 There are two ways to use JavaScript in the SERVER tag: to generate HTML with the write function, and simply to execute a JavaScript statement.

The write function causes LiveWire to generate HTML. When the client accesses an application, it receives HTML from the server. The client does not "know" that the HTML came from a LiveWire application. A JavaScript statement that does not include a write function does not generate HTML, but simply performs the statement.

These two different ways of using JavaScript are illustrated in the following excerpt from the "Hello World" sample application:

<P>This time you are 
<SERVER>
write(request.newname)
client.oldname = request.newname 
</SERVER>
The first line generates HTML based on the value of request.newname. If request.newname is "Mr. Ed," then it will generate the following HTML:

<P>This time you are Mr. Ed.
The second line in the example simply performs a JavaScript statement, assigning the value of request.newname to client.oldname. It does not generate any HTML.

Using backquotes

In general, HTML tags are of the form

<TAG ATTRIB="value" [...ATTRIB=VAL]>
where ATTRIB is an attribute and "value" is its value. The bracketed expression indicates that there can be any number of attribute/value pairs.

Use backquotes (`) to enclose JavaScript expressions as substitutes for HTML attribute names or values. When you embed JavaScript in HTML with back-quotes, it automatically emits HTML; you do not need to use write.

For example, consider the following line from the "Hangman" sample application:

<IMG SRC=`"images/hang"+client.num_misses+".gif"`>
This line dynamically generates the name of the image to use based on the value of client.num_misses. The backquotes enclose a JavaScript expression that concatenates the string "images/hang" with the integer value of client.num_misses and ".gif". The result is a string such as "images/hang0.gif" or "images/hang1.gif". JavaScript automatically converts the integer value to a string. The result is HTML such as

<IMG SRC="images/hang0.gif">
The order of the quotation marks is critical. The backquote comes first, indicating that the following value is a JavaScript expression, consisting of a string ("images/hang"), concatenated with an integer (client.num_misses), concatenated with another string (".gif"). JavaScript converts the entire expression to a string, and LiveWire adds the neccessary quotes around the attribute value. You cannot put a JavaScript expression for an attribute value inside double quotation marks, because it would be interpreted as the literal attribute value.

LiveWire automatically adds quotation marks around an attribute value when you enclose a JavaScript expression in backquotes, therefore do not provide them yourself (except for string literals, as in the preceding example).

For example, the anchor tag has attributes called HREF and NAME, among others. HREF makes the tag a hyperlink, and NAME makes it a named anchor. You could use the following script to create either a hyperlink or a target, depending on the value of the attrib and val properties of client:

<A `client.attrib` = `client.val`> Netscape Communications </A>
You could use the following code before the preceding statement to set the properties according to a request variable:

<SERVER>
if (request.choice == "link") {
   client.attrib = "HREF"
   client.val = "http://www.netscape.com"
}
if (request.choice == "target") {
   client.attrib = "NAME"
   client.val = "NetHead"
}
</SERVER>
If request.choice is "link", the result would be

<A HREF="http://www.netscape.com"> Netscape Communications </A>
If request.choice is "target", the result would be

<A NAME="NetHead"> Netscape Communications </A>
In both cases LiveWire adds the quotation marks around the attribute values produced in HTML.

Using the SERVER tag versus backquotes

In most cases, it is clear when to use the SERVER tag and when to use backquotes. However, sometimes you can achieve the same result both ways. In general, it is best to use backquotes to embed JavaScript values inside HTML tags, and use SERVER elsewhere.

For example, in Hangman, instead of writing

<IMG SRC=`"images/hang"+client.num_misses+".gif"`>
you could write

<SERVER>
write("<IMG SRC=\"images/hang")
write(client.num_misses)
write(".gif\">")
</SERVER>
Notice the backslash that lets you use a quotation mark inside a literal string. While the resulting HTML is the same, in this case, backquotes are preferable, because the source is easier to read and edit.

Compiling applications

There are two ways to compile a LiveWire application: with Site Manager and with the command-line compiler.

Compiling with Site Manager

To compile a LiveWire application with Site Manager, follow these steps:

  1. Select the application directory in the Folders page of Site Manager.
  2. Choose Site | Manage to bring the application under site management (if it is not already).
  3. Choose Build Web File to compile the application with the LiveWire compiler.
    Note: Only sites that have pages containing server-side JavaScript need to be compiled.

Using the command-line compiler

 The command-line compiler is available from any command prompt. Use the following command-line syntax to compile and link LiveWire applications on the server.

lwcomp [-c|v|?] [-o outfile.web] 
[script1.html ..scriptn.html] 
[funct1.js ..functn.js]
Items enclosed in square brackets are optional. The syntax is shown on multiple lines for clarity. There must be at least one HTML file or JavaScript source file.

Options

The following command-line options are available:

Installing and restarting applications

 You must install an application before you can run it and clients can access it. Each time you rebuild an application, you must restart it. You use Application Manager to install, start, and restart applications. For a full description of Application Manager, see "Using Application Manager" on page 20.

Installing a new application

After you build an application, you must install it with LiveWire Application Manager to make it accessible to clients. Installing an application identifies it to the server.

To install a new application, click the Add button in Application Manager. The right frame of Application Manager will display a form in which you enter the application name, path to the web file, and other installation parameters.

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.

For more information on installing applications, see "Installing a new application" on page 22.

Restricting access to an application

You may want to restrict the users that can access a particular application. You can do this by applying a server configuration style to the application. For more information on styles, see your server Administrator's Guide.

Starting, restarting, and stopping an application

After you first install an application, you must start it to run it. Select the application in Application Manager and click Start. If LiveWire successfully starts the application, the status of the application will change from "stopped" to "active" in the right frame.

You can also start an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=start
where appName is the application name.

You must restart an application each time you rebuild it. To restart an active application, select it in Application Manager and click Restart. Restarting essentially re-installs the application; LiveWire will look for the specified web file. If there is not a valid web file, then LiveWire will generate an error.

You can also restart an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=restart
If you want to stop an application, to make it inaccessible to users, select it in Application Manager and click Stop. You can also stop an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=stop

Running and debugging an application

 Once you have compiled and installed an application, you can run it by

How LiveWire processes an application page

 Running an application begins with a client request for a page. When the Netscape server receives the client request, it first performs authorization. This step is part of the basic server administration functions. If the request fails server authorization, then no subsequent steps are performed.

  1. If the request passes server authorization, then for each request LiveWire performs the following steps:
  2. Creates new request object and initializes its built-in properties, such as the request's IP address, and any form input elements associated with the request.
  3. Creates/restores client object: If the client object already exists, LiveWire retrieves it based on the specified client maintenance technique. If there is no existing client object, LiveWire creates a new object.
  4. Saves client object properties: LiveWire saves client object properties immediately before outputting the page to the client. LiveWire must save client object properties at this point to support some of the techniques for storing client object property values. For example, client cookies and client URL-encoding both require that client property values be known before or during page output. Therefore, any script statements that change client properties should be at the beginning of the HTML file, before any write statements.
  5. Outputs HTML: LiveWire sends the page content to the client. For static pages, the server simply transfers the HTML to the client. For dynamic pages, LiveWire performs the application logic to create the HTML and then sends it to the client.
  6. Saves/destroys client object: LiveWire saves or destroys the client object, created previously.
  7. Destroys request object: LiveWire destroys the request object created previously.
  8. Performs sever data logging: This data logging step is part of the basic server administration functions.

Debugging an application

 To debug an application, select it in the left frame of Application Manager and click Debug. This action will open a new Navigator window running the application, and a frame or window displaying the LiveWire trace facility for the application. You can specify whether the application trace appears in the same window as the application (in another frame) or in a separate window, by clicking on Config to configure Application Manager's default settings.

The trace facility displays values of object properties and arguments to debug functions called by the application. The facility shows all the property values of the request and client objects, before and after emitting the HTML for the page. It also indicates when the application assigns new values to properties. The trace facility will also indicate when LiveWire flushes content; this occurs for each block of 64Kbytes of content.

For example, if you click on Debug for "Hangman" you will see something similar to this:

Using debug URLs

For convenience, bookmark these URLs when developing an application.
Instead of using Application Manager, it may be more convenient to use an application's debug URL instead. To display an application's trace facility in a separate window, enter the following URL:

http://server.domain/appmgr/trace.html?name=appName
where server.domain is your server and domain name and appName is the name of the application. To display the trace facility in the same window as the application (but in a separate frame), enter this URL:

http://server.domain/appmgr/debug.html?name=appName
You must have access privileges to run Application Manager to use these URLs.

Using the debug function

The debug function displays values to the application trace facility. For example, the statement

debug("Current Guess is ", request.guess)
displays the value of the guess property of the request object in the trace window along with some identifying text.