Version 2.1


NetCloak

User's Guide


"Dynamic Web Sites...

...No Programming Required"


Commands: Unconditional
<HIDE>
<SHOW>
Commands: Client Domain
<HIDE_DOMAIN domain1 domain2 ...>
<SHOW_DOMAIN domain1 domain2 ...>
<INSERT_DOMAIN>
Commands: Time
<HIDE_TIME time1 time2 ...>
<SHOW_TIME time1 time2 ...>
<INSERT_TIME offset format>
Commands: Day of Week
<HIDE_DAY day1 day2 ...>
<SHOW_DAY day1 day2 ...>
<INSERT_DAY offset>
Commands: Date
<HIDE_DATE low high>
<SHOW_DATE low high>
<INSERT_DATE format>
Commands: Access Count
<INSERT_COUNT counter>
<HIDE_COUNT lowvalue highvalue counter>
<SHOW_COUNT lowvalue highvalue counter>
Commands: Time Countdown
<INSERT_COUNTDOWN_WDHM date@time "label"...>
Commands: Client Type
<HIDE_CLIENT client1 client2 ...>
<SHOW_CLIENT client1 client2 ...>
<INSERT_CLIENT>
Commands: User Name
<HIDE_USERNAME user1 user2 ...>
<SHOW_USERNAME user1 user2 ...>
<INSERT_USERNAME>
Commands: User Password
<HIDE_PASSWORD password1 password2 ...>
<SHOW_PASSWORD password1 password2...>
<INSERT_PASSWORD>
<REQUEST_PASSWORD realm>
Commands: Referring Document
<HIDE_REFERRER referrer1 referrer2 ...>
<SHOW_REFERRER referrer1 referrer2...>
<INSERT_REFERRER>
Commands: Random Number
<HIDE_RANDOM percent range>
<SHOW_RANDOM percent range>
<INSERT_RANDOM range>
Commands: Random Extensions
<HIDE_SAMERAND percent>
<SHOW_SAMERAND percent>
Commands: Redirecting
<REDIRECT "URL">
Commands: File Information
<INSERT_MODIFIED filename>
<INSERT_FILESIZE filename>
Commands: URL
<HIDE_THISURL url1 url2 ...>
<SHOW_THISURL url1 url2 ...>
<INSERT_THISURL>
Commands: User-Entered Variables
User-Entered Variables
<HIDE_VARIABLE variable "text">
<SHOW_VARIABLE variable "text">
<INSERT_VARIABLE variable>
Commands: Toggling Show/Hide Mode
<FLIPMODE>
Commands: Executing CGIs
<EXEC_CGI "application name" "direct" "beginfilter" "end filter">
Commands: HTTP Header
<HIDE_HEADER "text">
<SHOW_HEADER "text">
<INSERT_HEADER>

Commands: Referring Document

<HIDE_REFERRER referrer1 referrer2 ...>

This command hides the HTML text from users based on the last HTML document they accessed (the document that "referred" the user to this one). This allows you to tailor your document depending on where the user has been.

Specifying "referrers" is less restrictive than some of the other NetCloak commands, because the referrer is returned by the web browser and is subject to vary slightly. Specifically, the referrers you specify are not case sensitive, and they can appear anywhere in the URL of the last document the user was on.

Some browsers may not support the "Referrer" field, and if the browser doesn't send it, NetCloak won't be able to use it. You can check for the existence of the field by using the command alone, with no "referrers" specified. In other words, <HIDE_REFERRER> will hide text whenever a referrer is known. See below for an example.

<SHOW_REFERRER referrer1 referrer2...>

HTML text that follows this command will be visible to users when the most recent document they visited in their web browser matches "referrer".

For example, if your site was selected as the "Cool Site of the Day", you might add this to your Home Page:

<HIDE>
<SHOW_REFERRER Cool>
Welcome, Cool Site of the Day users!
<SHOW>

This would show the text only to people who had just come from a page with the word "Cool" in the URL.

Use <SHOW_REFERRER>, with no referrers specified, to make sure the browser supports the "referrer" field.

<HIDE><SHOW_REFERRER>You just came from <INSERT_REFERRER>!
<SHOW><HIDE_REFERRER>
Sorry, your browser does not support referrers.
<SHOW>

<INSERT_REFERRER>

This command will insert the URL of the last page visited into your document at the specified point.

Here is an example:

You just came from: <INSERT_REFERRER>.
If you want, you can:
<A HREF="<INSERT_REFERRER>">Go Back!</A>

Commands: Random Number

<HIDE_RANDOM percent range>

This command hides the HTML text from users randomly. The command causes text to be hidden in the defined percentage of page accesses. The show version of this variation is more common and easier to understand, so see below for more details.

<SHOW_RANDOM percent range>

This command shows the HTML text to users randomly. The command causes text to be shown in the defined percentage of page accesses. "Percent" is a numeric value from 1 to 100, and represents the likelihood of the command actually showing the HTML text which follows the command.

For example, to display a list where each item in the list appears randomly:

<HIDE><SHOW_RANDOM 30>
This line seen 30% of the time.
<HIDE><SHOW_RANDOM 20>
This line seen 20% of the time.
<HIDE><SHOW_RANDOM 80>
This line seen 80% of the time.
<HIDE><SHOW_RANDOM 10>
This line seen 10% of the time.
<HIDE><SHOW_RANDOM 90>
This line seen 90% of the time.

In order to ensure that one and only one line in the group is shown on a page, see the "Random Extensions" section below.

The optional parameter "range" allows you to specify a smaller or larger range of possible random values. In other words, when the range parameter is left out, the random "percentage" will be a value from 1 to 100. By specifying a range of, say 30, the value generated will be between 1 and 30. This allows for a finer level of control over percentages (down to 1/100th of a percent). It also allows you to select from more than 100 possible options. The maximum range for randomly generated values is 1 to 10,000.

<INSERT_RANDOM range>

<INSERT_RANDOM> allows you to display a random number in your document. By default (without "range" specified), the value will be between 1 and 100. Here are a few examples:

Random #(1-100): <INSERT_RANDOM>
Random #(1-5): <INSERT_RANDOM 5>
Random #(1-500): <INSERT_RANDOM 500>

Commands: Random Extensions

<HIDE_SAMERAND percent>

This command hides the HTML text from users randomly, based on a previously generated random value. The command causes text to be hidden in the defined percentage of page accesses. The show version of this variation is more common and easier to understand, so see below for more details.

<SHOW_SAMERAND percent>

This command shows the HTML text to users randomly, based on a previously generated random value. The command causes text to be shown in the defined percentage of page accesses.

"Percent" is a numeric value from 1 to 100 (by default, see the "Random" section above for information on changing the range), and represents the likelihood of the command actually showing the HTML text which follows the command.

<SHOW_SAMERAND> should only be used after a <SHOW_RANDOM>, <HIDE_RANDOM> or <INSERT_RANDOM> command, since these are the commands that generate the random value used by <SHOW_SAMERAND>.

A generated random value will trigger only a single "SAMERAND" command. For each show command that is not triggered, the chances of later "SAMERAND" commands triggering increases so that eventually one of the commands will trigger (assuming the percentages in the random commands totals 100%). If the percentages total less than 100%, there will be a chance that none of the items will be shown.

For example, to show exactly one of 4 possible lines with equal probability:

<HIDE><SHOW_RANDOM 25>
This is line 1.
<HIDE><SHOW_SAMERAND 25>
This is line 2.
<HIDE><SHOW_SAMERAND 25>
This is line 3.
<HIDE><SHOW_SAMERAND 25>
This is line 4.
<SHOW>

In this case, a random value is generated, between 1 and 100. If the value is between 1 and 25, the first line will be displayed. If the random value is between 26 and 50, the second line will be displayed. The third and fourth lines will be handled similarly. If you want to display the random value as well, use:

The random # is: <INSERT_RANDOM>
<P>
<HIDE><SHOW_SAMERAND 25>
This is line 1.
<HIDE><SHOW_SAMERAND 25>
This is line 2.
<HIDE><SHOW_SAMERAND 25>
This is line 3.
<HIDE><SHOW_SAMERAND 25>
This is line 4.
<SHOW>

Here is another example. In this case, a graphic will be randomly selected:

<HIDE><SHOW_RANDOM 2>
<IMG SRC=/Images/VeryRare.GIF>
<HIDE><SHOW_SAMERAND 5>
<IMG SRC=/Images/Rare.GIF>
<HIDE><SHOW_SAMERAND 15>
<IMG SRC=/Images/Occasional.GIF>
<HIDE><SHOW_SAMERAND 30>
<IMG SRC=/Images/Common.GIF>
<HIDE><SHOW_SAMERAND 48>
<IMG SRC=/Images/Frequent.GIF>
<SHOW>

Commands: Redirecting

<REDIRECT "URL">

The <REDIRECT> command is a little different from most other NetCloak commands. When this command is encountered in your cloaked HTML document, all processing of the page will immediately cease, and a "redirect" header will be sent to the browser. This causes the browser to immediately transfer to the URL specified.

The command will not cause a redirect to occur if text is "hidden" when the command is encountered, so redirects can be performed conditionally based on any <SHOW> and <HIDE> commands. Redirecting can be used in the error file to allow bad URLs to be redirected to their correct pages. It can also be used to simplify complex pages which have many long hidden sections. It can also be used to redirect an HTML page to a page that might be in a completely different format, if a browser is sensed that supports non-HTML pages.

Please note that a <REDIRECT> command causes all other contents of the page to be ignored. The redirect will not cause the redirected page to appear within the text of the original page.

Here is an example of using <REDIRECT> to send a special "internal use only" page based on the user's TCP/IP address. In the example, users in the domain "192.1." will be sent to the page "ProtectedPage.html". All other users will receive the public page.

<HIDE>
<SHOW_DOMAIN 192.1.>
<REDIRECT "http://my.server/ProtectedPage.html">
<SHOW>
<HTML>
<TITLE>Public Home Page</TITLE>
<BODY>
Welcome to our public Home Page!
</BODY>
</HTML>

"Smart" error pages are another excellent use of the redirect command. Visit the Maxum FAQ and support pages at "www.maxum.com" for up-to-date examples of building smart error pages.

Commands: File Information

<INSERT_MODIFIED filename>

The <INSERT_MODIFIED> command allows you to easily insert the date that the given file was last modified. If the parameter "filename" is not used, then the command will display the last modified date of the current page being served. For example, many pages may end in:

This file last updated on <INSERT_MODIFIED>.

The command can be particularly useful in macros, where a single macro (perhaps a footer) may be used on many pages. In this case, the <INSERT_MODIFIED> command need only appear in a single macro but will always display the modification date of the page that has been served.

Please note that this command may cause additional disk accesses, which may cause some minor degradation in performance. However, NetCloak maintains a cache of last modified dates for documents in the NetCloak.config file, so for NetCloak aliased pages, there is virtually no performance penalty.

The command also allows you to display the last modified date of any file on your server by specifying the optional filename parameter. Like aliases in the NetCloak.config file, the filename can include a relative or a full pathname.

<INSERT_FILESIZE filename>

This command inserts the size of the specified file as it is stored on disk. If a filename is not specified, the size of the page being served is given. There are 3 variations of the command, including "INSERT_FILESIZE_B", "INSERT_FILESIZE_K", and "INSERT_FILESIZE_M" for displaying the size of the file in either bytes, kilobytes, or megabytes, respectively.

The filename parameter may also be a file path. Like all paths specified in NetCloak, when the path begins with a slash ("/"), the path is relative to the Web server root folder. When a path does not begin with a slash, it is absolute. Here are some examples:

<INSERT_FILESIZE_B MyFile.sit.hqx>
<INSERT_FILESIZE_K /MyFolder/MyFile.sit.hqx>
<INSERT_FILESIZE_M MyHD/MyFolder/MyFile.sit.hqx>

The first example is a file ("MyFile.sit.hqx") that resides in the server root folder and the size is displayed in bytes. The second example gives the size, in kilobytes, of a file in a sub-folder of the Web server root. The last example shows the number of megabytes used by a file on the Macintosh volume "MyHD".

Displaying the size in bytes will always show the exact size of the file, while displaying kilobytes will cause NetCloak to round up to the nearest kilobyte. When displaying the size in megabytes, NetCloak will round up to the nearest tenth of a megabyte.

Commands: URL

<HIDE_THISURL url1 url2 ...>

The parameters for the "ThisURL" commands function similarly to the "Referrer" commands. A string of characters that appears in the <HIDE_THISURL> list will be compared against the URL of the current page. If any of these match the current URL, then the hide command will activate and the HTML "stream" will be turned off.

With the "ThisURL" commands, NetCloak allows you to essentially create "self-aware" pages. By using <SHOW_THISURL> and <HIDE_THISURL>, you can create pages that change when they are moved from one folder (or server) to another. These commands can also be used in your macro file to create macros that vary depending on the page they are used on. In short, they allow you to create more portable, re-usable HTML.

<SHOW_THISURL url1 url2 ...>

This is the "show" version of the "hide" command above.

Here's an example:

<HIDE><SHOW_THISURL TestFolder>
This file is in a folder called 'TestFolder', and this page is still being tested. When the file is moved into its final place on my site, this test message will disappear.
<SHOW>
This page is now in production use...

<INSERT_THISURL>

The <INSERT_THISURL> command, which accepts no parameters, will cause the current page's URL to be inserted into the page. This could be used in hidden fields on HTML forms to tell a forms processing CGI the URL of the entry form. It might also be used to create a "reload page" link, or to give the user additional feedback on how your site is set-up.

Commands: User-Entered Variables

User-Entered Variables

NetCloak allows you to create HTML forms that ask the user to enter information and then use that information in your pages. To do this, NetCloak uses "variables".

Each field of your HTML form will have a name. Once the form is submitted, each field becomes a NetCloak variable with the same name. The variable can then be referenced by name on subsequent pages. You can either show the variables to the user in the text of your HTML document, or use <SHOW> and <HIDE> to have your page change based on what the user entered into the fields of the form.

The first step is to create an input form which uses the POST method for form processing. In the ACTION field of your FORM command, you will need to specify the URL to a document that will be processed by NetCloak. NetCloak will store data entered on the form and then serve the file specified. Here is an example of an HTML form:

<HTML>
<TITLE>Variable Entry Example</TITLE>
<BODY>
<FORM method=POST action="/VarDisplay.html">
Please fill out this simple form...<P>
Name:
<INPUT TYPE="text" NAME="YourName" SIZE="32" MAXLENGTH="32">
<P>
Organization:
<SELECT name="Organization">
<OPTION selected>Commercial
<OPTION>K12 Education
<OPTION>Higher Education
<OPTION>Government
</SELECT>
<P>
Check here <INPUT NAME="MyCheckBox" TYPE=checkbox VALUE="CHECKED">
<INPUT TYPE=submit VALUE="Submit Form">
<INPUT TYPE=reset VALUE="Start Over">
</BODY>
</HTML>

In this example, the action specified is "/VarDisplay.html", which is simply the name of the html file we would like served when the user clicks "submit". Of course, the page will need to be served by NetCloak, so the file name specified in the action must end with an extension that is mapped to NetCloak. The example assumes that the Web server is configured to cloak all ".html" files. For more examples of how to use NetCloak variables, look at the NetCloak FAQ list on our Web site.

Once a form has been processed, the fields on the form become variables that may be used within cloaked documents. The "INSERT", "SHOW", and "HIDE" commands for variables are covered next...

<HIDE_VARIABLE variable "text">

Any HTML text that follows <HIDE_VARIABLE> will be hidden from those users when the specified variable contains the specified text. The specified text parameter must be enclosed in quotation marks since it may contain spaces. An example should make this more clear. Assuming that the input form above has been filled out and submitted by the user, we could use:

<SHOW>
<HIDE_VARIABLE YourName "J">
Your name does not contain a J.
<SHOW>

Here, the variable YourName (what the user entered into the field "YourName" on the input form) is checked to see if it contains a "J". If it does, text will be hidden, and the phrase "Your name does not contain a J" will not be seen. To see if the checkbox was checked, we could use:

<SHOW>
<HIDE_VARIABLE MyCheckBox "CHECKED">
You didn't check the check box!

<SHOW_VARIABLE variable "text">

This command operates exactly like <HIDE_VARIABLE> except that is turns the text stream on instead of turning it off. To continue the example from above, we could also show a message when the checkbox is not checked, by using:

<HIDE>
<SHOW_VARIABLE MyCheckBox "CHECKED">
You checked the check box!
<SHOW>

<INSERT_VARIABLE variable>

This command will place whatever the user entered into the field "variable" into the page. An example, based on the input form above, would be:

Your name is: <INSERT_VARIABLE YourName>

Important Note! It is possible for NetCloak to incorrectly identify users and confuse the variables. For this reason, you should not use variables to show and hide secure information, or for mission critical applications.

In cases where you are certain that each user will have a unique IP address (for example, possibly on your internal LAN) variables will be more reliable. In any case, the page served immediately after the input form is submitted (the one referenced in the "FORM" command of the input form) will always be served using the correct variables.

Commands: Toggling Show/Hide Mode

<FLIPMODE>

"Flipmode", which accepts no parameters, simply changes the current mode from SHOW to HIDE, or vise-versa. It is handy when you want to display one of two possible sections of HTML with IF/THEN/ELSE logic. For example, if you have two HTML snippets, one for table-compliant browsers and one for others, you could:

<HIDE><SHOW_CLIENT !Supports_Tables>
Advanced HTML goes here!
<FLIPMODE>
This is visible only to browsers that don't support tables...
<SHOW>

In this case, FLIPMODE doesn't save much, but it can be very handy when you have created a complex condition and simply want to turn on the faucet "for everyone else".

Commands: Executing CGIs

<EXEC_CGI "application name" "direct" "begin filter" "end filter">

This command allows you to dynamically execute "back-end CGIs", as well as execute multiple CGIs from a single client request. These can be either other commercial CGIs, or CGIs that you write yourself. For a detailed description of how back-end CGIs work, see the section "Using NetCloak With Other CGIs" earlier in this User's Guide.

"EXEC_CGI" accepts up to four parameters, though the second, third and fourth are optional. The "ApplicationName" is simply the name of the CGI application you would like to execute. As with all back-end CGI use, it must be the name (and path, where applicable) to the actual application , not an alias or a document created by or for the application that will be run.

The "direct" parameter allows you to overwrite the direct parameter sent to the CGI. Leaving this parameter blank will simply pass along the direct parameter as it originally came from the server, but overwriting this is an important capability. By changing the parameter, you can make the CGI think that the requested URL was different than it really was. This parameter also replaces the "Script Name" field, so that CGIs that function as actions will work properly.

The CGI application "Responder" is included with the NetCloak package as an example of using back-end CGIs. Here is a snippet that will include Responder's output in the context of an HTML page served by NetCloak:

<EXEC_CGI "Responder.cgi">

In many cases, you may want only a portion of the CGI response. In the case of Responder, you might want only the BODY of the complete HTML page that it returns. You can filter out what you don't want by specifying a beginning and an ending phrase. Only text that appears between the phrases will then be show in the final page. Notice that you must specify the direct parameter (even if it is left blank) in order to use the filtering function. For example:

<EXEC_CGI "Responder.cgi" "" "<BODY>" "</BODY>">

Commands: HTTP Header

<HIDE_HEADER "text">

The HIDE_HEADER command will hide HTML following it if the specified text is contained anywhere in the header of the HTTP request. The text parameter must be enclosed in quotation marks because it may contain spaces.

The Web is based upon the HTTP protocol, which is constantly evolving. Every request that comes into your server is in the form of an HTTP header request that may or may not have additional information that is not captured by some other NetCloak command. The "Header" commands give you the ability to look into the header even when there is no direct NetCloak command for checking a particular piece of information. Let's look at the "Show" version of these commands for an easier explanation of how this works.

<SHOW_HEADER "text">

"Show_Header" will "turn the stream on" when the specified text appears anywhere in the HTTP header of the incoming request. The specified text can be an acceptable file type, the incoming URL, the username, or any other information included in incoming HTTP requests.

For example, some browsers now support a "Host:" field which specifies the domain name of the server they are requesting information from. If you are running multiple "virtual servers" on a single Macintosh, you can use this information to direct requests for these server's home pages to an appropriate home page for each domain. This is sometimes called "Multi-Homing", because the goal is to have multiple home pages served from a single server. For example:

<HIDE><SHOW_HEADER "www.abc.com">
Welcome to "ABC.COM". This is their Home Page!
<HIDE><SHOW_HEADER "www.123.com">
Welcome to "123.COM". This is a different Home Page than ABC!

For browsers that support the "Hosts" field, only the Home Page from the requested domain will be displayed to any given user.

The HTTP header can also be used to help determine language information, file types the browser can accept, and more. Essentially any information that the browser sends to the server is yours for the asking.

<INSERT_HEADER>

The INSERT_HEADER command inserts the entire HTTP request header into the HTML document.

It is rare that you would want to display the HTTP header of an incoming request back to the user. There is, however, at least one very good reason for doing this. As new browsers become available with new HTTP features, you will want to add support for them into your documents. By using the "Insert_Header" command in a few test pages, you can see exactly what information is being sent by various browsers. This makes it easy to try out different browsers on your pages to see just what the browser is sending so that you know what to look for when you are developing new pages.

The usage of this command is simple, and looks like this:

<PRE>
<INSERT_HEADER>
</PRE>

We use the "<PRE>" HTML tag because the HTTP Headers are best viewed in this mode so that carriage return/line feed pairs are displayed on the browser correctly.


[ Previous | Table Of Contents | Next ]

Copyright © 1996 Maxum Development Corporation
820 South Bartlett Road - Suite 104
Streamwood, IL 60107
http://www.maxum.com/