Reference Guide
Dynamic Page Commands:
Random, File Info, Server Info, Configuration, Variables, Cookies, Utility
Contents
|
Version 3.1 Reference Guide |
Dynamic Page Commands:Random, File Info, Server Info, Configuration, Variables, Cookies, Utility |
Previous |
Next Contents |
INSERT_RANDOM allows you to display a random number in your document. By default (without a 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>
These commands hide or show the HTML text to users based on a random number. If the random number generated by the command is less than the threshold specified, the HTML text which follows the command will be hidden or shown.
If no range is specified, SHOW_RANDOM will use a range of 100, and the threshold is equivalent to a percentage from 1 to 100. For example, to display a line randomly:
<HIDE><SHOW_RANDOM 30>
This line seen 30% of the time.
Remember that each random line is independent of the others. If you place several SHOW_RANDOM commands in sequence, more than one of these lines may be shown, and it is also possible that none will be shown. In order to ensure that one and only one line in the group is shown on a page, use the SAMERAND commands explained below.
The optional parameter range allows you to adjust the range of possible random values. This will show the text following the command in a fraction of the times the page is loaded, equal to the threshold divided by the range. For example:
<SHOW_RANDOM 1 3>
This would show the text following it in 33% (1/3) of the times the page is served.
Specifying a range greater than the default of 100 allows for a finer level of control over the command than a single percentage, and in many cases simplifies the logic of your HIDE and SHOW commands. It also makes it possible to select from more than 100 possible options. The range for randomly generated values is 1 to 10,000.
This command inserts the most recently generated random number into the page without generating a new random number.
These commands hide or show the HTML text to users based on the random value generated in a preceding HIDE, SHOW or INSERT_RANDOM command. When the preceding RANDOM command has no range specified, the threshold is a percentage from 1 to 100.
SHOW_SAMERAND may 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 total of the threshold values in the commands equal the range of the RANDOM command). If the total is less than the range of the RANDOM command, there will be a chance that none of the items will be shown.
For example, to show exactly one of four 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, one graphic will be randomly displayed:
<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>
If a range other than the default has been specified in the preceding RANDOM command, the text following will be shown a fraction of the times the page is served defined by the threshold in the SHOW_SAMERAND command and the range in the preceding RANDOM command. For example:
<HIDE><SHOW_RANDOM 1 3>
This will only be shown 1/3 of the time.
<HIDE><SHOW_SAMERAND 1>
This will be shown 1/3 of the time when the first line is not.
<HIDE><SHOW_SAMERAND 1>
This will be shown the remaining 1/3 of the time.
The INSERT_MODIFIED command allows you to easily insert the date that the given file was last modified.
The filepath parameter may be either relative to the Root Folder, or relative to the location of the page being served. It may be specified using either the URL style for file paths (using slash '/' characters to delimit folder names), or the MacOS style (using colons ':' to delimit folder names). If the first character of the file path is a colon or a slash, the file path is assumed to be relative to the Root Folder. Otherwise, it is assumed to be relative to the location of the page being served. For example, if the Root Folder is MacHD:Web:, then the command:
<INSERT_MODIFIED "/news/latest.html">
…will always insert the last-modified date of the file:
MacHD:Web:news:latest.html
If the command:
<INSERT_MODIFIED "local/weather.html">
…is located in the file:
MacHD:Web:usa:indiana:default.html
…then NetCloak will insert the last-modified date of the file:
MacHD:Web:usa:indiana:local:weather.html
…into the web page when it is served. If the file path contains spaces, be sure to put it in double-quotes.
If the filepath parameter is missing, then the command will display the last modified date of the current page being served. For example, many pages may end in:
This page last updated on <INSERT_MODIFIED>.
The remaining two optional parameters works the same way as they do in the INSERT_DATE command.
The offset parameter lets you specify an offset from the file's modification date, in fractions of hours. For example, the following command:
<INSERT_MODIFIED "news.html" +168>
…will insert a date 7 days after the file newstuff.html (located in the same folder as the current page) was last modified. Why is this useful? When this command is nested inside a SHOW_DATE command, it gives you an easy way to automatically highlight files for a period of time whenever they are updated on your web site. The following code will automatically append a New! graphic to the hypertext link for seven days whenever the linked page is updated:
<A HREF="news.html">Recent News</A>
<HIDE><SHOW_DATE LT
<INSERT_MODIFIED "news.html" +168>>
<IMG SRC="new.gif">
<SHOW> <BR>
The format of the date inserted will depend on the date format you have selected in the Date & Time control panel, as well as the date format setting in NetCloak. See the "Configuring NetCloak" section in the User's Guide for more information on the way that NetCloak formats dates.
You can override the default date format setting by specifying either SHORT or LONG in the format parameter. The Date & Time control panel allows you to configure two date formats: a long format and a short format, and the format parameter allows you to select which should be used to display the date. The format may be specified without specifying an offset.
The command can also 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.
Note that if you use the INSERT_MODIFIED command inside a page that is not stored on disk (such as from a back-end CGI), NetCloak will not be able to determine a modified date and will insert the current date instead.
This command inserts the size of the specified file as it is stored on disk. If a filepath is not specified, the size of the page being served is given. There are three 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 filepath parameter may also refer to any file on the web server. Like all paths specified in NetCloak, when the path begins with a slash (/), the path is relative to the root folder defined in the NetCloak Configuration window. Here are some examples:
<INSERT_FILESIZE_B /MyFile.sit.hqx>
<INSERT_FILESIZE_K /Folder/Moof.hqx>
<INSERT_FILESIZE_M /BigFile.sit.hqx>
The first example is a file (MyFile.sit.hqx) that resides in the root folder and the size is displayed in bytes. The second example gives the size, in kilobytes, of a file in a folder named Folder contained in the root folder. The last example shows the number of megabytes used by a file in the root folder.
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.
Most browsers now support the Host field in the HTTP header. The Host field specifies the name of the server that the user has requested the document from. In most cases, this field will be the domain name of your server, or its IP address if the requested URL was specified by IP address.
This command can be very helpful in two situations. First, if your server has multiple domain names associated with it, the Host field is an excellent way to find out which domain name was requested by the client. For details on supporting multiple domains with the Host field, see the SHOW_HOST section below. Second, if you serve your Web site from multiple servers, you can create pages that are sensitive to the server they are being served from.
The INSERT_HOST command simply inserts the domain name (or IP address) that the URL specified when requesting the page.
Note that some older browsers do not send the Host field in the HTTP header. When pages are accessed by these clients, the INSERT_HOST command will not insert anything.
The HIDE_HOST command allows you to hide portions of a page based upon the domain name (or IP address) as specified in the URL used to access the page. Text after the command will be hidden if the requested host satisfies the comparison with any of the host parameters.
If the comparison operator is omitted from the command, a contains text comparison is used, so that a host name containing any one of the following parameters causes text to be hidden.
The SHOW_HOST command allows you to hide portions of a page based upon the domain name (or IP address) as specified in the URL used to access the page. Text after the command will be shown if the requested host satisfies the comparison with any of the host parameters.
If the comparison operator is omitted from the command, a contains text comparison is used, so that a host name containing any one of the following parameters causes text to be hidden.
For example, assume your web server is used to serve pages for three different domains: www.greg.com, www.peter.com, and www.bobby.com. Each of these domain names points to the same address, which is the address of your server, and each web site is served from a sub-folder within the root folder (called greg, peter, and bobby). The default page for your server, at the root level, could be:
<HIDE><SHOW_HOST IS "www.greg.com">
<REDIRECT "http://www.brady.com/greg/">
<HIDE><SHOW_HOST IS "www.peter.com">
<REDIRECT "http://www.brady.com/peter/">
<HIDE><SHOW_HOST IS "www.bobby.com">
<REDIRECT "http://www.brady.com/bobby/">
<SHOW>
The requested host is unknown. Please select from the following list of domains:
In this case, the SHOW_HOST command is used to select a REDIRECT command which sends the client to the correct default page for the domain. If the Host isn't recognized (most likely due to lack of support for the field in the browser), a default page is shown to the user so they can select the domain they are looking for.
Note that the MACRO command could be used in place of the REDIRECT commands to reduce processing, although the relative paths for URLs in the individual Home Pages could be confused. See the MACRO command for additional information.
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 so that line breaks are displayed on the browser correctly. These formatting tags are not required, but the header will most likely be difficult to read without them.
The HIDE_HEADER command will hide HTML following it if the HTTP request header satisfies the comparison with any of the given text parameters.
If the comparison operator is omitted, a contains text comparison is performed, so text is hidden if the HTTP request header contains any one of the given text parameters.
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.
The SHOW_HEADER command will "turn the stream on" when the HTTP request header satisfies the comparison with any of the given text parameters.
The specified text can be an acceptable file type or language, the requested URL, or any other information included in incoming HTTP requests.
If the comparison operator is omitted, a contains text comparison is performed, so text is shown if the current HTTP request header contains any one of the given text parameters.
For example, many browsers support a field which specifies the languages they can accept and display. If you would like to selectively serve files in various languages, you can use this field to automatically select text to be displayed. For example, to display a section of text in French to browsers that support it, you might use:
<HIDE><SHOW_HEADER CONTAINS "Accept-Language: fr">
Bon jour!
<FLIPMODE>
Hello!
<SHOW>
In this example, if the browser sends the appropriate field, the French text will automatically be displayed by NetCloak.
The HTTP header can also be used to help determine file types the browser can accept and more. Essentially any information that the browser sends to the server is yours for the asking.
Inserts a line (field) into the HTTP header when the page is returned to the client. The entire HTTP header line must be specified, normally according to the format:
FieldName: FieldValue
For example, to add a line to the HTTP header that will specify a user agent, you could use the command:
<SET_HEADER "User-Agent: SomeUserAgent/1.0">
Additional header fields may be used for cache control, supporting advanced HTTP features, etc. Header fields normally generated in the HTTP response by NetCloak will be over-ridden by the SET_HEADER command. For example, a page of text that must be served by NetCloak but is not an HTML file could include the command:
<SET_HEADER "Content-type: text/plain">
This would cause NetCloak to send text/plain as the file's content type instead of the normal text/html.
Finally, header lines may be generated dynamically using local variables and then inserted into the HTTP response header by referencing the variable name. For example:
<SET_LOCAL ExpHeader = "Expires: " &
<INSERT_DATE +48 LONG>>
<SET_HEADER ExpHeader>
This command will insert the URL of the last page visited into your document at the specified point. The URL will be exactly as reported by the browser, including server name and path and search arguments.
Here is an example:
You just came from: <INSERT_REFERRER>.
If you want, you can:
<A HREF="<INSERT_REFERRER>">Go Back!</A>
Note that this command will not work if the browser does not report the last page the user visited. In general, the referrer will be reported when the user clicks on a hypertext link to access the page. However, if the user manually enters the URL, the browser may not send the referrer, since the page the user was on when they entered the URL doesn't actually reference the page being served.
You can avoid giving the user a link to a non-existent referring page using a HIDE_REFERRER or SHOW_REFERRER command, described below.
Since REFERRER is commonly misspelled REFERER (including in early versions of the Internet specification for HTTP), NetCloak also supports that spelling for all REFERRER commands.
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.
If the comparison operator is omitted, a contains text comparison is performed with the listed referrer values.
Note that if a user types an URL into their Web browser to get to your page, there will be no referrer, since the page the user was on when they entered the URL doesn't actually reference the page being served.
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, or by using the EXISTS comparison operator. In other words, HIDE_REFERRER> or HIDE_REFERRER EXISTS> will hide the text following it whenever a referrer is known.
HTML text that follows this command will be visible to users when the most recent document they visited in their web browser satisfies the comparison with at least one of the specified referrer parameters.
If the comparison operator is omitted, NetCloak will show text if the referring page's URL contains any one of the listed referrer values.
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 CONTAINS 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 parameters, or SHOW_REFERRER EXISTS>, to make sure the browser supports the referrer field and avoid providing a broken link to a nonexistent referrer, like this:
<HIDE><SHOW_REFERRER>
You just came from <INSERT_REFERRER>.
<A HREF="<INSERT_REFERRER>">Go back there!</A>
<FLIPMODE>
Sorry, your browser does not support referrers, or you entered the URL for this page manually.
<SHOW>
The INSERT_THISURL command ("This URL"), which accepts no parameters, will cause the file path and document name of the current page to be inserted into the page. For example, if the URL for a page is:
http://www.web.com/bob/page.html$path?qry
the INSERT_THISURL command would insert:
/bob/page.html
With servers that support virtual hosting of multiple Web sites, the path will be relative to the root folder for the requested site.
The INSERT_THISURL 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 this page" link, or to give the user additional feedback on how your site is set up.
If the URL of the current page satisfies the comparison with any of the listed URL parameters, then this command shuts off the flow of text to the browser.
If the comparison operator is omitted, then the comparison is satisfied when the URL of the current page contains any one of the given URL parameters.
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.
This is the SHOW version of the HIDE_THISURL command above.
Here's an example:
<HIDE><SHOW_THISURL CONTAINS TestFolder>
This page is in the folder 'TestFolder', and is still being tested. When the file is moved into its final place on my site, this test message will disappear.
<FLIPMODE>
This page is now in production use.
<SHOW>
When a non-existent page is requested and the error page is served, THISURL is the requested (non-existent) URL. This makes the SHOW_THISURL command useful for making a smart error page. If users have a typo in their URL, the error page can automatically redirect them to the page they were looking for.
<HIDE><SHOW_THISURL CONTAINS faq>
<REDIRECT "http://my.server/questions/faqlist.html">
<SHOW>
You can use a similar technique to automatically redirect users accessing obsolete pages by putting the URL of the obsolete page in the SHOW_THISURL command and the new URL in the REDIRECT command.
With the example above on your error page, users who request a page that does not exist but contains FAQ will be automatically redirected to the FAQ List page.
In an HTTP URL, there are three parts of the URL that come after the server name. The first is a path to the requested file. The second part, called the path arguments, follows the name of the requested file. In MacOS web servers, the path arguments are separated from the filename by a dollar sign character ('$'). Following the path arguments is the third part of the URL, called the query arguments or search arguments. The search arguments are separated from the path arguments (or the filename, if there are no path arguments) by a question mark character ('?'). Both path arguments and search arguments are URL encoded by browsers (in other words, all non-alphanumeric characters are turned into a percent sign '%' followed by the two-digit hexadecimal ASCII code for the character). Here is an example URL containing both path arguments and search arguments:
http://www.maxum.com/netcloak/sample.html$path%20Args?search%20Args
In this example the path arguments consist of the text path arguments (which have been URL encoded, turning the space character into %20), and the search arguments consist of the URL encoded text search Args. It is important not to confuse path arguments with the requested file path. In the example above, the file path is /netcloak/sample.html.
Path and search arguments can be used to send additional data to NetCloak to be used in processing cloaked pages, simply by appending them to the URL of any cloaked page, then using the following commands within the cloaked pages.
The INSERT_PATH command inserts the path arguments for the requested URL into the cloaked page. If there are no path arguments in the requested URL, this command does nothing.
If the file /netcloak/sample.html in the above example contained the following HTML:
This text follows the dollar sign in the requested URL: <INSERT_PATH>
The page seen at the browser would contain:
This text follows the dollar sign in the requested URL: path args
Important Note: If you are using the NetCloak CGI by calling it directly in your URLs, like this: http://www.yourdomain.com/NetCloak.acgi$/somefile.html, then the path arguments are used to send the URL of the cloaked file to NetCloak, and are not available for you to use for other purposes. In this case, the INSERT_PATH command will insert the path to the cloaked file.
The HIDE_PATH command turns off the flow of text in the page if the path arguments in the requested URL satisfies a comparison with any of the path parameters listed in the command. See SHOW_PATH for an example where this could be useful. If the comparison operator is omitted, a contains text comparison is performed.
The SHOW_PATH command turns on the flow of text in the page if the path arguments in the requested URL satisfy the comparison with any of the parameters listed in the command.
When no comparison operator is used, the flow of text is turned on when the path arguments contain any one of the parameters listed.
The SHOW_PATH command can be useful when you want one page to contain all the logic for some interactive process, like an online questionnaire or game. Rather than spreading the logic for the interaction across multiple cloaked pages, you can put it all in one cloaked page, and use path arguments to determine which part of the process to send to the browser.
For example, a form can be submitted and processed by the same page, based on the path argument. The form command looks like this:
<FORM METHOD=POST ACTION="regkillerapp.html$step2">
Notice the path argument specified, Step2. Later in the page, the form is processed by enabling one section of HTML using the NetCloak command:
<HIDE><SHOW_PATH IS "step2">
Similarly, the form itself must be hidden once it has been submitted. This can be done like this:
<HIDE>
<SHOW_PATH IS "step1">
<SHOW_PATH #EXISTS>
This shows the form when either the first step is specified by the path argument, or when no path argument exists (as would be the case when the form is linked to from another page).
The INSERT_SEARCH command inserts the search arguments for the requested URL into the cloaked page. If there are no search arguments in the requested URL, this command does nothing.
If the file /netcloak/sample.html in the INSERT_PATH example contained the following HTML:
This text follows the question mark in the requested URL: <INSERT_SEARCH>
Then the browser would see:
This text follows the question mark in the requested URL: search args
Note: When an HTML form specifies a method of GET instead of POST, the data in the form fields are appended to the URL specified in the action of the form, as search arguments. The SEARCH commands can be used to look at the raw form data. See the section "Commands: User Variables" for more information.
HIDE_SEARCH turns off the flow of text in the page if the search arguments in the requested URL satisfy the comparison with any of the parameters listed in the command. SHOW_SEARCH turns on the flow of text if the search arguments in the requested URL satisfy the comparison.
A contains comparison is performed if no comparison operator is used.
Search arguments typically are used (as their name implies) to send text to be searched for, either in a database or in the files of the web site. But with NetCloak, they can be used just like path arguments, for just about any purpose. Here's an example where we use NetCloak commands to add better feedback and a consistent look-and-feel to the results returned from a simple file-searching CGI. If no search arguments are provided, we avoid calling the CGI altogether:
<HTML>
<HEAD><TITLE>Search Results</TITLE></HEAD>
<BODY>
<MACRO Header>
<HIDE_SEARCH #EXISTS>
<H1>Search Results</H1>
Here are all the matches found for the phrase "<INSERT_SEARCH>":<P>
<HR>
<EXEC_CGI "SimpleSearch.cgi">
<!-- The CGI returns raw results -->
<HR>
<FLIPMODE>
<P>No search arguments were supplied. Please try again.<P>
<MACRO Footer>
</BODY>
</HTML>
The SET_NETCLOAK (or NETCLOAK) command is used to set many of NetCloak's configuration options for a single page, or even for only part of a page. These options, when set using this command, will supersede the default settings that have been defined in NetCloak. However, the revised setting will only be in effect for the page in which the SET_NETCLOAK command is used. Other pages being served will be unaffected by temporary configuration changes made with the SET_NETCLOAK command.
Here are the configuration options that can be set using this command. For each setting, the list of valid values is given.
Translation - This sets the character translation mode for text following the command. Possible values are:
For example, to have NetCloak perform MacRoman to ISO-Latin-1 character translation, you could use the command:
<SET_NETCLOAK Translation = Latin>
NewFileTranslation - Tells NetCloak what character translation to perform, if any, when creating new files with a CREATEDOC directive. The options for use with this setting are:
LastMod - This allows you to change the Last Modified field of the HTTP header for the page on which the command appears. Possible values include:
For example, assume you have a page with numerous sections of random content, but you have set NetCloak to return the file's modification date as the Last-Modified date of the HTTP header, by default. For the page in question, you can override this default by including the command:
<SET_NETCLOAK LastMod = Now>
This will cause the browser to recognize the fact that the page is constantly changing, and perform caching appropriately.
TimeFormat - This allows you to change the format of time values in the current page. Possible values include:
DateFormat - This allows you to change the format of date values in the current page. Possible values include:
Logging - Lets you enable or disable logging of pages on a per-page basis. Possible values include:
ServerField - This text value is sent as the value of the Server: field in NetCloak's HTTP reply header.
PragmaNoCache - This determines whether or not NetCloak will tell the browser (and any other caching mechanisms in between) to not cache the page.
DuplicateFiles - Tells NetCloak what to do when creating files via a CREATEDOC directive, and an existing file with the same name in the same folder already exists. Valid options for this setting are:
CreatorCode - The four-character creator signature NetCloak uses for created files. The creator code determines the icon of the file, as well as which application launches when the file is double-clicked.
ConvertBrackets - This allows you to determine how NetCloak will handle angle bracket characters in form field data when they are inserted into the resulting page. Options for this setting:
LinkNextText - Defines the text displayed in the hypertext link created by the LINKNEXT> tag in created documents. The value of this configuration setting can by any string of text not including double-quote characters.
LinkPrevText - Defines the text displayed in the hypertext link created by the LINKPREVIOUS> tag in created documents. The value of this configuration setting can by any string of text that does not include double-quote characters.
INSERT_NETCLOAK inserts the current value of the specified configuration parameter into the page. In addition to the configuration settings listed above, this command also lets you insert the following information into the page:
These commands show or hide the HTML that follow them (until the next SHOW/HIDE command) if the specified configuration parameter satisfies the comparison to the given value. As with other commands, you may specify a list of values to test against. If the comparison operator is omitted, an exact text match is required.
For example:
<SET_NETCLOAK DateFormat = Long>
This command will cause NetCloak to display all dates inserted by NetCloak commands in the remainder of the page using the Long Date format defined in the server's Date & Time control panel.
<HIDE><SHOW_NETCLOAK Logging IS "Off">
Logging is currently disabled.
<FLIPMODE>
Logging is currently enabled.
<SHOW>
This series of commands will tell the user whether or not their web server access is being logged by NetCloak.
The SHOW and HIDE_NETCLOAK commands are also useful in combination with the SET_NETCLOAK command to make conditional changes to NetCloak configuration settings.
NetCloak supports four distinct types of variables: Local, User, Global, and Cookies. The first three types are stored by NetCloak. Cookies are different from the others in that they are stored at the client, so they will be discussed separately later.
Variables have a name and a value. A variable name consists of alphanumeric characters, may not contain quote marks, expression operators (+,-,*,/, &), the '#' character, or whitespace characters, and may not begin with a digit or an exclamation point. A variable may have any text or numeric value.
Local variables can be used only within a single HTML page. Local variables can be set at the top of the page and used repeatedly within the page, but once the page has been served completely the variable is forgotten. Local variables are useful for storing data that only needs to be used on another part of the same page, such as in math functions, simplifying complicated SHOW/HIDE expressions, passing variables into macros, looping in a REPEAT command, etc.
User variables remain in effect for a particular user during the time they are visiting your site. When a form is submitted to NetCloak, the fields on the form become NetCloak user variables automatically. User variables will not affect users other than the user they are set for, but they persist between page accesses for up to one hour or until another form is submitted by the same user. User variables are tracked either by the visitor's IP address or by a default cookie that can be generated by NetCloak. Note that when the user does not have a browser which supports cookies, then user variables will be tracked by IP address even if you set the default cookie. See the SET_COOKIE command description for information about creating a default cookie.
Global variables are variables that are retained indefinitely and have a single value for all pages being served to all users. You can use globals as mini-macros, making short blocks of text (a few characters or words) easy to use throughout your site. Global variables also allow you to have the actions taken by one user on your site to impact others. For example, you could have a form that allowed you, as the Webmaster, to turn on and off various portions of your Web site, by showing and hiding links to pages based on global variables that were affected by form submissions. You could also create multi-user games, implement opinion polls, and more.
Global variables can be created and updated one of three ways:
NetCloak allows you to create HTML forms that ask the user to enter information and then use that information in your pages. The contents of the form are then automatically used to create User Variables.
Each field of your HTML form will have a name. Once the form is submitted, each field becomes a NetCloak User variable with the same name, whose value is the value entered into the field by the user. 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 that uses the POST method for form processing. In the ACTION field of your FORM command, you will need to specify the URL of 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:
<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">
</FORM>
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 the Submit Form button. 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.
Once a form has been processed, the fields on the form become User variables that may be used within cloaked documents.
Some form variables can have multiple values. These are called multivalue variables. An example is a set of checkboxes that all have the same field name but different values, or a SELECT field with the MULTIPLE attribute (which is usually displayed as a list box that allows multiple selections). NetCloak allows you to access all of the values of a multivalue variable, using square brackets after the variable name which include the number of the instance you want to use. For example, to access the third instance of a variable named Toppings, you could write:
<INSERT_VARIABLE Toppings[3]>
Furthermore, you can use the name of another variable within the square brackets to access an instance of a multivalue variable, like this:
<INSERT_VARIABLE Toppings[gDailySpecial]>
This notation is supported in all NetCloak INSERT, SHOW, and HIDE commands, as well as the REPEAT command.
Variables can be assigned values either by user input or by using the SET_LOCAL, SET_VARIABLE, or SET_GLOBAL commands. Each of the SET commands sets the variable VariableName to a given value. The equal sign (=) is optional. The Value can be a string, a number, or another local, user, global, counter or cookie variable (see below for information about cookies). In addition, five operators can currently be used to create a value from an expression. They are:
+ Performs simple addition.
- Subtracts the second value from the first.
* Multiplies two values.
/ Divides the first value by the second.
& Concatenates two values (Adds the strings).
For example, to put the value of 2 + 2 into the local variable Four, you could use the command:
<SET_LOCAL Four = 2 + 2>
Another way to put the number 4 into the variable Four would be:
<SET_LOCAL Two = 2>
<SET_LOCAL Four = Two * 2>
We could also set a variable called TwentyTwo by doing something like:
<SET_LOCAL Two = 2>
<SET_LOCAL TwentyTwo = Two & "2">
When performing numeric operations in SET commands, NetCloak gives the resulting variable the same number of decimal places as the parameter with the most decimal places on the right-hand side of the equal sign. Thus, if no decimal places are given, then NetCloak will display no decimal places when the resulting variable is INSERTed into a page. Conversely, the following code:
<SET_LOCAL a = 12.3456>
<SET_LOCAL b = 3>
<SET_LOCAL c = a * b>
<INSERT_LOCAL c>
...will cause the value 37.0368 to be inserted into the page. See the INSERT variable commands, below, for more information about controlling the number of decimal places displayed.
You can include multiple operators in the same SET command, but be aware that NetCloak does not honor any operator precedence rules - it merely works from left to right. Thus, all of the following are allowed by NetCloak:
<SET_LOCAL newURL = "http://" & gHostName & "/" & <INSERT_THISURL>>
<SET_LOCAL TwoTwentyTwo = 200 + 20 + Two>
<SET_LOCAL WhoKnows = 200 - 20 / 2>
<SET_LOCAL NotOne = 1.0/2.0 + 1.0/2.0>
...but only the first two will produce results you might expect. The third command assigns a value of 90 to the variable WhoKnows; the last assigns NotOne a value of 0.8.
It is standard practice to put strings in quotes and leave numeric values without, but NetCloak will accept a number in quotes or a string without. Also, the equal sign is not required, though is encouraged for readability, especially when performing numeric operations.
When assigning a variable, you can reference any local, user, global, counter, or cookie variable on the right-hand side of the equal sign, without using a nested INSERT command. So, you can set a local variable to the value currently held in a global, or a global variable to the current value of a counter.
For example, let's say you have a counter on your home page called HomeHits, and another counter on every page of your server called TotalHits. You could display the percentage of hits your home page receives on your site with something like:
<SET_LOCAL HHTemp = HomeHits * 100>
<SET_LOCAL Percentage = HHTemp / TotalHits>
Home Page: <INSERT_LOCAL Percentage>%
To determine the value of a variable found on the right-hand side of the equal sign in a SET command, NetCloak searches for variables in order from most-specific scope to least-specific scope. In other words, it looks for variables that are most-specific to the current page first. It searches for variables in this order:
Thus, if you have defined a local variable and global variable with the same name, the value of the local variable will be used first. If NetCloak does not find any matching variable name, the variable name itself is used as the value of that parameter.
These commands will place the contents of the variable into the page. The value inserted may be a computed variable created using a SET command, or it could be the field from a user-entered form.
For example, after the form above has been filled out and submitted, you could use the following command to display the user's name:
Your name is: <INSERT_VARIABLE YourName>
Inserted variables will appear as you would expect, with the value of the variable inserted at the point at which the INSERT command is placed. Numeric values will be displayed as numbers (not an ASCII representation of the value) so that a variable with a value of 65 will be displayed as 65 and not the letter A.
If the variable value is a number, you can control the number of decimal places displayed by providing the optional decimalPlaces parameter. If omitted, all decimal places from the value will be displayed. This parameter is ignored if the variable's value contains any characters other than a digit, period, plus, or minus character. For instance, the following code:
<SET_LOCAL a = 12.3456>
<SET_LOCAL b = 3>
<SET_LOCAL c = a * b>
<INSERT_LOCAL c 1>
...will insert the value 37.0 into the page.
Important Note! It is possible for NetCloak to incorrectly identify users and confuse the variables. This can occur when browsers don't support cookies (or are configured not to allow them) and/or when user IP addresses are being dynamically assigned or users connect through a proxy server. For this reason, you should not use User 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) User variables will be reliable.
Also note that expressions used to create values for variables (+, -, etc.) cannot be used in INSERT commands. To display a computed value, you must SET a variable first then reference it by name in the INSERT command.
Any HTML text that follows HIDE_LOCAL, HIDE_VARIABLE, or HIDE_GLOBAL will be hidden from those users when the specified variable satisfies the comparison to any one of the listed values. If the comparison operator is not specified, text is hidden if the variable's value contains any of the listed values.
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 CONTAINS "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 IS "CHECKED">
You didn't check the check box!
Frequently, it is necessary to check that a variable value is not empty, as when a user is filling out form fields. You can check for non-empty variables using the EXISTS operator, or by simply not specifying a value in the HIDE command. For example:
<SHOW>
<HIDE_VARIABLE EXISTS YourName>
You didn't enter a name!
<SHOW>
The text "You didn't enter a name!" will only appear if the YourName field was left blank in the form.
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 checked, by using:
<HIDE>
<SHOW_VARIABLE MyCheckBox IS "CHECKED">
You checked the check box!
<SHOW>
This is a handy utility command which displays a list of all the defined user variables for the current page. The list of variables is formatted according to the HTML text inserted between the opening and closing VARIABLE_LIST tags. The HTML text is repeated once for each defined variable. Within this HTML text, any occurrence of the special tag VARNAME is replaced with the variable name, and the special tag VARVALUE is replaced with the value of that variable. An example will make things clearer. Suppose a user has submitted a form with three fields: a field named Crust with a value of Deep Dish, a field named Topping with a value of Pepperoni, and a field named Size with a value of Medium. Then the following code:
<VARIABLE_LIST>
<B><VARNAME>:</B> <VARVALUE>
</VARIABLE_LIST>
...will cause the following text to be displayed in the browser:
<B>Crust:</B> Deep Dish
<B>Topping:</B> Pepperoni
<B>Size:</B> Medium
This command is very handy for debugging purposes, as well as for passing variables from one form to another when the variable names may not be known in advance.
Cookies, like other kinds of variables, are made up of two parts: a name and a value. They are transferred in the HTTP header of both user requests and server responses, and are stored by the browser on the user's computer.
When the user asks for a page, the server is allowed to send a cookie in the header (it won't be seen in the HTML page) along with the response page it would normally send. The browser is expected to store the cookie so that when it makes subsequent requests of the server it can send the cookie name and value.
NetCloak gives you the ability to create cookies, and it even makes them easy. Cookies have lots of uses, and are actually a lot like user variables. In some cases, user variables may be better because they can be tracked even when a browser doesn't support them and the data doesn't need to be constantly resent by the browser. On the other hand, cookies have the capability of sharing information among multiple servers, or between different add-on tools on the same server. Cookies are also more reliable when users may be coming through proxy servers or have dynamic IP addresses, such as America Online users.
Even if you prefer to use user variables, cookies can be used to help NetCloak track the variables. For users dialing in using shared modem pools or proxy servers, cookies give NetCloak a reliable way to track the user variable data.
NetCloak supports a default cookie, named NetCloakID. When this cookie is found, it will use the cookie's value as a key to the user variable data, instead of the user's IP address. To create a randomized default cookie, use the command:
<SET_COOKIE>
For example, the command SET_COOKIE on your server's home page will generate a string and send it as a cookie named NetCloakID. If accepted by the browser, all subsequent user variable operations (using either SET_VARIABLE or forms submitted by the user) will store the variable data based on this randomized key. If the browser refuses the cookie (either it doesn't support cookies or the user chooses not to accept it), then NetCloak will store user variables using the user's IP address as the key. If you are using User variables on your site, it is recommended that you include a SET_COOKIE command on your home page to improve tracking of users.
Be sure that if you're tracking user variables with the default cookie, you don't overwrite the cookie's value after it is created, or the link between the variables and the browser will be broken. You can do this by always checking that the cookie exists using a HIDE_COOKIE command before a SET_COOKIE command, like this:
<HIDE_COOKIE NetCloakID EXISTS>
<SET_COOKIE>
<SHOW>
In addition to the default cookie, you can also specify up to sixteen additional cookies per user, named whatever you like. A cookie name may only include alphabetic characters, no spaces, and is case-sensitive. The value is optional; if you specify a value, then that value will be given to the cookie, and if you don't NetCloak will generate a random value for you.
For example, to create a cookie named BeenThere with a value of DoneThat, use the command:
<SET_COOKIE BeenThere = "DoneThat">
The optional expirationDate parameter allows you to specify the expiration date for the cookie. The user's Web browser will store the cookie between sessions and return it on subsequent visits to the page until the expiration date is reached. This allows you to track users between visits to your site. If no expiration date is specified, the cookie will expire when the user quits the browser.
The expiration date is specified either as date@time, in the same format as HIDE_DATE and other commands which accept date parameters, or as an offset to the current date and time. A negative offset can be used to delete a cookie from the browser's "cookie jar" before its expiration date.
For example:
<SET_COOKIE myCookie "" "1/1/2000@17:00">
Sets cookie myCookie to a random value which expires on January 1, 2000 at 5 pm.
<SET_COOKIE myCookie = 701253 +1.5>
Sets cookie myCookie to 701253 which expires in 90 minutes.
<SET_COOKIE myCookie "" -1>
Deletes cookie myCookie from the browser's cookie jar.
The domain and path parameters allow you to specify which servers and which specific URLs within a server will receive the cookie when requested. If no domain or path parameters are given, then the cookie is sent in every request to the server from which the cookie originated. You can redirect the cookie to another host by specifying that host in the domain parameter, or you can supply a partial domain name so that the cookie is sent to all servers in the given domain. You can use the path parameter to limit the cookie so that it is only sent in requests to a given subfolder of your site. Examples:
<SET_COOKIE myCookie = "12345" +72 "maxum.com">
Send the cookie in all requests to any server in the .maxum.com domain for the next 72 hours.
<SET_COOKIE myCookie = "12345" "" "secure.sales.com">
Only send the cookie to the server secure.sales.com until the browser quits.
<SET_COOKIE myCookie = "12345" +72 "www.maxum.com" "/netcloak/">
Only send the cookie to the server www.maxum.com if the URL begins with /netcloak/, for the next 72 hours.
A special note if you have lots of visitors using America Online browsers: certain versions of AOL browsers only support persistent cookies, which means that you must supply an expiration date in the SET_COOKIE command or the cookie will be ignored. So, for best compatibility with AOL users, you should use the following code to track user variables with the NetCloakID cookie:
<HIDE_COOKIE NetCloakID EXISTS>
<SET_COOKIE NetCloakID = "" +24>
<SHOW>
This code will only create the cookie if it does not already exist, giving it a random value and an expiration date 24 hours from the time it is created.
This command will place the contents of the specified cookie into the page. For example, if you have set the BeenThere cookie noted above you can display it with:
Your Cookie Is: <INSERT_COOKIE BeenThere>
Inserted cookies will appear as you would expect, with the value of the cookie inserted at the point at which the INSERT command is placed.
Any HTML text that follows HIDE_COOKIE will be hidden from those users when the specified cookie satisfies the comparison to the specified text. If the comparison operator is omitted, a contains comparison is performed.
An example is included in the SHOW_COOKIE section below.
This command operates exactly like HIDE_COOKIE except that is turns the text stream on instead of turning it off.
For example, assume you have a planes page, a trains page, and an automobiles page on your site. Each of these pages sets the cookie LastMainPage to either planes, trains, or autos, accordingly. When the user accesses a form requesting more information, you could use the HTML:
<HIDE><SHOW_COOKIE LastMainPage IS "planes">
Airplane information can be received...
<HIDE><SHOW_COOKIE LastMainPage IS "trains">
Train information can be received...
<HIDE><SHOW_COOKIE LastMainPage IS "autos">
Car information can be received...
<SHOW>
Here, the cookie LastMainPage will always be set to the value defined by the most recently accessed of the three pages.
A simple example of a cookie might be to change the behavior of your server after the user has visited a page or taken some action. For example, you might have a form that asks people which sports car is best... the Porsche Boxter, the Mazda Miata, the BMW Z3, or the Honda DelSol VTEC. You could gather the results using global variables, use local variables to display the relative percentages of each car, and use a cookie to remember that the user has already voted and disallow them from voting again.
The INSERT_BEEP command causes the server to play the default system alert sound whenever the command is encountered. Nothing is inserted into the text of the page being served. The only effect is a system beep on the server.
At first glance, this command may not seen to be useful, but there are several cases in which it can be handy. You can use INSERT_BEEP while you are developing pages with NetCloak commands to verify that NetCloak is processing the page.
Another possible use for this command is in your server's error page. By including the command INSERT_BEEP on the error page, your server will beep any time an incorrect URL is processed by your server. This can give you a warning of broken links on your site as they are being accessed.
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.
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.
The command will not cause a redirect to occur if it is hidden by another NetCloak command, so redirects can be performed conditionally based on any SHOW and HIDE commands. The redirect command can be used in the server's error file to automatically send clients accessing bad URLs to the correct pages. You might also use the command to redirect an HTML page to a page that might be in a completely different format depending on the client's browser type, address or other information.
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 Protected.html. All other users will receive the public page.
<HIDE>
<SHOW_DOMAIN 192.1.>
<REDIRECT "http://my.server/Protected.html">
<SHOW>
<HTML>
<TITLE>Public Home Page</TITLE>
<BODY>
Welcome to our public Home Page!
</BODY>
</HTML>
The normal REDIRECT command returns a Moved Temporarily (302) HTTP response code to the requesting browser. The REDIRECT command can also return a Moved Permanently (301) response, by using REDIRECT* instead of REDIRECT, like this:
<REDIRECT* "http://my.server/Protected.html">
For permanently-moved files, the 301 response notifies proxy servers, search engines and other automated or caching systems that the old URL should be replaced permanently.
The REPEAT command is a very powerful command that allows you to insert a chunk of HTML text into a web page a number of times, based on the value of any NetCloak global, local, user, counter, or cookie variable. The HTML to be repeated is placed between the opening and the closing REPEAT tags. The number of times the text will be inserted depends on the condition defined in the REPEAT tag. The text is repeated until the condition is false. If the condition is always false, then no text is inserted.
Any comparison operator supported by the SHOW and HIDE commands may also be used in the REPEAT command. If the comparison operator is omitted, the REPEAT command will loop as long as the specified variable exists.
It is up to you to make sure an infinite loop is not created. When an infinite loop occurs, NetCloak continues to add the text to the returned page indefinitely and will make the server freeze or crash. In order to avoid an infinite loop, you must update some loop variable between the opening and closing REPEAT tags until the condition in the REPEAT tag eventually becomes false.
Ordinarily, you would use SET_LOCAL commands to increment or decrement a local variable inside the REPEAT tags. For example, the following code will create a simple 2-row by 3-column table:
<SET_LOCAL row = 1>
<SET_LOCAL col = 1>
<TABLE>
<REPEAT row LT= 2>
<TR>
<REPEAT col LT= 3>
<TD>Row <INSERT_LOCAL row> Col <INSERT_LOCAL col></TD>
<SET_LOCAL col = col + 1>
</REPEAT>
</TR>
<SET_LOCAL row = row + 1>
</REPEAT>
</TABLE>
Here is the HTML text that is actually sent to the browser:
<TABLE>
<TR>
<TD>Row 1 Col 1</TD>
<TD>Row 1 Col 2</TD>
<TD>Row 1 Col 3</TD>
</TR>
<TR>
<TD>Row 2 Col 1</TD>
<TD>Row 2 Col 2</TD>
<TD>Row 2 Col 3</TD>
</TR>
</TABLE>
The variable in the REPEAT command may also be a multivalue form variable (such as a group of checkboxes or a multiple select list box). In that case, you use a local variable to access each instance of the multivalue variable. For instance, let's suppose a user has filled out a form which contains a set of checkboxes to pick pizza toppings. You want to display the selected toppings back to the user so they can confirm their order. The checkboxes are all named Topping, and each checkbox in the form has a different value, like this:
<INPUT TYPE="checkbox" NAME="Topping" VALUE="sausage">
<INPUT TYPE="checkbox" NAME="Topping" VALUE="pepperoni">
<INPUT TYPE="checkbox" NAME="Topping" VALUE="mushrooms">
If the user chooses more than one topping, then multiple instances of the variable Topping will be created by NetCloak. Each instance can be accessed using square brackets like this: Topping [1], Topping[2], etc.
To loop through all the selected toppings, you can use a local variable between the square brackets, and repeat as long as an instance of the multivalue variable exists. So here is an excerpt from the order confirmation page:
<P>Selected Toppings:
<SET_LOCAL index = 1>
<REPEAT Topping[index] EXISTS>
<INSERT_VARIABLE Topping[index]>
<SET_LOCAL index = index + 1>
</REPEAT>
If the user checks the pepperoni and mushrooms checkboxes in the form, the confirmation page they get looks like this:
<P>Selected Toppings: pepperoni mushrooms
This command allows you to dynamically execute CGIs and insert their response into a page, 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 more information on how NetCloak calls other CGIs, see the section "Using NetCloak With Other CGIs" in the User's Guide.
The EXEC_CGI command accepts up to four parameters, though the second, third and fourth are optional. The CGIpath parameter is simply the path to the CGI application you would like to execute. The path must be the path to the actual application , not an alias or a document created by or for the application that will be run.
The scriptName 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 of the CGI AppleEvent, so that CGIs that function as actions will work properly.
The filepath and scriptName parameters may be either relative to the Root Folder, or relative to the location of the page being served. They may be specified using either the URL style for file paths (using slash '/' characters to delimit folder names), or the MacOS style (using colons ':' to delimit folder names). If the first character of the file path is a colon or a slash, the file path is assumed to be relative to the Root Folder. Otherwise, it is assumed to be relative to the location of the page being served. (See the INSERT_MODIFIED command for more information about filepath parameters.)
Maxum has produced a simple, freeware CGI named Responder which is useful for testing or demonstrating the EXEC_CGI command. Responder simply echoes the CGI request that is sent to it as an HTML page listing the various parameters separately. Here is a snippet that will include Responder's output in an HTML page served by NetCloak:
<EXEC_CGI "Responder.cgi">
You can download Responder from the Maxum Web site at http://www.maxum.com/.
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 inserted into the response page. Notice that you must specify the scriptName parameter (even if it is left blank) in order to use the filtering parameters. For example:
<EXEC_CGI "Responder.cgi" "" "<BODY>" "</BODY>">
This example would include only the parts of Responder's response that are between, but not including, the <BODY> and </BODY> tags.
Note that the EXEC_CGI command does not allow setting query or post arguments. (Query arguments are included in a CGI request URL preceded by a question mark; post arguments are sent as data from an HTML form.) EXEC_CGI therefore cannot be used with CGIs that depend on these for input. This typically includes database access CGIs, as well as search tools such as Phantom. If you have a CGI that depends on query or post arguments, consider running it as a back-end to NetCloak instead.
This command is only available in the NetCloak plug-in. It operates identically to the EXEC_CGI command, but instead of calling an external CGI application via AppleEvents, it calls another WebSTAR API plug-in running on the same web server as NetCloak, using the PIXO (Plug-In Cross Over) standard for inter-plug-in communication jointly developed by Maxum and Clearway Technologies, Inc. Most commercial WebSTAR plug-ins available today support PIXO.
In this case, the first parameter, serviceName, is the name of the PIXO service registered by the plug-in you want to call. The PIXO standard requires plug-ins to register a service name which provides other plug-ins access to their functionality. The convention for naming a PIXO service is to append the text _PIXO to the plug-in's normal action name. For instance, NetCloak's PIXO service name for processing HTML pages is CLOAK_PI_PIXO, and the PIXO service name used by NetCloak Pro to process FDML files is NFORMS_PI_PIXO.
Included in the NetCloak package (in the Goodies folder) is a plug-in called FireSite SSI_PIXO Adapter which allows you to call the WebSTAR SSI plug-in from cloaked pages. When this plug-in, WebSTAR SSI, and NetCloak are all installed, you can insert the contents of an SSI-processed page into a NetCloak-processed page like this:
<EXEC_PIXO "SSI_PIXO" "ssipage.shtml" "<BODY>" "</BODY>">
The above command will call WebSTAR SSI to process the file ssipage.shtml, and then insert the text between the <BODY> and </BODY> tags into the current page.
Using this command in any HTML page, NetCloak can trigger the processing of an FDML file whenever a Web page is accessed by a browser. Multiple instances of this command in a cloaked page can also be used to perform multiple tasks from a single form submission, without using CHAIN directives.
Where this command appears in the page, NetCloak will insert the response page returned from the FDML file.
The FDMLPath parameter is a filepath to an FDML file. This parameter conforms to the filepath rules described in the NetCloak Standard User's Guide; if the path begins with a slash or colon character, the path is appended to the Root Folder to locate the file. Otherwise, the path is appended to the path of the folder in which the page containing the EXEC_FDML command resides.
The optional beginText and endText parameters are used to extract only a portion of the response page to be inserted into the HTML page. If omitted, NetCloak will use <BODY> and </BODY> so that only the content of the response page body is inserted into the cloaked HTML page.
Here are some examples:
<EXEC_FDML "SendMsg.fdml">
This command processes the FDML file SendMsg.fdml, located in the same folder as the current page, and inserts the body of the resulting response page into the current page.
<EXEC_FDML "/forms/updaterpt.fdml">
<EXEC_FDML "/forms/log.fdml" "</HEAD>" "<BODY>">
This example causes two FDML files to be executed; the files named updaterpt.fdml and log.fdml, each located in the forms folder in the web server Root Folder. The response from processing updaterpt.fdml will be inserted into the HTML page. Because no text usually occurs between the </HEAD> and <BODY> tags in an HTML page, no text from the response of the second FDML file will be inserted into the final page.
The Macro command is used to insert text or HTML from a local file or pre-defined macros. If the specified macro name matches the name of a macro defined in the file NetCloak.macros, NetCloak will insert the contents of that macro into the HTML in place of the MACRO command. If the macro name is a pathname for a file, NetCloak will insert the contents of the specified file.
When inserting a file, the macroName parameter may be either relative to the Root Folder, or relative to the location of the page being served. It may be specified using either the URL style for file paths (using slash '/' characters to delimit folder names), or the MacOS style (using colons ':' to delimit folder names). If the first character of the file path is a colon or a slash, the file path is assumed to be relative to the Root Folder. Otherwise, it is assumed to be relative to the location of the page being served. (See the INSERT_MODIFIED command for more information about filepath parameters.)
When serving multiple virtual domains, macro file paths are resolved relative to the root folder for each virtual domain. This has two implications. First, no macro may access any file outside its virtual domain's root folder, unless you create aliases within the virtual domain's root folder. Second, this lets you provide macros that are customized for each virtual domain.
If NetCloak is unable to insert a specified macro, it will insert an error message enclosed in an HTML comment. View the HTML source of the document after it is served to a Web browser to see the error message.
If the specified macro contains NetCloak SHOW or HIDE commands, the show/hide state (or "mode") of text following the MACRO command is not affected by the final mode of the macro. In other words, the mode of a MACRO command is not propagated back to the calling page.
When processing a page, NetCloak also does not process MACRO commands that are hidden by a previous HIDE command.
A trivial example will help explain this. Consider the following macro, defined in the NetCloak.macros file:
<BEGIN_MACRO TurnOn>
<SHOW>
<END_MACRO>
This macro does nothing when used in a cloaked page:
<HIDE>
This text is hidden from all users all the time.
<MACRO TurnOn>
This text is ALSO always hidden! In fact, NetCloak won't even call the macro.
<SHOW>
If you want a macro to affect the mode of the calling page, use the MODEMACRO command (see below) instead.
MODEMACRO behaves identically to the MACRO command, except for two important differences:
Using the same example TurnOn macro defined above, the following code works as expected:
<HIDE>
This text is hidden from all users all the time.
<MODEMACRO TurnOn>
This text is shown to all users.
The BEGIN_MACRO command is used in the NetCloak.macros file to define the start of a macro. Outside of the NetCloak.macros file it will have no effect.
The END_MACRO command is used in the NetCloak.macros file to define the end of a macro. Outside of the NetCloak.macros file it will have no effect.
See the "Macros" section in the User's Guide for more information on defining and using macros.
| Copyright © 1996-2000 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |