Developing applications

his chapter describes how to develop applications with LiveWire and Java-Script. 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 user actions.

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

Creating and running a LiveWire application

The tools

You use the following tools to develop 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

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. They are the primary mechanism by which data are 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 do not support file upload; that is, you cannot submit an INPUT element of TYPE="file" 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 simply performs the statement and does not generate HTML.

The following excerpt from the Hello World sample application illustrates these two ways of using JavaScript:

<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 excerpt 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 any number of attribute/value pairs is possible.

Use backquotes (\Q) to enclose JavaScript expressions as substitutes for HTML attribute names or values. JavaScript embedded in HTML with backquotes automatically generates HTML; you do not need to use write.

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

<IMG SRC=\Q"images/hang" + client.num_misses + ".gif"\Q>
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 necessary quotation marks 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 \Qclient.attrib\Q = \Qclient.val\Q> 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://home.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 either way. 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=\Q"images/hang" + client.num_misses + ".gif"\Q>
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. Although 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. Both create a LiveWire .web file from HTML and JavaScript source files.

Note: Only pages containing server-side JavaScript need to be compiled.

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 LiveWire application to compile the application with the LiveWire compiler.

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|d|?] [-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.

Note: For more information, see "Using Application Manager."

Installing new applications

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. For complete instructions on installing an application, see "Installing a new application."

Note: Unix only You must stop and restart your server after you add new application with Application Manager on Unix servers. You can restart a server from your Server Manager; see your server's Administrator's Guide for more information.

When 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. For example, if you have an application called "orders," when a client requests the URL

http://yourserver.yourdomain.com/orders
the user will get the LiveWire application; if you have an orders directory in your server document root, users will no longer be able to access it.

Protecting applications

You may want to restrict access to your application, particularly if the application provides access to sensitive information or capabilities. You can protect your application from unauthorized access as described in "Restricting access to applications."

If you are working on a development server inside a firewall, then you may not need to worry about restricting access while you are developing the application. It is convenient to have unrestricted access during development, and you may be able to assume that the application is safe from attack from inside the firewall. If you are using sample data during the development phase, then the risk will be even less. However, if you leave your application open, you should be aware that anyone who knows or guesses the application URL can use the application.

When you finish development and are ready to deploy your application, you should reconsider how you want to protect it. For more information, see "Restricting access to applications."

Starting, restarting, and stopping applications

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, indicated in the right frame, will change from "stopped" to "active."

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 reinstalls 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
To use the start, restart, or stop URLs you must have access privileges for Application Manager.

Running and debugging applications

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.

If the request passes server authorization, then for each request LiveWire performs the following steps:

  1. 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.
  2. 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.
  3. Saves client object properties: LiveWire saves client properties immediately before outputting the page to the client. LiveWire must save client object properties at this point to support some of the client object maintenance techniques. 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.
  4. Outputs HTML: The server sends the page content to the client. For static pages, the server simply transfers HTML to the client. For dynamic pages, LiveWire performs the application logic to create HTML and then sends it to the client.
  5. Saves/destroys client object: LiveWire saves or destroys the client object created previously.
  6. Destroys request object: LiveWire destroys the request object created previously.
  7. Performs server data logging: This data-logging step is part of the basic server administration functions.

Debugging applications

 To debug an application, select it in the left frame of Application Manager and then 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 Config to configure the default settings for Application Manager.

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 generating 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 64 Kbytes of content.

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

Using debug URLs

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:

Note: For convenience, bookmark these URLs when developing an application. 

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
To use these URLs you must have access privileges to run Application Manager.

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.

Security considerations

When developing LiveWire applications, you should keep security considerations in mind, particularly if the application will be accessible to unknown users. In any case, you should protect your application against misuse by an attacker, just as you would a CGI or NSAPI program. This section summarizes security considerations for LiveWire applications.

The File object provides access to world-readable files on the server, potentially including password files (such as /etc/passwd). When accessing files in your application, take care that the file name cannot be modified by an attacker. For example, you should avoid using client properties for file names, since the values may be accessible to an attacker through cookies or URLs (depending on the client maintenance technique being used). In such cases, the attacker can modify cookie or URL values to gain access to sensitive files.

Using external libraries can compromise security if you the native program processes a command line entry from the user (for example, a program that allows you to enter operating system or shell commands). This functionality is dangerous because an attacker can attach additional commands using semicolon multi-statement syntax. It is best to avoid command lines, unless you strictly check the input.

In general, you should be suspicious of information from the client, including:

An attacker can manipulate data from these sources to allow access to unauthorized information or capabilities. You should never assume that data from any of these sources is trusted.

Deploying applications

After you have finished developing and testing your application, you are ready to deploy it so that it is available to its intended users. This involves two steps:

You should only move the application web file to the deployment server, along with any standard (uncompiled) HTML files required. In general, you should not deploy source files. You can move files with standard utilities such as FTP or with Site Manager, as described in "Deploying a site."

Note: Before making an application openly available, be sure to read "Security considerations."

Depending on the application, you might want to restrict access to certain groups or individuals. In some cases, you might want anyone to be able to run the application; in these cases you don't need to apply any restrictions at all. If the application displays sensitive information or provides access to the server file system, you should restrict access to authorized users who have the proper username and password, as described in the following section.

Restricting access to applications

You restrict access to an application by applying a server configuration style from your Server Manager. For complete information on using Server Manager and configuration styles, see your server Administrator's Guide.

Using the LiveWire configuration style

A configuration style called "LiveWire" is provided in the Server Manager. To restrict access to Application Manager, apply this style to the /appmgr and /dbadmin Application URLs. You can add other application URLS to this configuration style, or create new ones.

On a development server, you generally want to let developers have access to all LiveWire applications, including Application Manager. On a production (deployment) server, you should restrict access to Application Manager. You might not want to restrict access to other applications, or have less restriction on them. Therefore, you will probably want to create separate configuration styles for applications other than Application Manager.

To apply the LiveWire configuration style to an application:

  1. Access your Server Manager and choose the server on which the application will run.
  2. Choose Config Styles in the upper frame of the Server Manager then click Assign Style in the left frame.
  3. In the Style dropdown list, choose LiveWire.
  4. In the URL prefix wildcard text field, enter the application URL, followed by a slash and an asterisk, "/*". For example, to apply the style to "Hello World," enter "world/*" and click OK.
  5. When you are asked to confirm you actions, choose Save and Apply.

Changing the LiveWire password

 To change the username and password for the LiveWire configuration style:

  1. In your Server Manager choose Access Control in the upper frame, then choose Manage User Databases in the left frame. The Manage User Databases form appears.
  2. Click the This Database radio button.
  3. Choose the user database that has access to the LiveWire configuration style. If you are not sure what database this is, choose Access Control then choose Restrict Access, and click Permissions. The Allow Access to a Resource form will show the database in the User Database field.
  4. Type the database's current password in the Existing Database Password field.
  5. If you don't want to protect this database with a password, click the No Password radio button. To require that a password be used, click the Password button, and type a password in the field. To ensure accuracy, retype the password in the field below. The password can be up to 8 characters long.
  6. Click the Change Database Password button, and confirm your changes.

Adding users to the LiveWire style

 For information on how to create a user databases and on the details of access restriction, see your server Administrator's Guide.

To add users who can access applications protected with the LiveWire configuration style:

  1. Choose Config Styles and then in the left frame choose Edit Style.
  2. Select LiveWire in the Style dropdown list, and choose Restrict Access from the list below the dropdown.
  3. If access control is turned off, turn it on by clicking Turn On Access Control.
  4. For Access Type Read, choose "Deny" under Action. Then click Permissions.
  5. The Allow Access to a Resource form will appear. You can choose to always allow certain hosts, and specify user databases and individual users who will have access. Click Help for information on using this form.
  6. After making your choices, click Done to apply your choices; then click OK in the Restrict Access form.

Creating a new configuration style

 If want to restrict access to an application, but don't want to use the built-in LiveWire configuration style, you can create a new configuration style. To do this:

  1. In your Server Manager, choose Config Styles in the upper frame of the Server Manager.
  2. Initially, New Style will be selected. Enter the name of the style you want to create. For instance, you could create a style called "myapp" for your LiveWire application. Click OK.
  3. The Edit Style form appears. Click Restrict Access
  4. The Restrict Access form appears. Click Turn on access control. The access control restrictions will appear.
  5. Choose "Deny" for both read and write access, then to specify users who will be allowed to access the application, click Permissions for Read access.
  6. The Allow Access to a Resource form appears. You can choose to always allow certain hosts, and specify user databases and individual users who will have access. Click Help for information on using this form. After making your choices, click Done; then click OK in the Restrict Access form.