Web Application Module

Stateless and Session-based Processing Skins WAP/WML Skins cHTML (I-Mode) Skins Skin Files Hierarchy Languages and Skin Text Dataset Serving Regular Files Serving Web Application (WSSP) Files Creating and Managing Skins 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/cHTML) 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 Server WebUser Interface implements Skins. Each Skin is a set of files that define how the information is presented to users. Skins files include:

• WSSP files used to build "web pages" (HTML, WML, etc.) and format the page data.
• static service files - graphic elements, style sheets, etc.
• Language files containing various static text strings (messages, page and button titles, tags, etc.) referenced from WSSP files.

The CommuniGate Pro software comes with one Unnamed Stock Skin, providing the very basic and simple HTML and WML interface. It also comes with some Named Stock Skins that provide more visually rich interfaces. This Stock Skins are stored in the application directory, they are parts of the software package, and they should not be modified by server administrators.

CommuniGate Pro installations can also use Unnamed and Named custom Skins. Custom Skins can be created as Server-wide Skins. These custom Skins are available to all users. Each CommuniGate Pro Domain can also have its own set of custom Skins, available only to the users of that Domain.

When a user connects to the Web User Interface service (the HTTP User port), the hostname string specified in a stateless request URL is used to find the CommuniGate Pro Domain. When the Domain is found, its Default Account WebUser Preferences are retrieved and the SkinName (Layout) and Language Settings are used.

The SkinName Setting specified the name of the Skin to use (if that Setting is empty, the Unnamed Skin is used).

If the Skin with the specified Name is not found in the set of the Domain Skins, the Server-wide Skin sets are checked. If the Skin with the specified name is still not found, the Stock Skin with this name is used. If the Named Stock Skin is not found either, the Unnamed Stock Skin is used.

Since Domains can have their own Skin sets, the same request sent to different Domains can display different pages: the Default WebUser Preferences can specified different Skin Names in different Domains, and even if the Preferences are the same, different Skins with the same name can exist in different Domains.

Stateless requests can use any Skin available for the addressed Domain. To use an alternative Skin, a Stateless HTTP request should specify the Skin name using the Skin request parameter.

The Language Setting retrieved from the Domain effective Default Account WebUser Preferences specifies the language to use on the stateless page. To use an alternative language, a Stateless HTTP request should specify the language name using the Language request parameter.

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 effective Account WebUser preferences are retrieved. Those preferences contain the name of the Skin to use (an empty value specifies an Unnamed Skin). The Skin with the specified name is selected from the Skin set of the Account Domain (note that the Domain specified with the request URL can be different).
If the Account Domain does not have the specified Skin, the Server-wide Skin is used.

Session-based HTTP requests use the Language specified with the Account WebUser Preferences.

WAP/WML Skins

The HTTP module checks the content of the Accept request header field. If this field contains a wml substring, the module assumes that the request comes from a WML browser.

Requests coming from WML browsers are processed using WML Skins. For Stateless requests the name of the Skin to use is taken from the WAP/WML Layout parameter of the Default WebUser Preferences for the addressed Domain. When a user logs in using a WML browser, the name of the Session Skin to use is taken from the WAP/WML Layout parameter of the WebUser Preferences for the user Account.

All Skins with names starting with letters WML are considered to be WML Skins. These Skins appear in the list of available Skins for the WAP/WML Layout parameters, and these Skins are removed from the list of available Skins for the regular Layout parameters.

cHTML (I-Mode) Skins

The HTTP module checks the content if the User-Agent request header field.
If this field contains a DoCoMo substring, the module assumes that the request comes from a Japanese I-Mode browser.
If this field contains a portalmmm substring, the module assumes that the request comes from a European I-Mode browser.

I-Mode requests are processed with special I-Mode Skins in the same was as WML requests are processed with WML Skins. The special I-Mode/cHTML WebUser Preferences parameter is used to specify the name of the I-Mode Skin to use.

All Skins with names starting with letters IMode are considered to be cHTML Skins. These Skins appear in the list of available Skins for the I-Mode/cHTML Layout parameters, and these Skins are removed from the list of available Skins for the regular Layout parameters.

For all pages retrieved for Japanese cHTML browsers the charset is set to Shift-JIS, and all pages are converted into that charset.
For all pages retrieved for European cHTML browsers the charset is set to windows-1252, and all pages are converted into that charset.

Skin Files Hierarchy

When a WebUser Interface request is processed, the Server needs to retrieve certain files from the selected Skin. If the requested file is not found in the selected Skin, and the selected Skin is a Domain Skin, the file is retrieved from the Server-wide Skin with the same name. If the requested file is not found in the Server-wide Skin, the Stock Skin with the same name is checked. If the file is still not found, and the selected Skin is a Named Skin, then unnamed Server-wide and unnamed Stock Skins are checked.

Initially, when no Domain has any custom Skin, and the Server-wide Skins are empty, all Domains can use the Stock Skins only. The Unnamed Skin is selected by default.
By uploading files into the Server-wide Unnamed Skin, the Server Administrator can "shadow" the Unnamed Stock Skin files, and this can change the application look and feel for all Domains.
By uploading files into the Unnamed Skin of some CommuniGate Pro Domain, 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.

This hierarchy allows Server and Domain Administrators to use new Skins that are designed "from scratch", or to develop small Skin variation, re-using the already existing Skins.

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 Cluster-wide Skins, as well as modifications of any Skin in any Shared Domain are automatically distributed to all Cluster Members.

Languages and Skin Text Dataset

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

A Skin can contain additional, localized Text Dataset files - language.data files, where language is the language name (french.data, japanese.data, etc.). If a non-default language is selected, the Text Dataset from the specified language file is used.

When the selected Text Dataset of the selected Skin does not contain the requested data, the same language Text Datasets are checked in all Skin "parents" (as specified above). If the requested data is still not found, the "default language" Text Dataset is used.

Use the UTF-8 character set to place non-ASCII symbols strings into a Text Dataset file. 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 WebAdmin Interface provides Skin Editor pages to manage Server-wide, Cluster-wide, and Domain Skins.

To manage the Server-wide and Cluster-wide 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.

When the Domain Skins Editor page is opened, and there is no Unnamed Skin for the 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 used as the "default files" source for this Skin:

Marker  File Name Size Modified Help.gif 155 25-Sep-04 default addressbook.wssi 1143 23-Sep-03 default alerts.wssp 1727 26-Sep-04 default answeredletter.gif 890 27-Feb-03 default attachedFile.gif 1147 27-Feb-03 ... default mailbox.wssp 5806 28-Sep-04 mailboxes.wssp 3452 02-Oct-01 ... default strings.data 28K 27-Oct-04 default german.data 31K 28-Oct-04 ... default website.wssp 592 28-Sep-04 default websitebody.wssi 2648 28-Sep-04

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 a 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 GoldenFleece 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.