home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / BYCLIENT.DOC < prev    next >
Text File  |  2001-03-27  |  14KB  |  336 lines
  1. 15 Apr 1998: ByClient.RXX :  Using Client Specific Documents.
  2.  
  3. Abstract:
  4.   ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  5.   deliver of "client specific" documents to your WWW clients.
  6.  
  7. Contents:
  8.  
  9. 1.0 Introduction
  10. 2.0 Using ByCLIENT.RXX
  11. 2.1 A Simple Example
  12. 2.2 Syntax of a .USR file
  13. 2.3 Specifying IDs
  14. 3.0 Miscellaneous Notes
  15. 4.0 A sample
  16.                         --------    ----   ---------
  17.  
  18. 1.0) Introduction
  19.  
  20. ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  21. delivery of "client specific" documents to your WWW clients.  Using
  22. ByCLIENT.RXX requires creation of special instructions files (.USR files)
  23. that identify which files should be delivered to which clients. After
  24. identifying the client, ByCLIENT will use this .USR file to ascertain
  25. a file to be INCLUDEd in the document.
  26.  
  27. Identification of clients is based on a number of possible pieces of
  28. information, including: special ByCLIENT cookies, the SRE-http "client
  29. privileges", or the IP namd and address.  The .USR file can freely mix
  30. these different "client identification" mechanisms.
  31.  
  32.  
  33. Hint:
  34.     For many purposes, the use of content-negotiation (either server side
  35.     or client side) will be easier (and more efficient) then using this
  36.     BYCLIENT addon. Please see NEGOTIAT.DOC for the details
  37.  
  38.  
  39.                         --------    ----   ---------
  40.  
  41. 2.0) Using ByCLIENT.RXX
  42.  
  43. To use ByCLIENT.RXX, you just need to include
  44.  
  45.     <!-- INTERPRET FILE ByCLIENT.RXX -->
  46.  
  47. "SSI keyphrases" in a "requesting document". When this "requesting document" 
  48. is requested by a client,  SRE-http will call (actually, SRE-http will 
  49. read and "interpret") ByCLIENT.RXX. ByCLIENT.RXX will find a .USR
  50. file (with the same name as the "requesting document"), match the
  51. "client" with an "rule" in this .USR file, and INCLUDE the "client
  52. specific document" this rule points to.
  53.  
  54. Inclusion of these client specific documents is accomplished via a
  55. <!-- #INCLUDE file=docname >  or <!-- #INCLUDE virtual=docname > 
  56. server-side includes (where docname is the "client specific document"
  57. specified in the .USR file).  Typically, these files will contain information
  58. relevant to a subset of clients (say, "intranet" versus "extranet" clients).
  59.  
  60. In addition to the (unavoidable) task of writing these client specific 
  61. documents, use of ByCLIENT requires creation of .USR files. These .USR
  62. files consist of a series of matching "rules". Each rule contains two sets
  63. of information: the file to use, and the clients for whom this file should
  64. be used.  
  65.    * File to use: The file to use should be specified relative to the
  66.      web space of your server, or relative to the location of the
  67.      "requesting document". 
  68.     
  69.    * Client identification: Clients may be identified via cookies,
  70.      client privileges, or IP address.   
  71.        Cookies: If a BYCLIENT cookie was passed to the server, its value
  72.        will be used as a client-id. 
  73.        Client privileges: Each of the various "client privileges" will
  74.        be used to identify 
  75.        IP address: The IP address (numeric or name) can be used to 
  76.        identify a client -- with wildcards used to specify entire domains.
  77.  
  78.     Note that a client may be identified several times; say, through
  79.     a BYCLIENT cookie, through several client privileges, and through
  80.     several wild-card'ed domains.  In such cases, the cookie "identification"
  81.     is tried first, followed by the client privileges, followed by
  82.     the IP address.  
  83.  
  84. As this point, a simple example should help....
  85.  
  86.                         --------    ----   ---------
  87.  
  88. 2.1) A Simple Example
  89.  
  90. Let's assume the following URL on your home page:
  91.     <A href="/NEWS.HTM">Today's news? </a>
  92. Let's also assume that /NEWS.HTM points to D:\WWW\NEWS.HTM,
  93. and that D:\WWW\NEWS.HTM contains the following:
  94.  
  95.    <h2>Local news</h2>
  96.       <!-- INTERPRET FILE ByCLIENT.RXX -->
  97.    <h2> National news </h2>
  98.  
  99. Thus, the "local news" will be "client specific".
  100.  
  101. SRE-http will invoke ByCLIENT.RXX, and ByCLIENT.RXX will look for
  102. a file named D:\WWW\NEWS.USR. NEWS.USR should contain "rules" used
  103. to determine what file this client should get. For example:
  104.  
  105. ; ByCLIENT .USR file for /NEWS.HTM
  106. COOKIE: /stories/news1.inc     class1 class2
  107. PRIVILEGE: /stories/news1.inc  priv1 priv2 priv3
  108. PRIVILEGE: /stories/newsA.ink  privas privb
  109. IP: /stories/news1.inc   *.mysite.net *.newsdog.com *.131.51
  110. IP: /stories/newsa.ink   *.hersite.net *.newsdog.com *.31.61
  111. COOKIE: /stories/newsA.ink     classA classB
  112.  
  113. These rules select between two files: D:\WWW\STORIES\NEWS1.INC and
  114. D:\WWW\STORIES\NEWSA.INK.  Each rule consists of three components:
  115. the "type" of rule, the file, and a space delimited list of client
  116. ids.  Note that lines beginning with a ; are comments.
  117.  
  118. The actual file "INCLUDED" will depend on the values of the ByCLIENT
  119. cookie, the client privileges, and the client's IP address.  For example:
  120.  
  121.   *  If BYCLIENT=CLASS2 and the client's IP name is JOHN.MYSITE.NET
  122.         then D:\WWW\STORIES\NEWS1.INC will be used.
  123.  
  124.   *  If BYCLIENT=CLASS6 and the client has a PRIVB privilege; 
  125.         then D:\WWW\STORIES\NEWSA.INK will be used.
  126.  
  127.    * If there is no BYCLIENT cookie, and the client's IP name 
  128.      is JOHN.NEWSDOG.COM;
  129.         then D:\WWW\STORIES\NEWS1.INC will be used.
  130.  
  131. The key to using ByCLIENT is to understand how the .USR file identifies
  132. clients. The next section discusses the syntax of these .USR files.
  133.  
  134.                         --------    ----   ---------
  135.  
  136. 2.2) Syntax of a .USR file
  137.  
  138.  
  139. The .USR file is used to match a client to a filename. This filename
  140. (which is specified using a "selector" style of name) will then be
  141. #INCLUDEd in the requesting document.
  142.  
  143. When an <!-- INTERPRET ByCLIENT.RXX --> keyphrase is encountered,
  144. ByCLIENT will look in the "requesting documents" directory 
  145. for a file with a .USR extension. If no such file can be found, nothing
  146. is done (i.e; the <!--INTERPRET  ByCLIENT.RXX --> keyphrase is ignored).
  147.  
  148. NOTE:  You can specify an explicit .USR file to use. For example:
  149.              <!-- INTERPRET ByCLIENT.RXX  buttons/helplink.usr --> 
  150.       (see this section's notes for further details).
  151.  
  152. Note:
  153.   
  154.   *  To specify an explicit .USR file, place its name after the 
  155.      ByCLIENT.RXX.  For example:
  156.              <!-- INTERPRET ByCLIENT.RXX /order/form1.usr --> 
  157.      This can be  quite useful if you have a commonly used file
  158.      (say, a button bar), or if you want to include several files 
  159.      (say, several different tables in an otherwise generic document).
  160.  
  161.      Note that the location of this "explicit" .USR file is
  162.      either relative to the "requested document's directory" (if the
  163.      filename does NOT begin with a /). When this filename starts with a
  164.      /, it is interpreted using the standard SRE-http selector rules 
  165.      (i.e.; using the data directory and virtual directories).
  166.       
  167. The .USR file is an ascii (text) file.  Each line of the .USR file 
  168. is a "rule" that is used to match clients to INCLUDEable files.
  169.  
  170. The syntax of these rules is:
  171.    type  filename   id1 ... idn
  172. where
  173.   type:  The type of "client ID". Three types are recognized:
  174.          * COOKIE: The value of the "ByCLIENT" cookie (if one exists).
  175.          * PRIVILEGE: The values of the SRE-http client privileges
  176.          * IP: IP addresses (either numeric or name)
  177.  
  178.   filename: The "selector" style filename of the file to be #INCLUDEd.
  179.             This file is assumed to be either
  180.                a) relative to the requesting document's directory, or 
  181.                b) relative to the root of the web tree, or in a virtual
  182.                   directory
  183.            In particular, if the filename does NOT start with a /, then
  184.            a is used. If the filename DOES start with a /, then b is used.
  185.            In other words:
  186.              foo/bar.1 is equivalent to <!-- #include file="foo/bar.1" -->
  187.            and
  188.              /foo/bar.1 is equivalent to <!-- #include virtual="foo/bar.1" -->
  189.  
  190.   id1 ..idn : A space delimited list of "client identifiers". The values
  191.               will depend on the type.  Thus, if type=IP, then these "ids"
  192.               should be IP addresses (either name or number). Or, if
  193.               type=COOKIE, then these "ids" should be possible values
  194.               of a ByCLIENT cookie.
  195.  
  196. In addition to these three rules, lines starting with semi-colons
  197. are treated as comments, and empty lines are ignored.
  198.  
  199. 2.3) Specifying IDs
  200.  
  201. When looking for a rule with a matching ID, ByCLIENT does the following:
  202.  
  203. 1) Checks for a ByCLIENT cookie (note that the case of ByCLIENT is ignored).
  204.    All COOKIE "rules" are then checked.  The first rule that contains
  205.    an id that matches ByCLIENT will be used, provided that the 
  206.    filename (contained in the rule) exists. 
  207.    If it does not exist, the next COOKIE rule is used.
  208.  
  209. 2) If no matching COOKIE rule can be found, the PRIVILEGE rules are used.
  210.    Since there may be many client privileges, each id is compared against
  211.    all the client privileges -- if a match is found, then the rule
  212.    is used. As with COOKIE rules, if the filename does not exist, the
  213.    next PRIVILEGE rule is used.
  214.  
  215. 3) If no matching PRIVILEGE rule can be found, the IP rules will be checked.
  216.    IP ids can either by numeric (i.e.; 121.55.12.5) or name (i.e.; 
  217.    JOE.COWS.ORG).  The IP ids can also contain * wildcards.
  218.  
  219. 4) If no matching PRIVILEGE rule can be found, 
  220.    the <!-- INTERPRET ByCLIENT.RXX -->  SSI keyphrase is ignored.
  221.  
  222.  
  223. 3.0) Misellaneous Notes
  224.  
  225.   *  Please be aware that within a "type" of rules, rules nearer the
  226.      top of the file are used in precedence to rules that are lower
  227.      in the file. Conversely, COOKIE rules are always used before
  228.      PRIVILEGE (and IP) rules, regardless of where they appear.
  229.  
  230.   *  There are a number of ways of specifying "cookies".  The easiest
  231.      way is to use a META element in the <HEAD> section of an HTML document
  232.      that is examined before the "requesting document" is loaded.
  233.      For example, you might include:
  234.            <meta http-equiv="Set-Cookie:" content="ByCLIENT=USER_REG">
  235.      on a "registration" page that contains a link to the "requesting
  236.      document" (that is, a link to the document containing the
  237.      <!-- INTERPRET FILE ByCLIENT.RXX -->)
  238.  
  239.   *  Wildcard characters (the *, several of which may appear) used in IP "ids"
  240.      are used in a standard string-matching fashion. 
  241.      Thus, an id of *.121.55 would match 5.21.121.55 and would match 62.121.55.
  242.  
  243.   *  Wildcard characters can NOT be used with PRIVILEGE rules, but can
  244.      be used with COOKIE rules.
  245.  
  246.   *  For a more dynamic form of "client customization", that makes extensive 
  247.      use of cookies, consider the CUSTOMIZ addon. CUSTOMIZ can be on obtained 
  248.      from http://www.srehttp.org/apps/customiz/.
  249.   
  250.   *  Reminder: you can modify client privileges by changing "user"
  251.      entries in the USERS.IN file.  This, however, requires the
  252.      client to login.  Alternatively, the PUBLIC_PRIVS, INHOUSE_PRIVS,
  253.      and INHOUSEIPS. entries allow you to set privileges on a 
  254.      global and on a per-IP-address basis.
  255.  
  256.   *  It's a good idea to specify a "default" rule as the last entry in a 
  257.      .USR file. For example:
  258.          IP  /stories/news0.htm  *
  259.      will cause /stories/news0.htm to be used for ALL IP addresses.
  260.  
  261.                         --------    ----   ---------
  262. 4) Demo
  263.  
  264. The following simple sample can be used to demo ByClient.RXX. 
  265. To use this demo:
  266.  
  267.  a)With your favorite text editor, cut out the code and create 
  268.    the indicated files, 
  269.  b)Request /ByClient.sht
  270.    or, to first set a cookie, 
  271.  c) request /ByClien2.Sht?cookie_value
  272.       (where cookie_value could be COOK1 or COOK2)
  273.     and then request /ByClient.sht
  274.  
  275.  
  276. 1) BYCLIENT.SHT (in your GoServe data directory):
  277.                   ------- cut here ---------------
  278. <!DOCTYPE HTML PUBLIC "-//W3 Organization//DTD W3 HTML 2.0//EN">
  279. <html>
  280. <head>
  281. <title>Test ByCLIENT</title>
  282. </head>
  283. <body>
  284. <h1>Test of ByClient</h1>
  285.  
  286. <!-- This will cause the "client specific" file (BYC.0...BYC.5)
  287.      to be INCLUDEd -->
  288.  
  289. Welcome.<p>
  290. <!-- interpret file $ byclient.rxx  -->
  291.  
  292. </body>
  293. </html>
  294.                  ------- cut here ---------------
  295.  
  296. 2) ByCLIEN2.SHT (in your goserve data directory)
  297.                   ------- cut here ---------------
  298. <html><head>
  299. <title>SEt ByClient Cookie </title>
  300. <meta http-equiv="Set-cookie:" content="ByClient=<!-- option 1-->" >
  301. </head><body>
  302. <h1>Set ByClient Cookie</h1>
  303. <p> Your ByClient cookie has been set to <!-- option 1-->
  304. <hr>
  305. <b>Note:</b> To set client, use a selector of:
  306.             <tt>/byclien2.htm?cookie_value</tt>
  307. </body></html>
  308.                   ------- cut here ---------------
  309.  
  310. 3)ByCLIENT.USR -- same directory as byclient.sht
  311.                   ------- cut here ---------------
  312. ;sample .USR file for ByClient
  313. ip byc.1 127.*.*
  314. cookie byc.2 cook2 owner
  315. cookie byc.3 cook23
  316. priv byc.4   byclientp
  317. priv byc.5   superuser
  318. ip byc.0 *
  319.                   ------- cut here ---------------
  320.  
  321. 4) Create Byc.0, byc.1, to byc.5 in the same directory as 
  322.    byclient.sht.
  323.    For exampe, simple one line files can be used:
  324. BYC.0  :  This is the default message
  325. BYC.1  :  This is the message for loopback clients (on 127.*.*)
  326. BYC.2  :  Message for clients with ByClient cookie of <b>cook2</b> or <b>owner</b>
  327. BYC.3  :  Message for clients with ByClient cookie of <b>cook23</b> 
  328. BYC.4  :  Message for clients with a <b>byclientp</b> privilege
  329. BYC.5  :  Message for <b>SUPERUSER</b>s
  330.  
  331. Reminder: the above entries represent 6 seperate files!
  332.  
  333.                         --------    ----   ---------
  334.  
  335. .End of document.
  336.