Client Customization under SRE-http

This document describes SRE-http's client customization facility. In addition to the description, a working example and a configuration tool are included in this document.

Synopsis: the what and how, plus an installation note
Sample: an example of a "tell us your preferences" document.
CUSTOMIZ: a description of the CUSTOMIZ SRE-http addon -- a "client specific" server side include.
MKCUSTOM: a description of the MKCUSTOM SRE-http addon -- it creates data files used by CUSTOMIZ
Configurator: A useful FORM for initializing client configuration (setting defaults, etc.)
Programming aides: some procedures to give REXX programmers easy access to the CUSTOMIZation files.
Current: FYI: your current request headers, including your current cookies.

Back to top

Synopsis

Client customization: granting clients the ability to effect the look and feel of your site.

Whether it's picking the background and icon set, or choosing the types of stories your want to see on a web-newsletter, it's nice to be able to customize the appearance of a set of web pages. SRE-http supports this client customization in a straightforward fashion; one based on cookies and client specific server side includes.

Cookies, which have been around since at least Netscape 1.3 (but, unfortunately, were never supported by Web Explorer) are special pieces of information that a server tells a browser to send the next time(s) the client visits. By judicious use of cookies, SRE-http can efficiently match an incoming request to previously chosen preferences.

Client specific server side includes are, like other server side includes, real time modifications of an HTML document; with the additional feature of reflecting the preferences of the requesting client. Since server side includes can include file replacements and in-line executables, the range of modifications is quite large, and can be achieved with minimal effort -- merely requiring some basic familiarity with SRE-http server side includes.

Briefly stated, the SRE-http strategy is:

Create a set of data that contains a client's preferences (this set will be associated with a cookie).
Tell the client's browser to send the appropriate cookie on future requests (perhaps only for a few selected pages on the site)
When such a request occurs, complete with appropriate cookie, match the cookie to the associated set of data, and use this data to modify client specific server side includes contained in the requested document.

Implement this strategy involves a four step process:

Run the configurator: Using the configurator, initialize the default values for a set of client-selectable options, with defaults for those with cookie-deprived browsers (and you can define many different sets for your different needs).
Create a preference selection FORM: Using the MKCUSTOM add-on, create a FORM that will allow your clients to select their preferences.
Create documents that incorporate client preferences: Using CUSTOMIZ server side includes, create documents that incorporate these client preferences.
Tell your public: link 'em to the preference selection FORM.
sit back and watch....

Installation notes

Installation is described in the READ.ME file. Most of the work is done by the installation program (INSTALL.CMD). Please note that SRE-http support two methods of client customizaton: a simple method and a flexible method. This document focuses on the flexible method; please see CUSTOM.SHT for a discusson of the simple method.

Back to top

Sample of a client customization FORM

This demonstrates how one can set up a FORM that enables clients to specify customization options. Feel free to adapt this code for your own use!

Note: this sample assumes you've created a SAMPLES directory under your USERINFO_DIR directory:

The cookies created by this sample will remain valied for 24 hours, and only apply to requests to the /CUSTOM directory.

Client customization: select your preferences!

Welcome to our site's customizer -- you can specify several options that will effect the look and feel of our pages!

Or would you like to see your current (perhaps default) preferences?

After you "save your choices", you'll be redirected to a document that is built using these selections

Back to top

The CUSTOMIZ addon

CUSTOMIZ is an "interpretable" SRE-http addon (note that CUSTOMIZ points to a file named CUSTOMIZ. -- with no extension). In a sense, the CUSTOMIZ addon is a "cookie-aware, client specific REPLACE".

The CUSTOMIZ addon is typically invoked with a server side include (SSI) keyphrase of the form:

              <!-- $ CUSTOMIZ setname.varname , username-- >
for example:
              <!-- $ CUSTOMIZ personal.car -->

where:

username is optional (and usually not specified), and

setname.varname identifies the client specific variable (i.e.; PERSONAL.CAR) to look for. This client specific variable should contain a string (perhaps a string that contains one of the other SSIs), which will then be inserted into the document.

The following contains a detailed descripiton of how CUSTOMIZ finds the value of client specific variables. Beginners looking for a simple example of how CUSTOMIZ is used should first examine the source code for CUSTOM2.SHT.

CUSTOMIZ will parse out setname and varname. In the above example, setname=PERSONAL and varname=CAR.
If setname is not specified (i.e.; a  keyphrase is used) then it is assumed that setname=DEFAULT.
CUSTOMIZ will look for a cookie with a name of setname. In the above example, CUSTOMIZ will look for a cookie named PERSONAL.
This cookie, if it exists, should contain a client identifier. For example, if a PERSONAL=JOEFILE1 cookie exists, then the idenfitier equals JOEFILE1.
If this cookie does not exist, then identifier is set equal to DEFAULT
If username is specified, then the above steps (looking for a cookie) will not be undertaken; instead, the USERNAME will be used as the identifier. Inclusion of a username will negate the client-specific aspect of CUSTOMIZ. Therefore, it should only be used in special circumstances.
A ".CLI" data file, containing client specific information, is then loaded. The name of this file is constructed using the SRE-http USERINFO_DIR parameter (or the TEMPFILE_DATA parameter, if you are using an older version of SRE-http), the setname, and the identifier.
For example:
If USERINFO_DIR=D:\GOSERVE\USERINFO, and
SETNAME=PERSONAL, and
a PERSONAL=JOEFILE1 cookie exist.
Then D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CLI will be loaded.
However, if there is no PERSONAL cookie, or
D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CLI does not exist
then D:\GOSERVE\USERINFO\PERSONAL\DEFAULT.CLI will be loaded.
Furthermore, if setname was not specified, then
then D:\GOSERVE\USERINFO\DEFAULT.CLI will be loaded.
Note that a .CLI extension is always assumed.
If one of the files derived in step 4 can be found, CUSTOMIZ will extract the varname variable from this .CLI data file. If no file can be found, an error comment is returned.
The CUSTOMIZ "keyphrase" is replaced by this value. For example, if D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CLI contains a:
CAR=<B>Honda Accord</B>
varname entry, then Honda Accord will be inserted into the document.

Back to top

The MKCUSTOM addon

As discussed above, CUSTOMIZ requires special .CLI data files. The easiest method of creating such files is through the MKCUSTOM SRE-http addon. Typically, MKCUSTOM will be invoked by a "tell us your preferences" HTML document filled out by interested clients (such as the above sample). On occasion, as when setting up DEFAULTS, you (the webmaster) will need to invoke MKCUSTOM, often by calling the configurator.

MKCUSTOM recognizes nine parameters:

SETNAME (required)
IDENTIFIER optional, usually not used)
PASSWORD (optional)
NODELETE (optional)
VAR.varname (required)
RESPONSE (recommended)
EXPIRE (recommended)
PATH (optional)
INIT (SUPERUSERs only)

Summarizing MKCUSTOM options

SETNAME and VAR.varname are required: simple client customization schemes can ignore all the other options; in which case:
Clients will not be permitted to modify their options,
the options apply to all documents on your site, and
the options are only valid for the current browser session
Although not required, RESPONSE is recommended: the generic response is pretty mundane.
IDENTIFIER, PASSWORD, and NODELETE are useful only if the client is allowed to modify her customization options.
EXPIRE and PATH are immediately used to set cookies (they are not stored).
If you want the client's options be to long lasting, use the EXPIRE option.
INIT is only used, by SUPERUSERs, to "initialize a SETNAME".

Although the following documentation is thorough, it's probably overly complicated for beginners. To get started quickly, we highly recommend viewing the ===SAMPLE=== section in this document's HTML source code.

SETNAME

SETNAME identifies the "set of variables". The idea is that you may have several distinct sets of documents on your server; the use of setname allows you to assign different sets of client customization options to each of these sets of documents.

Technically speaking, SETNAME should identify an existing subdirectory of the SRE-http USERINFO_DIR directory (recollect that .CLI files will be loaded from this subdirectory). Thus, on FAT systems the value of SETNAME should never be more than 8 characters long.
Typically one will use a "hidden" FORM element to indicate the value of setname. For example:
```
       < INPUT TYPE="hidden" NAME="SETNAME"  VALUE="FAMILY" > 
```
If you do not specify a SETNAME, a DEFAULT setname will be used (it implicitily points to the root of the USERINFO_DIR directory).
Note that CUSTOMIZ (and MKCUSTOM) are not host-aware. If you are running a multiple host server, just be sure to use unique values of SETNAME (i.e.; PERSONAL1 for documents under www1.foo.net and PERSONAL2 for documents under www2.foo.net).

IDENTIFIER

IDENTIFIER identifies who the client is.

Technically speaking, IDENTIFIER should identify a not necessarily existing ".CLI" file under the SETNAME subdirectory. Thus, on FAT systems the value of IDENTIFIER should never be more than 8 characters long.
If you do not specify IDENTIFIER, MKCUSTOM will generate a random name. This is often sufficient, since MKCUSTOM will tell the client's browser (using a cookie) the value of this IDENTIFIER (that is,human eyes need never see the value of IDENTIFIER).
If an IDENTIFIER ".CLI" file already exists, it will be modified. If security is a concern, you can:
- Not specify an identifier. Since this means the legitimate client can not change his preferences, you might want to
- use a PASSWORD parameter.
- Or, if you do not want to permit modifications, use the NODELETE parameter.
Example:
<INPUT type="text" name="identifier" size=8 > Enter your username

PASSWORD

PASSWORD is used to control access to a pre-existing IDENTIFIER file. That is: when PASSWORD is specfied, a pre-existing IDENTIFIER file must contain a matching PASSWORD.

If IDENTIFIER is not specified, PASSWORD is ignored.
If the IDENTIFIER file does not contain a PASSWORD entry, then PASSWORD is ignored (and access will be granted)
If the PASSWORD does not match the password in the identifier file, an error response is returned to the client.
The password stored in the IDENTIFIER file is set when the file is first created. Thus, the password stored in the IDENTIFIER file can not be modified.
Example:
<INPUT type="password" name="password" size=8 > Enter your password

NODELETE

NODELETE is used to prevent overwriting of pre-existing IDENTIFIER files. If NODELETE is specified with a value of 1, selection of a pre-existing IDENTIFIER will result in an error response. Furthermore, when an IDENTIFIER file is first created with NODELETE=1, then MKCUSTOM will never modify or delete it (even if invoked at a later date without a NODELETE parameter).

If IDENTIFIER is not specified, NODELETE is ignored.
If a client wishes to change options, and NODELETE is used, she'll have to select a different value for IDENTIFIER. This can result in orphaned files!
Typically one would use a "hidden" FORM element to indicate the value of NODELETE. For example:
< INPUT TYPE="hidden" NAME="NODELETE" VALUE="1" >
If PASSWORD is used, NODELETE is ignored.

VARS.varname

At least one VARS.varname statement is required: they should contain the values to save. The varname "tail" should be the name of the varname to save.

One will often have multiple VARNAME entries (assuming there is more then one client customizable option).
Each VARNAME (and, of course, it's value) will be stored in the file specified by SETNAME and IDENTIFIER.

Example:

 <INPUT TYPE="text" NAME="VAR.HELLO" size=20> Enter an optional message

 <INPUT TYPE="radio" NAME="VAR.SHOWTIME"
            VALUE="&lt;!-- replace time --&gt;"  Selected > Display the time?
 <INPUT TYPE="radio" NAME="VAR.SHOWTIME"
            VALUE="&lt;!-- replace URL --&gt;"   > or display the URL?

Note that the values can be any text string, including SSI keyphrases. But be sure to use URL-encoding (i.e.; use < for <).

Do not use numeric varnames (they are reserved for future use).
If you start a varname with a !, it will only be displayed to clients with SUPERUSER privileges.
The following varnames are reserved: !NODELETE !EXPIRE !PATH !PASSWORD !CREATION !WHO !IDENTIFER

RESPONSE

A response file, typically an HTML document. After submission, CUSTOMIZ will redirect the client to this response file. Thus, RESPONSE should be a valid URL (though you need not specify the servername).

Typically one will use a "hidden" FORM element to indicate the value of RESPONSE. For example:
< INPUT TYPE="hidden" NAME="RESPONSE" VALUE="/CUSTOM/RESPABC.HTM" >
If RESPONSE is not specified, a generic response is returned.

EXPIRE

EXPIRE is used to set the EXPIRATION date for this to include SETNAME cookie (for the current client) -- the value of EXPIRE will be the number of days this cookie will be active.

EXPIRE=0 means "cookie will not be activated.
If not specified, the cookie will be activated just for the current browser session (it will be discarded when the browser is shut down).
You can use fractions. For example, EXPIRE=0.1 means 2.4 hours.
Typically one will use a "hidden" FORM element to indicate the value of EXPIRE. For example:
< INPUT TYPE="hidden" NAME="EXPIRE" VALUE="30" >

PATH

This is used to specify what PATH of documents the SETNAME cookie should be applied to.

If not specified, a PATH=/ is assumed.
IF EXPIRE=0, then PATH is ignored.
Typically one would use a "hidden" FORM element to indicate the value of PATH. For example:
< INPUT TYPE="hidden" NAME="PATH" VALUE="/MOONPROJ" >
WARNING: Netscape is Case Sensitive -- so you must be sure that your PATH= case matches the case used in your links.

INIT

When INIT is set to 1, then MKCUSTOM will create DEFAULT.CLI in the SETNAME directory, and insert the specified VAR.varname variables.

If DEFAULT.CLI exists in SETNAME, the selected variables will be added (that is, this DEFAULT.CLI file will not be appended to).
When INIT is selected
If necessary, a SETNAME directory will be created.
EXPIRE and PATH are ignored (cookies are not set),
IDENTIFIER, PASSWORD, and NODELETE are ignored: IDENTIFIER is set to DEFAULT, and (only) SUPERUSERs can modify the file at a later date.
A generic RESPONSE is returned.
Only clients with SUPERUSER privileges can use INIT.

Back to top

Configurator

This configurator will initialize a DEFAULT.CLI file for the chosen SETNAME. Up to 8 variables can be defined:

if you need to define more variables... just re-configure the same SETNAME, and specify new variable names (the old variables are retained).

Select the SETNAME:

Specify the names, and default values, of up to 8 variables:

Variable Name and it's default value

or ...

Back to top

Programming Aides

Ambitious REXX programmers may want to create their own scripts for analyzing and manipulating the CUSTOMization files (the .CLI files). To ease this burden, a small set of useful procedures are provided. If you are using version 1.2k.1097b (or later) of SRE-http, these procedures are available in "REXX macrospace". Otherwise, you can use the CUSTOMIZ.SRF file (it should be in the SRE-http ADDON directory) -- just include CUSTOMIZ.SRF in your REXX program.

The following documents the what's and how's. You should also try the examples & sample code contained in TESTCUST.HTM and in TESTCUST.CMD.

Short Descriptions

SREF_SETNAME_STATUS(setname,username,varname): Returns 1=success, S-no setname, U-no username, V=no varname
SREF_SETNAME_SEARCH(setname,varname,target,nth,match_type,sort_by): Find the username that contains the nth match to the target value of varname, in the setname directory (sorting files using sort_by)
SREF_SETNAME_VALUE(setname,username,varname,newvalue): Extract the value of the varname variable from the username file in the setname directory. If new value specified, change/save it's value.

In greater detail

SREF_SETNAME_STATUS(setname,username,varname)
    Returns status information:  does the USERNAME (.CLI file) in the
    SETNAME (directory) contain a VARNAME variable.   When specifying
    SETNAME and VARNAME, do NOT include path and extension.

  Possible returns  are:
            1 = Success (varname exists)
            S = No such setname
            U = No such username (but setname does exist)
            V = No such varname (but varname does exist)

   Example: status=sref_setname_status('sample','joe10','fontsize')


SREF_SETNAME_SEARCH(setname,varname,target,nth,match_type,sort_by)

     Finds the USERNAME, in the SETNAME directory, that is the NTH match
     to the TARGET value of the VARNAME variable.
     Returns the USERNAME that contains this match.

     Options: Use the MATCH_TYPE "matching criteria", and sorts
              the USERNAME files by SORT_BY before looking for matches.

     Special Case: If VARNAME=*, then return a spaced delimited list of
                   all the usernames in this setname.
 
     If there is no match (or one of setname, username, or varname does
     not exist), a 0 is returned.

     If nth=0, then returns the number of matches (or 0 if no matches).
     Note that if there are M<nth matches, a 0 is returned.

     Match_type can equal:
            I = case Insensitive matches
            S = strip spaces
           IS = case insensitive, and strip spaces
            * = Wildcard match: case insensitive, strip spaces, and treat
                * characters as wildcards

     Sort_by can equal:
           N = sort by name
           D = sort by creation date (newest first)
 
   Example: status=sref_setname_search('sample','city','Boston',1,'IS','D')
          finds the most recent username whose "city" equals "Boston"
          using a case insensitive search,
          ignoring leading/trailing spaces


SREF_SETNAME_VALUE(setname,username,varname,newvalue)

     Extract the value of the VARNAME variable from the USERNAME (file)
     in the SETNAME directory. If newvalue is specified, replace
     this value with the value of newvalue.

     Special Case: If VARNAME=*, then return a space delimited list of
                   variables available for this setname & username.

     Example: avalue=sref_setname_value('customer','jondoe','age',55)
           Find the "AGE" variable of the JONDOE username (in
           CUSTOMER directory).  Change it's value to 55.

Back to top

Your current request headers

Cookies, if any were specified, are in the row(s) after the Cookie: line.

accept: */*
user-agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
host: www.srehttp.org