Mechanics of Developing JavaScript Applications

jsac [-h] [-c] [-v] [-d] [-l]
   [-o outfile.web]
   [-i inputFile]
   [-p pathName]
   [-f includeFile]
   [-r errorFile]
   [-a 1.2]
   script1.html [...scriptN.html] 
   [funct1.js ... functN.js]

Items enclosed in square brackets are optional. The syntax is shown on multiple lines for clarity. The scriptN.html and functN.js files are the input files to the compiler. There must be at least one HTML file. By default, the HTML and JavaScript files are relative to the current directory. Files you specify must be either JavaScript files or HTML files; you cannot specify other files, such as GIF files.

On all platforms, you may use either the dash (-) or the forward slash (/) to indicate a command-line option. That is, the following lines are equivalent:

jsac -h
jsac /h

Note that because the forward slash indicates a command-line option, an input file cannot start with a forward slash to indicate that it is an absolute pathname. That is, the following call is illegal:

jsac -o myapp.web /usr/vpg/myapp.html

This restriction does not apply to any of the pathnames you supply as arguments to command-line options; only to the input files. On NT, you can instead use backslash (\) to indicate an absolute pathname in an input file, as in the following call:

jsac -o myapp.web \usr\vpg\myapp.html

On Unix, you must use the -i command-line option to specify an absolute pathname, as described below.

The following command-line options are available:

-h: Displays compiler syntax help. If you supply this option, don't use any other options.

-c: Checks syntax only; does not generate a web file. If you supply this option, you do not need to supply the -o option.

-v: (Verbose) Displays information about the running of the compiler.

-d: Displays generated JavaScript contents.

-l: Specifies the character set to use when compiling (such as iso-8859-1, x-sjis, or euc-kr)

-o outfile: Creates a bytecode-format web file, named outfile.web. If you do not supply this option, the compiler does not generate a web file. (Omit this option only if you're using the -c option to check syntax or -h to get help.)

-i inputFile: Allows you to specify an input file using its full pathname instead of a relative pathname. You can provide only one filename to this option. If you need to specify multiple filenames using full pathnames, use the -f option.

-p pathName: Specifies a directory to be the root of all relative pathnames used during compilation. (Use before the -f option.) You can provide only one pathname to this option.

-f includeFile: Specifies a file that is actually a list of input files, allowing you to circumvent the character limit for a command line. You can provide only one filename to this option. The list of input files in includeFile is white-space delimited. If a filename contains a space, you must enclose the filename in double quotes.

-r errorFile: Redirects standard output (including error messages) to the specified file. You can provide only one filename to this option.

-a 1.2: Changes how the compiler handles comparison operators on the server. For more information, see "Comparison Operators".

For example, the following command compiles and links two JavaScript-enhanced HTML pages, main.html and hello.html, and a server-side JavaScript file, support.js, creating a binary executable named myapp.web. In addition, during compilation, the compiler prints progress information to the command line.

jsac -v -o myapp.web main.html hello.html support.js

As a second example, the following command compiles the files listed in the file looksee.txt into a binary executable called looksee.web:

jsac -f looksee.txt -o looksee.web

Here, looksee.txt might contain the following:

looksee1.html
looksee2.html
\myapps\jsplace\common.js
looksee3.html

Installing a New Application

You cannot run an application and clients cannot access it until you install it. Installing an application identifies it to the server. After you have installed the application, you can rebuild and run it any number of times. You need to reinstall it only if you subsequently remove it. You can install up to 120 JavaScript applications on one server.

Before you install, you must move all application-related files to the correct directory, by publishing the files. Otherwise, you'll get an error when you install the application. For security reasons, you may not want to publish your JavaScript source files on your deployment server. See "Application URLs" for restrictions on where you can place your files.

Important For security reasons, you should never store sensitive information such as passwords in your .web file. If you do, someone can potentially access that information.

To install a new application with the Application Manager, click Add Application. In response, the Application Manager displays, in its right frame, the form shown in Figure 3.3.

Figure 3.3 Add Application form

Fill in the fields in the Add Application form, as follows:

Name: the name of the application. This name defines the application URL. For example, the name of the Hello World application is "world," and its application URL is http://server.domain/world. This is a required field, and the name you type must be different from all other application names on the server. See "Application URLs".

Web File Path: the full pathname of the application web file. This is a required field. For example, if you installed the Netscape server in c:\nshome, the web file path for the Hello World application is c:\nshome\js\samples\world\hello.web.

Default Page: the page that the JavaScript runtime engine serves if the user does not indicate a specific page in the application. This page is analogous to index.html for a standard URL.

Initial Page: the page that the JavaScript runtime engine executes when you start the application in the Application Manager. This page is executed exactly once per running of the application. It is generally used to initialize values, create locks, and establish database connections. Any JavaScript source on this page cannot use either of the predefined request or client objects. This is an optional field.

Built-in Maximum Database Connections: the default value for the maximum number of database connections that this application can have at one time using the predefined database object. JavaScript code can override what you specify in this setting when it calls the database.connect method.

External Libraries: the pathnames of external libraries to be used with the application. If you specify multiple libraries, delimit the names with either commas or semicolons. This is an optional field. Libraries installed for one application can be used by all applications on the server. See "Working with External Libraries".

Client Object Maintenance: the technique used to save the properties of the client object. This can be client cookie, client URL, server IP, server cookie, or server URL. See "Techniques for Maintaining the client Object".

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

You must stop and restart your server after you add or change the external libraries for an application. You can restart a server from your Server Manager; see the administrator's guide for your web server for more information.

Application URLs

When you install an application, you must supply a name for it. This name determines the base application URL, the URL that clients use to access the default page of a JavaScript application. The base application URL is of the form

http://server.domain/appName

Here, server is the name of the HTTP server, domain is the Internet domain (including any subdomains), and appName is the application name you enter when you install it. Individual pages within the application are accessed by application URLs of the form

http://server.domain/appName/page.html

Here, page is the name of a page in the application. For example, if your server is named coyote and your domain name is royalairways.com, the base application URL for the hangman sample application is

http://coyote.royalairways.com/hangman

When a client requests this URL, the server generates HTML for the default page in the application and sends it to the client. The application URL for the winning page in this application is

http://coyote.royalairways.com/hangman/youwon.html

Important Before you install an application, be sure the application name you choose does not usurp an existing URL on your server. The JavaScript runtime engine routes all client requests for URLs that match the application URL to the directory specified for the web file. This circumvents the server's normal document root.

For instance, suppose a client requests a URL that starts with this prefix from the previous example:

http://coyote.royalairways.com/hangman

In this case, the runtime engine on the server looks for a document in the samples\hangman directory and not in your server's normal document root. The server also serves pages in the directory that are not compiled into the application.

You can place your source (uncompiled) server-side JavaScript files in the same directory as the web file; however, you should do so only for debugging purposes.

Important When you deploy your application to the public, for security reasons, you should not publish uncompiled server-side JavaScript files. In addition, you should never store sensitive information such as passwords in your .web file. If you do, someone can potentially access that information.

Controlling Access to an Application

When you install an application, you may want to restrict the users who can access it, particularly if the application provides access to sensitive information or capabilities.

If you work on a development server inside a firewall, then you may not need to worry about restricting access while 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 inside the firewall. If you use sample data during the development phase, then the risk is 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. You can restrict access by applying a server configuration style to the application. For information on configuration styles, see the administrator's guide for your web server.

NOTE: Controlling access to applications with configuration styles is available only with Netscape 2.0 servers and later versions.

Modifying Installation Fields

To modify an application's installation fields, select the application name in the left frame of the Application Manager and click Modify.

You can change any of the fields 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 fields of a stopped application, the Application Manager automatically starts it. When you modify fields of an active application, the Application Manager automatically stops and restarts it.

Removing an Application

To remove the selected application, click Remove in the Application Manager. The Application Manager removes the application so that it cannot be run on the server. Clients are no longer able to access the application. If you delete an application and subsequently want to run it, you must install it again.

Although clients can no longer use the application, removing it with the Application Manager does not delete the application's files from the server. If you want to delete them as well, you must do so manually.

Starting, Stopping, and Restarting an Application

After you first install an application, you must start it to run it. Select the application in the Application Manager and click Start. If the application successfully starts, its status, indicated in the right frame, changes 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

Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.

If you want to stop an application and thereby make it inaccessible to users, select the application name in the Application Manager and 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.

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

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

Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.

You must restart an application each time you rebuild it. To restart an active application, select it in the Application Manager and click Restart. Restarting essentially reinstalls the application; the software looks for the specified web file. If there is not a valid web file, then the Application Manager generates an error.

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

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

Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.

Running an Application

Once you have compiled and installed an application, you can run it in one of two ways:

Select the application name in the Application Manager, and then click Run. In response, the Application Manager opens a new Navigator window to access the application.

Load the base application URL in Navigator by typing it in the Location field.

The server then generates HTML for the specified application page and sends it to the client.

Debugging an Application

To debug an application, do one of the following:

Select the application name in the Application Manager, and then click Debug, as described in "Using the Application Manager".

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

You can use the debug function to display debugging information, as described in "Using the debug Function".

Once you've started debugging a JavaScript application in this way, you may not be able to stop or restart it. In this situation, the Application Manager displays the warning "Trace is active." If this occurs, do the following:

Close any windows running the debugger.
Close any windows running the affected application.
In the Application Manager, select the affect application and click Run.

You can now stop or restart the application.

Using the Application Manager

To debug an application, select it in the left frame of the Application Manager and then click Debug. In response, the Application Manger opens a new Navigator window in which the application runs. The trace utility also appears, either in a separate frame of the window containing the application or in another window altogether. (You can determine the appearance of the debug window when you configure the default settings for the Application Manager, as described in "Configuring Default Settings".)

The trace utility displays this debugging information:

values of object properties and arguments of debug functions called by the application

property values of the request and client objects, before and after generating HTML for the page

property values of the project and server objects

indication of when the application assigns new values to properties

indication of when the runtime engine sends content to the client

Figure 3.4 shows what you might see if you debug the Hangman application.

Figure 3.4 Debugging Hangman

Using Debug URLs

Instead of using the Application Manager, you may find it more convenient to use an application's debug URL. To display an application's trace utility in a separate window, enter the following URL:

http://server.domain/appmgr/trace.html?name=appName

Here, appName is the name of the application. To display the trace utility in the same window as the application (but in a separate frame), enter this URL:

http://server.domain/appmgr/debug.html?name=appName

You cannot use these two URLs unless you have access privileges to run the Application Manager. You may want to bookmark the debug URL for convenience during development.

Using the debug Function

You can use the debug function in your JavaScript application to help trace problems with the application. The debug function displays values to the application trace utility. For example, the following statement displays the value of the guess property of the request object in the trace window along with some identifying text:

debug ("Current Guess is ", request.guess);

Deploying an Application

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:

moving the application from the development server to the deployment (production) server that is accessible to end users

applying or changing access restrictions to the application, as appropriate

You should move the application web file to the deployment server, along with any images and uncompiled HTML and JavaScript files that are needed. For more information on how to deploy your application files, see the Web Publisher User's Guide.

Important When you deploy your application to the public, for security reasons, you should not publish uncompiled server-side JavaScript files. In addition, you should never store sensitive information such as passwords in your .web file. If you do, someone can potentially access that information.

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 user name and password.

You restrict access to an application by applying a server configuration style from your Server Manager. For information on using Server Manager and configuration styles, see the administrator's guide for your web server.