client

Created by

Description

You cannot use the client object on your application's initial page. This page is run when the application is started on the server. At this time, there is not a client request, so there is no available client object.

The runtime engine constructs and destroys the client object for each client request. However, at the end of a request, the runtime engine saves the names and values of the client object's properties so that when the same user returns to the application with a subsequent request, the runtime engine can construct a new client object with the saved data. Thus, conceptually you can think of the client object as remaining for the duration of a client's session with the application. There are several different ways to maintain client property values; for more information, see Writing Server-Side JavaScript Applications.

All requests by one client use the same client object, as long as those requests occur within the lifetime of that client object. By default, a client object persists until the associated client has been inactive for 10 minutes. You can use the expiration method to change this default lifetime or the destroy method to explicitly destroy the client object.

Use the client object to maintain data that is specific to an individual client. Although many clients can access an application simultaneously, the individual client objects keep their data separate. Each client object can track the progress of an individual client across multiple requests to the same application.

Method Summary

destroy

expiration

Examples

<SERVER>client.customerId = assignId(request.ip)</SERVER>

Example 2. This example creates a customerId property to store a customer ID that a user enters into a form. The form is defined as follows:

<FORM NAME="getCustomerInfo" METHOD="post">
<P>Enter your customer ID: 
   <INPUT TYPE="text" NAME="customerNumber">
</FORM>

<SERVER>client.customerId=request.customerNumber</SERVER>

See also

Properties

You can create a property for the client object by assigning it a name and a value. For example, you can create a client property to store a customer ID at the beginning of an application so a user does not have to enter it with each request.

Because of the techniques used to maintain client properties across multiple client requests, there is one major restriction on client property values. The JavaScript runtime engine on the server converts the values of all of the client object's properties to strings.

The runtime engine cannot convert an object to a string. For this reason, you cannot assign an object as the value of a client property. If a client property value represents another data type, such as a number, you must convert the value from a string before using it. The core JavaScript parseInt and parseFloat functions are useful for converting to integer and floating point values.

Methods

destroy

Syntax

destroy()

Description

If you are using client-cookies to maintain the client object, destroy eliminates all client property values, but it does not affect what is stored in Navigator cookie file. Use expiration with an argument of 0 seconds to remove all client properties stored in the cookie file.

When using client URL encoding to maintain the client object, destroy removes all client properties after the method call. However, any links in a page before the call to destroy retain properties in their URLs. Therefore, you should generally call destroy either at the top or bottom of the page when using client URL maintenance.

Examples

<server>client.destroy()</server>

See also

expiration

Syntax

expiration(seconds)

Parameters

seconds

Description

Use the expiration method to explicitly control the expiration of a client object, making it longer or shorter than the default. You must use expiration in each page of an application for which you want a client expiration other than the default. Any page that does not specify an expiration will use the default of 10 minutes.

Client expiration does not apply if using client URL encoding to maintain the client object. In this case, client properties are stored solely in URLs on HTML pages. The runtime engine cannot remove those properties.

Examples

<SERVER>client.expiration(3600)</SERVER>

See also