Test of ByBROWSR.RXX

15 Apr 1998: ByBROWSR.RXX : Using Browser Specific Documents. Abstract: ByBROWSR.RXX is an "INTERPRETable" SRE-http addon that simplifies the deliver of "browser specific" documents to your WWW clients. Contents: 1.0 Introduction 2.0 Using ByBROWSR.RXX 2.1 A Simple Example 2.2 More Options 3.0 Configuring ByBROWSR.RXX 3.1 User-Configurable Parameters in ByBROWSR.RXX 4.0 A simple, working example -------- ---- --------- 1.0) Introduction ByBROWSR.RXX is an "INTERPRETable" SRE-http addon that simplifies the delivery of "browser specific" documents to your WWW clients. Although it requires a bit of initial setup, once you have ByBROWSR.RXX customized to your needs, it's quite easy to use. Of course, you still are responsible for content-creation -- but with ByBROWSR.RXX, that's about all you need to be concerned with. Hint: For many purposes, the use of content-negotiation (either server side or client side) will be easier (and more efficient) then using this BYBROWSR addon. Please see NEGOTIAT.DOC for the details -------- ---- --------- 2.0) Using ByBROWSR.RXX To use ByBROWSR.RXX, you just need to include "SSI keyphrases" in a "base document". When this "base document is requested by a client, SRE-http will call (actually, SRE-http will read and "interpret") ByBROWSR.RXX. ByBROWSR.RXX will lookup the client's browser (using the "user-agent" request header), and then try and find a "browser specific" version of the "base document". Browser specific versions are files that have the same name as the base document, but have extensions that indicate which browser the file is meant for. You can, and should, make several such documents for the various types of browsers likely to visit your site; and you should also make a default document for use when some unusual (or new) browser comes a calling. The trick is to know what extensions to use. This is explained in greater detail in the Configuring ByBROWSR.RXX section. But first, how about a simple example? -------- ---- --------- 2.1) A Simple Example Let's assume the following URL on your home page: More info? Let's also assume that /MOREINFO.HTML points to D:\WWW\MOREINFO.HTML. D:\WWW\MOREINFO.HTML can consist of just the following line. (that's right: no , no -- just one line of text.) Now the hard part -- creation of several "browser-specific files". Each of these files will be named D:\WWW\MOREINFO.an_ext; where an_ext is a a special "browser-specfic" extension. These an_ext animals are setup in ByBROWSR.RXX (again, we'll get to that in the configuration section). For now, let's assume you care about 4 major "classes" of browsers. The an_ext for these should be.... NetScape 2.x : an_ext = NETSCAPE2 NetScape 3.x : an_ext = NETSCAPE3 MSIE 3.x : an_ext = MSIE3 all others : an_ext= DEF (for sake of simplicity, let's ignore NetScape 4, MSIE 4 ,etc.) Thus, you should also create the following files, each of which will contain "browser specific" HTML code. For this simple example, each of these "browser specific" files should be a fully contained HTML document (i.e; one that starts with or , and ends with ). D:\WWW\MOREINFO.NETSCAPE2 (used with Netscape 2.x browsers), D:\WWW\MOREINFO.NETSCAPE3 (used with Netscape 3.x browsers), D:\WWW\MOREINFO.MSIE3 (used with MSIE 3.x browsers), D:\WWW\MOREINFO.DEF (used with all otherbrowsers), That's it! When a client asks for /MOREINFO.HTM; one of the above 4 files will be returned. A FAT Note: If you are using a FAT system:, some extra configuration is needed in order to use ByBROWSR.RXX, and your "extensions" can only be three characters long, but otherwise there is no difference. -------- ---- --------- 2.2) More options: ByBROWSR.RXX is actually a "browser specfic #INCLUDE". Specifically, SRE-http will convert a "SSI keyphrase" of into where filename is the name (minus extension) of the requested document (i.e.; MOREINFO), and an_ext is determined from the User-Agent request header and the "file matching rules" specified in ByBROWSR.RXX. Thus, the "browser specfic files" need NOT be an entire HTML document -- they can just be a component of an otherwise "all-browser" document. That is: you can use in pretty much the same way you use a statement. For example, MOREINFO.HTM could be a regular HTML document, with used to specify a that uses browser specific

extensions. The astute reader might ask: what if I want to have several such "browser-specific components"? And the answer is ---- Yes, it's easy to do. All you need to do is place the "selector" for this "base document" after the ByBROWSR.RXX, as in: For example: Suppose you have a BBars directory that contain sets browser-specific button-bars (such as NAVIGATE.NETSCAPE2, NAVIGATE.DEF, and NAVIGATE.MSIE4) To include the appropriate button bar, use the following: Notes: * the "selector" (i.e.; BBARS/NAVIGAT) will be interpreted using the regular SRE-http rules -- it should either be under the GoServe default data directory or should point to a virtual directory (either of which may be host-specific) * you needn't bother putting an extension after NAVIGAT -- it will be stripped off. -------- ---- --------- 3.0) Configuration The heart of ByBROWSR.RXX is a set of "file-matching" rules. These rules are used to match an "user-agent" request header to a "file extension". Note: ByBROWSR.RXX is installed into your SRE-http "addons" directory (perhaps D:\GOSERVE\ADDON). There are three levels of rules: 1) Primary Rules. Each primary rule consists of a candidate user-agent string, and the extension it maps to. ByBROWSR.RXX will find the primary rule that "best" matches the user-agent. 2) Secondary Rules. If the primary rule fails (either because there is no match, or a file with the matching extension does not exist), a set of secondary rules are examined. These are similar to primary rules; with the notion being you will use more "generic" names. In addition, ALL matching secondary rules are attempted starting with the "best" match and continuing until a matching file name exists (or until there are no more matching secondary rules). 3) Default rule. If the primary and secondary rules do not yield a match, a default extension is used. As shipped, the default extension is DEF -- but you can change that. This "best" matching is based on the following algorithim: 1) All spaces are removed from the user-agent, and from each of the primary (and secondary) rules. 2) A case-insensitive "wild card" match is attempted -- with * in the "rules" treated as a wildcard characters. You can have multiple *s in each rule (* in the user-agent are treated as normal characters). 3) If there are multiple "wild card" matches, the "best" match is used (for seconday rules, the "best" matches are "used first"). Best match is a function of how many characters in the "user-agent" also appear in the rule -- the more "early occurences", the better the match. For example: if the user-agent=MOZILLA/2.0(emulator), and two candidate rules are: i) Mozilla*2 ii) Moz*2.0*( then both match, but i is better (since "Mozilla" is longer then "Moz". Note that * can "wildcard match" a 0-length string (that's why ii is a valid match). ByBROWSR.RXX is shipped with about 50 primary rules that map unique "user-agents" to unique extensions, and several secondary rules that deal with the most popular "families" of browsers. The following lists several of these "shipped with" primary rules, and the extensions they map to. Extension Primary Matching Rule ------- ---------------------------------------- WEBEX11 IBMWebExplorerDLL/v1.1* WEBEX12 IBMWebExplorerDLL/v1.2* MSIE3 Mozilla/2.0*(compatible*MSIE3.* MSIE2 Mozilla/*compatible*MSIE2.* MSIE4 MicrosoftInternetExplorer/4.* NETSCAPE4 Mozilla/4.* NETSCAPE3 Mozilla/3.* NETSCAPE2 Mozilla/2.* NETSCAPE1 Mozilla/1.* MOSAIC27 NCSA_Mosaic/2.7* Reminder: when the user-agent is compared to a matching rule -- all spaces are removed, case is ignored, and * is a wildcard. Furthermore, the "best" match is used. Hence, a user-agent of Mozilla/2.0*(compatible*MSIE 3.*Windows 3.1*)* would yield MSIE3. Since it is quite likely that you will NOT have all these zillions of browser specific files; in most cases a matching primary rule WILL be found, but the corresponding file will NOT exist. In such cases, the secondary rules are examined. ByBROWSR.RXX is shipeed with the following secondary rules: Extension Secondary Matching Rule ------- ---------------------------------------- NETSCAPE2 Mozilla/2.* NETSCAPE2 Mozilla/3.* NETSCAPE2 Mozilla/4.* MOSAIC MOSAIC NET Mozilla* Example (assuming the "base document" name is xxxx): If the user-agent matches the Mozilla/3.* "primary rule", but a xxxx.NETSCAPE3 file does not exist: i) A xxxx.NETSCAPE2 file will be tried. If this fails: ii) A xxxx.NET file will be tried And if this also fails, iii) A xxxx.DEF file will be used If you want to modify these rules (and it's probably a wise idea to at least consider modifying the secondary rules), you'll need to edit the following varibles in ByBROWSR.RXX: BROWSER.! -- Primary Rules BROWSER_2.! -- Secondary rules. DEFAULT -- Default ByBROWSR.RXX contains a description of the syntax of these variables. Or, you can read the "User-configurable Variables" section that coming upt next. -------- ---- --------- 3.1) User-Configurable Variables in ByBROWSR.RXX This section contains information on the structure of the various "user-configurable" variables. DEFAULT -- The default extension. DEFAULT should equal the extension to use if there is no match, or if matching rules point to a non-existent file. Example: DEFAULT='DEF' BROWSERS.! -- Primary Rules A list of User Agents and associated extensions. The BROWSER.! variables should have the following syntax: BROWSER.!an_ext='u_agent' where an_ext is the extension to use u_agent is compared against user-agent request headers Example: BROWSER.!NETSCAPE3='Mozilla/3.*' Notes: * Be sure to include the .! before the an_extension (it's a REXX "stem variable" subtlety). PLEASE NOTE THAT THE ! IS NOT USED IN THE EXTENSION. * Be sure to surround the u_agent with ' quotes * Spaces in the user_agent are ignored, case is ignored, and * are treated as wild-card characters. * The "best" match (of the u_agent field against a requesting browser's user-agent request header) is used * If you are using a FAT (3 character extension) system, you'll need to modify the an_ext "tails" of all the BROWSER.! and BROWSER_2.! rules. * To specify U_agents mapping to the same an_ext, use syntax e Examples: BROWSER.!WEBTV='Mozilla/1.*WebTV/1.*compatible*MSIE2.*' BROWSER.!EINETMACWEB='MacWeb/1.00*libwww/2*' BROWSER.!WEBEX12='IBMWebExplorerDLL/v1.2*' BROWSER.!WEBEX11='IBMWebExplorerDLL/v1.1*' BROWSER.!MCI='internetMCI/1.0(Windows)*' BROWSER.!MSIE3='Mozilla/2.0*(compatible*MSIE3.*' BROWSER.!MSIE4='MicrosoftInternetExplorer/4.*' BROWSER.!NETSCAPE4='Mozilla/4.*' BROWSER.!NETSCAPE3='Mozilla/3.*' BROWSER_2.! -- Secondary Rules. The BROWSER_2.! variables are used when a matching BROWSER.! "primary rule" can not be found. It uses the same syntax as BROWSER.!. Notes: * We advice using very generic (short, with early use of *) u_agents! * You can use u_agents specified in BROWSER.! rules. Examples: BROWSER_2.!MOSAIC='*MOSAIC' BROWSER_2.!NETSCAPE2.1='Mozilla/2.*' BROWSER_2.!NETSCAPE2.2='Mozilla/3.*' BROWSER_2.!NETSCAPE2.3='Mozilla/4.*' Note the use of NETSCAPE.1, NETSCAPE.2 and NETSCAPE.3 -- all three u_agents will map to the NETSCAPE2 an_ext extension. -------- ---- --------- 4.0) A simple, working example For a simple working example of how ByBROWSR.RXX works, cut out the following code and create the appropriate (mostly 1 line) files. Then, hit TESTBRWS.HTM with you favorite browser(s); and see what happens. Notes: * Since you are unlikely to have browser that sends a "FOOBAR" user-agent, you can use the SRE-http DOGET.CMD utility to fake it. * For status info, set VERBOSE=4 and run PMPRINTF. ------------------- Save as TESTBRWS.HTM (in your GoServe Data Directory) Test of ByBROWSR.RXX This is a test of browser specific document includes using the ByBROWSR.RXX utility. You might want to set verbose=4, and watch what PMPRINTF tells you.

Test1: Including the generic (own file name) browser-specific document:

Test2: Including a specified browser specfic document (that may be in another web directory):  (note that the extension is not used)

End of test ------------------- Save as TESTBRWS.DEF (in your GoServe Data Directory) This is the default include ------------------- Save as TESTBRWS.FOO (in your GoServe Data Directory) This is the foo include ------------------- Save as TESTBRWS.NET (in your GoServe Data Directory) This is the netscape specific include. ------------------- Save as SAMPLES/TEST1INC.DEF (relative to your GoServe Data Directory) This is the default browser specfic include of a non-generic file (TEST1INC) ------------------- Save as SAMPLES/TEST1INC.NET (relative to your GoServe Data Directory) This is the netscape specific include. ------------------- Save as SAMPLES/TEST1INC.FOO (relative to your GoServe Data Directory) This is the foo include --------------------- End of files to create. .End of document