CUSTOMIZE: Client Customization for OS/2 Web Servers

This document describes CUSTOMIZE: a client customization facility for OS/2 web servers.

Summarizing the contents of this document:

• Synopsis: the what and how, plus some installation notes
• Sample: an example of a "tell us your preferences" document.
• CUSTCGI: a description of CUSTCGI -- a "client specific", #EXEC invoked, server side include.
• MKCUSTCG: a description of the MKCUSTCG CGI-BIN script -- it creates data files used by CUSTCGI
• Configurator: A useful FORM for initializing client configuration (setting defaults, etc.)

Note that CUSTOMIZE is adapted from an addon created for the SRE-http web server. Since the SRE-http version uses direct calls, it is often substantially faster then this, the CGI-BIN compliant, version.

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

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, CUSTOMIZE 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.

Briefly stated, CUSTOMIZE's strategy is:

1. Create a set of data that contains a client's preferences (this set will be associated with a cookie).
2. Tell the client's browser to send the appropriate cookie on future requests (perhaps only for a few selected pages on the site)
3. 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.

Given that your OS/2 web server...

• supports CGI-BIN. and
• understands the #EXEC cmd= server side include (an NCSA-style server side include);

1. Run the configurator: Using the CUSTOMIZE 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).
2. Create a preference selection FORM: Create an HTML FORM to allow your clients to select their preferences -- this form will invoke the MKCUSTCG.CMD cgi-bin script.
3. Create documents that incorporate client preferences: Using CUSTCGI in server side includes, create documents that incorporate these client preferences.
4. Tell your public: link 'em to the preference selection FORM.
5. sit back and watch....

Installation notes

Of particular importance is the initialization of several parameters; including:

• USERINFO_DIR : Location of "client preferences" files.
• GMT_OFFSET: Hours difference from GMT (used for creating expiration dates)
• SUPERUSER: List of IP address to be granted superuser privileges (i.e; initialization rights)
• DATA_DIR: Root directory of your HTML documents (used for resolving the location of response files)

Depending on your web server, you might also have use special extensions for HTML documents that contain server side includes (i.e.; .SHTML instead of .HTML). If so, you'll need to change references (in this document) from CUST_CGJ.HTM to CUST_CGJ.whatever (i.e.; CUST_CGJ.SHT).

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

Client customization: select your preferences!

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

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

              <!-- #exec cmd="Custcgi?setname.varname" -- >
for example:
              <!-- #exec cmd="Custcgi?personal.car" -- >

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

1. CUSTCGI will parse out setname and varname. In the above example, setname=PERSONAL and varname=CAR.

   If setname is not specified (i.e.; a <!-- #exec cmd="custcgi?varname" --> keyphrase is used) then it is assumed that setname=DEFAULT.

2. CUSTCGI will look for a cookie with a name of setname. In the above example, CUSTCGI will look for a cookie named PERSONAL.
3. 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

4. A ".CC" data file, containing client specific information, is then loaded. The name of this file is constructed using the USERINFO_DIR parameter that you must set in the CUSTCGI.CMD and MKCUSTCG.CMD source code.
   For example:
   If USERINFO_DIR=D:\GOSERVE\USERINFO, and
   SETNAME=PERSONAL, and
   a PERSONAL=JOEFILE1 cookie exist.
   Then D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CC will be loaded.
   However, if there is no PERSONAL cookie, or
   D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CC does not exist
   then D:\GOSERVE\USERINFO\PERSONAL\DEFAULT.CC will be loaded.
   Furthermore, if setname was not specified, then
   then D:\GOSERVE\USERINFO\DEFAULT.CC will be loaded.
   Note that a .CC extension is always assumed.
5. If one of the files derived in step 4 can be found, CUSTCGI will extract the varname variable from this .CC data file. If no file can be found, an error comment is returned.
6. The CUSTCGI "keyphrase" is replaced by this value. For example, if D:\GOSERVE\USERINFO\PERSONAL\JOEFILE1.CC contains a:
         CAR=<B>Honda Accord</B>
varname entry, then Honda Accord will be inserted into the document.

MKCUSTCG recognizes nine parameters:

1. SETNAME (required)
2. IDENTIFIER optional, usually not used)
3. PASSWORD (optional)
4. NODELETE (optional)
5. VAR.varname (required)
6. RESPONSE (recommended)
7. EXPIRE (recommended)
8. PATH (optional)
9. INIT Superusers only

Summarizing MKCUSTCG 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 (as defined by IP address), 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 USERINFO_DIR directory (recollect that .CC 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 CUSTCGI (and MKCUSTCG) 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 PERSONAL1 for documents under www2.foo.net).

  
  

  IDENTIFIER

  IDENTIFIER identifies who the client is.

  • Technically speaking, IDENTIFIER should identify a not necessarily existing ".CC" 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, MKCUSTCG will generate a random name. This is often sufficient, since MKCUSTCG 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 ".CC" 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 MKCUSTCG 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;!-- #echo time="DATE_LOCAL" --&gt;"  Selected > Display the time?
     <INPUT TYPE="radio" NAME="VAR.SHOWTIME"
                VALUE="&lt;!-- #echo time="DOCUMENT_URI" --&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 &lt; 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; where superusers are defined by IP address (using the SUPERUSER parameter in CUSTCGI.CMD.
  • The following varnames are reserved: !NODELETE !EXPIRE !PATH !PASSWORD !CREATION !WHO !IDENTIFER

  
  

  RESPONSE

  A response file, typically an HTML document. After submission, MKCUSTCG will read this document in and send it back verbatim. This means that server side includes will NOT be attempted on this document -- the document is sent back "as is" (if there were an agreed CGI-BIN redirect syntax, we could do better....)

  Thus, RESPONSE should be a fully qualified file name. If not, MKCUSTCG will assume the file is relative to your DATA_DIR (DATA_DIR is a parameter contained in MKCUSTCG.CMD).

  • 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" > (where CUSTOM is a subdirectory of your DATA_DIR).
  • If RESPONSE is not specified, a generic response is returned.
  • If you set RESPONSE equal to a URL (i.e.; http://foo.bar.net/custom/resp_cgj.htm), then a generic response, with a link to this response, will be used.

  
  

  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 MKCUSTCG will create DEFAULT.CC in the SETNAME directory, and insert the specified VAR.varname variables.

  • If DEFAULT.CC exists in SETNAME, the selected variables will be added (that is, this DEFAULT.CC 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. To identify superusers, you (the webmaster) must set the SUPERUSER parameter in MKCUSTCG.CMD

  ---

  Configurator

  This configurator will initialize a DEFAULT.CC 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 ...

  ---