Web Application Module

Intro
Installation
SysAdmin
Network
Objects
Transfer
Access
Services
Directory
Data Files
Clusters
WebApp
WSSP 
AppCodes 
WebMail
Miscellaneous
HowTo
HelpMe
Licensing
The CommuniGate Pro Web Application module provides access to various CommuniGate Pro objects (accounts, messages, mailing lists, web files) via any Web (HTTP/HTML/WML) browser.

The HTTP module receives HTTP client browser requests that come to the WebUser port(s), and passes those requests to the Web Application module. The Web Application module either retrieves the requested file, or it starts some internal web application code and converts the result into the HTML, WML or other markup format. The result is returned to the HTTP module that delivers it back to the client browser.

Read this section if you want to customize your CommuniGate Pro Server Web User Interface.

Stateless and Session-based Processing

Regular HTTP servers are stateless processors: a user's browser may send several sequential requests, but the HTTP server does not keep any information about the browser or the client between the requests. Each request is processed individually.

The Web Application Server allows users to "log in", providing a name of some CommuniGate Pro Account and the account password. For each successful login, a Session is started. The session keeps the information about user actions and requests, so all HTTP requests sent to the same session can share and use the same set of session data. To maintain a session, all session requests have URLs in the following form:

http://hostname:serverport/Session/sessionID/sessionRequest
where the sessionID string identifies the session, and the sessionRequest is the name of the file to retrieve or the application component to run.

The Web Application Sessions have time-out counters. If no HTTP request has been sent to a session during the configurable time-out interval, the Session is closed. The session user can close the session by sending a request for the special Bye page.


Skins

The hostname string specified in a stateless request URL is used to find the CommuniGate Pro Domain. Each Domain may have a custom Unnamed Skin - a set of files that an HTTP request can retrieve. Since different Domains have different Unnamed Skins, the same request sent to different Domains can retrieve different data.

If a Domain does not have an Unnamed Skin, the server-wide Unnamed Skin is used.

The CommuniGate Pro Server software comes with a Stalker-designed Skin, called the stock Unnamed Skin. This Skin is stored in the application directory, it is a part of the software package, and it should not be modified by server administrators.

If a requested file is not found in the Unnamed Domain Skin, the Web Application module tries to retrieve a file with the specified name from the server-wide Unnamed Skin. If the file is not found in the server-wide Unnamed Skin, the module tries to find that file in the Stock Skin.

Initially, when no Domain has an Unnamed Skin, and the server-wide Unnamed Skin is empty, all Domains effectively use the Stock Skin. By uploading files into the server-wide Unnamed Skin, the server administrator can "shadow" the Stock Skin files, and can change the application look and feel for all Domains. By uploading files into the Domain Unnamed Skin, the Server or Domain Administrator can "shadow" the Stock Skin and server-wide Unnamed Skin files and change the look and feel for that particular Domain.

The session-based HTTP requests do not use the hostname string specified in the URL. Instead, when a user logs in, and a Web Application session is created for the specified CommuniGate Pro Account, the Account WebUser preferences are retrieved. Those preferences contain the name of the Skin to use. If this name is empty, then the Unnamed Skin for the Account Domain is used. If that Domain does not have an Unnamed Skin, the server-wide Unnamed Skin is used.

If the Account WebUser preferences specify a non-empty Skin name, the Web Application module tries to open a Named Skin. Each Domain can have several Named Skins, and if the Domain has the Named Skin with the specified name, it is used. If the Domain does not have the specified Named Skin, the module tries to find the server-wide Named Skin with the specified name. If it cannot find it, the server-wide Unnamed Skin is used.

The Stateless requests usually use the Unnamed Skin for the addressed Domain. To retrieve a file from a Named Skin, the request should include the Skin parameter that specifies the Skin Name.

When the Web Application module needs to retrieve a file from a Named Skin, and the Domain Named Skin does not contain a file with the specified name, the module looks for a server-wide Named Skin with the same name, and tries to retrieve the file from that Skin. If the file is not found again, the module tries to retrieve the file from the server-wide Unnamed Skin, and then - from the Stock Skin.

This hierarchy of Skins allows Server and Domain Administrators to provide different, custom look and feel for different Domains and for different users, and simplifies Skin development by providing server-wide Skins used as the source of "default" files.

The Dynamic Cluster installations have two sets of the server-wide Skins - one set is used for local Server Domains, while the other, Cluster set is used for all Shared Domains in the Cluster. Modifications of these server-wide Skins, as well as modifications of the Shared Domain Skins are automatically distributed to all Cluster Members.


Skin Text Dataset

Each Skin can have a Text Dataset - the strings.data text file containing a dictionary. The WSSP Script pages can use various commands to retrieve data from this Skin Text Dataset.

When the Text Dataset of the selected Unnamed Domain Skin does not contain the requested data, the Text Dataset of the server-wide Unnamed Skin is checked. If it does not contain the requested data, the Text Dataset of the Stock Skin is checked.

When the Text Dataset of the selected Named Domain Skin does not contain the requested data, the Text Dataset of the server-wide Named Skin (with the same name) is checked. If it does not contain the requested data, the Text Dataset of the server-wide Unnamed Skin is checked. If it does not contain the requested data, the Text Dataset of the Stock Skin is checked.

When placing non-ASCII symbols strings into the Skin Text Dataset, the UTF-8 character set should be used. Check the http://www.unicode.org site to learn more about Unicode and the UTF-8 charset.


Serving Regular Files

When a URL specifies a file with any file name extension other than .wssp, the Web Application module retrieves this file from the selected Skin, places it into the internal Skin Cache, and returns that file to the client browser via the HTTP module connection.

The specified file names are always converted into the lowercase letters.

When the Web Application module receives a request for the same file, it is retrieved from the Skin Cache.

If the file has been requested using a Session-based URL, the session time-out counter is reset. This can be used to create a frame in the client browser window, and make that frame periodically retrieve some file using the session URL. As a result, this session inactivity timer can be reset to keep the session alive as long as this frame is displayed in the user's browser.

System and Domain administrators can upload custom files into server-wide and Domain Skins to modify the Web Application look and feel.
For example, the Stock Skin uses the Logo.gif file for most of its pages. By uploading a custom Logo.gif file to a server-wide Unnamed Skin you can change the look of the Web Application pages even without creating and uploading custom page (WSSP) files.

To include a file reference to into a .wssp page retrieved with a Stateless request, use the %%filesRef%% prefix in the .wssp code:

HREF="%%filesRef%%filename.extension"
See the Code Components for Stateless Requests section for more details.

Sessions can used Named Skins, and the session-based pages usually need to refer to regular files in the same Skin. References in the "session realm" (HREF="filename.extension" or HREF="/Session/sessionID/filename.extension" work, but they do not allow client browsers to cache these files between sessions, since each session has its own sessionID, and file URLs are different for each session. To allow client browsers to cache regular files, use the %%SESSION(filesRef)%% prefix for file URLs:

HREF="%%SESSION(filesRef)%%/filename.extension"
See the Session Dataset description for more details.


Serving Web Application (WSSP) Files

When a URL specifies a resource with the .wssp file name extension, the Web Application module retrieves the specified WSSP file from the Skin, and Compiles it into some internal code. The module then runs the Web Application code associated with the file name. This code produces a dataset with various string, array, and dictionary data. Then the module runs the WSSP internal (compiled) code to produce an HTML page using this dataset, and returns the resulting HTML page to the browser using the HTTP module connection.

The specified resource names are always converted into the lowercase letters.

The WSSP Scripting section explains the WSSP file format. System and Domain administrators can create custom WSSP files and upload them to the server-wide and Domain Skins to modify the Web Application look and feel.

The Code Components section lists the available Web Application code components, defining the set of WSSP pages that this version of CommuniGate Pro server can generate. It specifies how each component processes the form parameters sent to it, and what data is included into the dataset it generates.


Creating and Managing Skins

The same type of WebAdmin Editor is used to manage server-wide and Domain Skins.

To manage the server-side Skins, open the Domains realm of the WebAdmin Interface, and click the Skins link.

To manage the Domain Skins, open that Domain page in the Domains realm of the WebAdmin Interface, and click the Skins link. The Domain Administrator should have the CanModifySkins Access Right to be able to create and modify the Domain Skins.

The Skins Editor page appears. If the Domain Skins Editor is opened, and there is no Unnamed Skin for that Domain, the page contains the Create Unnamed Skin button. Click this button to create the Unnamed Skin for this Domain.

The Skin Editor page contains the list of all files "visible" in this Skin: it lists files directly uploaded to this particular Skin, as well as all files uploaded to the Skins that work as the "default files" source for this Skin:

Marker File NameSizeModified
Help.gif15525-Sep-01
defaultaddressbook.wssi114323-Sep-01
defaultalerts.wssp172726-Sep-01
defaultansweredletter.gif89027-Feb-99
defaultattachedFile.gif114727-Feb-99
...
defaultmailbox.wssp580628-Sep-01
mailboxes.wssp345202-Oct-01
...
defaultwebsite.wssp59228-Sep-01
defaultwebsitebody.wssi264828-Sep-01

Files directly uploaded to the Skin have a checkbox in the Marker column. Files from the other skins "visible" in this Skin have the word default in that column.

You can download any of the Skin files by clicking the file name.

You can upload a file to the Skin by clicking the Browse button and selecting the file on your workstation, then clicking the Upload button.

You can delete any of the files uploaded to the Skin by selecting the checkboxes and clicking the Delete Marked button.

If you are uploading a .wssp or a .wssi file, the Editor tries to compile that file first. If the compiler parser detects an error, the file is not uploaded, the source of the file is displayed on the Editor page, with the red <--ERROR--> marker indicating the location of the error.

When you upload a file to any Skin, that Skin cache is automatically cleared. If you upload a file to a Shared Domain Skin or to a Cluster-wide Skin, the update automatically propagates to all Cluster Members.

You can upload a set of files by uploading a TAR-archive (a file with .tar name extension). For example, when you have a TAR-archive with a predesigned Skin you can open the Skin you want to modify (the Server-wide Unnamed Skin or Domain-wide Unnamed Skin or some Named Skin), and upload the .tar file. The Server will unpack the archive and store each file individually, as if they were uploaded one-by-one.

The Editor page for the Unnamed Skin contains the list of all Named Skins:

Named Skins
Marker Skin Name
German
IceColdMail
:

To create a Named Skin, enter its name, and click the Create Skin button.

To remove Named Skins, use the checkboxes to select the Skins, and then click Remove Marked button. Only empty Skins (Skins without any files) can be removed.

To remove the Unnamed Skin, remove all its files and all Named Skins, and then click Remove Unnamed Skin button.

To open a Skin, click its name. The Editor will display the Skin Name, and it will provide the UP link to the Unnamed Skin page.

The Named Skin Editor allows you to rename the Skin by entering a new Skin Name and clicking the Rename Skin button.


CommuniGate® Pro Guide. Copyright © 1998-2004, Stalker Software, Inc.