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:
<!-- $bybrowsr.rxx -->
Test2: Including a specified browser specfic document (that
may be in another web directory):
<!-- $bybrowsr.rxx /samples/testinc --> (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