Reference Guide
Syntax Reference
Contents
|
Version 3.1 Reference Guide |
Syntax Reference |
Previous |
Next Contents |
All NetCloak dynamic page commands follow the same rules of syntax. Like HTML tags, every command must begin with an open angle-bracket (<), followed immediately by the command name. The command name is not case-sensitive, but it is conventional to use uppercase to make the NetCloak commands more recognizable. The examples here and in the User's Guide show commands in all upper case.
Following the command name may be one or more parameters and a closing angle-bracket (>). While the parameters may be optional, the closing bracket is required.
SHOW and HIDE commands have the command name followed by a comparison and comparison constants. Together they look like this:
<SHOW_DAY BEGINS SAT>
The command above, when described in English, means "show if the current day begins with SAT". BEGINS is the comparison operator, and SAT is a parameter.
Most SHOW and HIDE commands will accept multiple parameters in a series, and show or hide if any of them are matched. For example, the SHOW_DAY command accepts a day name as a parameter and so allows multiple days to be specified, as in:
<SHOW_DAY BEGINS SAT SUN>
This will show text on either Saturday or Sunday.
All NetCloak SHOW and HIDE commands let you specify one of thirteen comparison operators, which let you specify exactly how to compare a NetCloak variable to the parameters listed in the command.
A comparison operator causes NetCloak to perform a logical test, which has either a true or false result. If the result is true, then a SHOW command causes text following it to be shown; and a HIDE command causes the text to be hidden. If the result of the test is false, then the command has no effect on the page.
The comparison operator may be omitted from the command. If it is, a default comparison operator is used which is specific to each command. The default comparison operator for each command is listed in the command's description later in this User's Guide. In all cases, the default comparison operator permits backward-compatibility with versions of NetCloak prior to 3.0.
Comparison operators fall into one of two categories: text comparisons and numeric comparisons. Be sure you know which kind of operator you are using, or you will get unexpected results in your web pages.
Text comparison operators treat the variable and the command parameters as sequences of alphabetic characters. All text comparisons are case-insensitive, which means that the capitalization of the characters is ignored. Therefore, bob and BoB are considered an exact match. The text operators, and the tests they perform, are listed below. For the examples shown below, assume the existence of a NetCloak global variable named Platform with the value Macintosh.
CONTAINS
The comparison is true if the NetCloak variable contains any of the given text parameters. For example, the following commands all will cause text to be hidden:
<HIDE_GLOBAL Platform CONTAINS
"mac">
<HIDE_GLOBAL Platform CONTAINS
"into">
<HIDE_GLOBAL Platform CONTAINS
"mAcInTosh">
IS (Text Equality)
The comparison is true if the NetCloak variable exactly matches any one of the given text parameters. Of the following three commands, only the last one will cause text to be hidden:
<HIDE_GLOBAL Platform IS "mac">
<HIDE_GLOBAL Platform IS "into">
<HIDE_GLOBAL
Platform IS "mAcInTosh">
IN
The comparison is true if any one of the given text parameters contains the value of the NetCloak variable. The following command would cause text to be hidden:
<HIDE_GLOBAL Platform IN "Welcome to Macintosh.">
BEGINS (Begins With)
The comparison is true if the NetCloak variable begins with the exact same sequence of characters as any one of the text parameters, including whitespace characters (spaces, tabs, and returns). Of the following three commands, only the first one will cause text to be hidden:
<HIDE_GLOBAL Platform BEGINS
"mac">
<HIDE_GLOBAL Platform BEGINS
"into">
<HIDE_GLOBAL Platform BEGINS "Macintosh
">
The third example fails the test because the text parameter contains extra space characters.
ENDS (Ends With)
The comparison is true if the NetCloak variable ends with the exact same sequence of characters as any one of the text parameters, including whitespace characters (spaces, tabs, and returns). Of the following three commands, only the first one will cause text to be hidden:
<HIDE_GLOBAL Platform ENDS "tosh">
<HIDE_GLOBAL Platform ENDS "into">
<HIDE_GLOBAL
Platform ENDS " Macintosh">
The third example fails the test because the text parameter contains extra space characters.
BEFORE (Alphabetically)
This operator uses the ASCII value for each character in the text to determine if the NetCloak variable would be sorted alphabetically before the text parameters. If multiple parameters are listed, this comparison returns true if the variable is alphabetically before any one of the parameters. For this reason, this operator should ordinarily be used with only a single text parameter.
Using ASCII values, whitespace characters sort before digit characters, and digit characters sort before all alphabetic characters. Also, if all characters in a short word match a longer word, the shorter word sorts before the longer word.
Note: the BEFORE operator is not a date/time comparison operator. You usually do not want to use this operator in date/time commands.
Of the following examples, only the second one will cause text to be hidden using our "Platform" global variable:
<HIDE_GLOBAL Platform BEFORE
"mac">
<HIDE_GLOBAL Platform BEFORE
"windows">
<HIDE_GLOBAL Platform BEFORE
"123xyz">
AFTER (Alphabetically)
This operator uses the ASCII value for each character in the text to determine if the NetCloak variable would be sorted alphabetically after the text parameters. If multiple parameters are listed, this comparison returns true if the variable is alphabetically after any one of the parameters. For this reason, this operator should ordinarily be used with only a single text parameter.
Using ASCII values, whitespace characters sort before digit characters, and digit characters sort before all alphabetic characters. Also, if all characters in a short word match a longer word, the shorter word sorts before the longer word.
Note: the AFTER operator is not a date/time comparison operator. You usually do not want to use this operator in date/time commands.
Of the following examples, only the third one will cause text to be hidden using our "Platform" global variable:
<HIDE_GLOBAL Platform AFTER
"Macintosh">
<HIDE_GLOBAL Platform AFTER
"windows">
<HIDE_GLOBAL Platform AFTER
"123xyz">
EXISTS
This comparison doesn't really compare the NetCloak variable to anything; it always evaluates true if the variable has been defined to have any value. In fact, if this comparison operator is used, the text parameters following it are completely ignored. This comparison operator comes in handy when you want to make sure you do not overwrite a variable's value once it has already been set, such as is often the case when setting cookie values (see the SET_COOKIE command) or global variable values. For example, if the global variable named "Platform" does not already exist, the following code sets its value; otherwise, it leaves it alone:
<HIDE_GLOBAL Platform EXISTS>
<SET_GLOBAL
Platform = "Macintosh">
<SHOW>
Numeric comparison operators treat the variable and the command parameters as numbers, converting text parameters to numbers as necessary. Numeric values may only contain these characters:
A variable that contains other characters will be treated as text by NetCloak, and will be converted to the number zero for a numeric comparison.
In date and time commands, the date and time parameters are converted to a single number in seconds. This allows comparisons and other operations in date commands to work just like those for plain numbers.
The numeric operators, and the tests they perform, are listed below. For the examples below, assume the existence of a counter named Orders with a value of 250.
== (Numeric Equality)
The comparison is true if the NetCloak variable has a value that is exactly equal to any of the listed numeric values. For example, the following command will cause text to be hidden:
<HIDE_COUNT Orders == 50 150 250 350>
LT (Less Than)
The comparison is true if the value of the NetCloak variable is less than any of the listed numeric values. In the following examples, the third one will cause text to be hidden:
<HIDE_COUNT Orders LT 50>
<HIDE_COUNT
Orders LT 250>
<HIDE_COUNT Orders LT 500>
LT= (Less Than or Equal)
The comparison is true if the value of the NetCloak variable is less than or equal to any of the listed numeric values. In the following examples, the second and the third one will cause text to be hidden:
<HIDE_COUNT Orders LT= 50>
<HIDE_COUNT
Orders LT= 250>
<HIDE_COUNT Orders LT= 500>
GT (Greater Than)
The comparison is true if the value of the NetCloak variable is greater than any of the listed numeric values. In the following examples, the first one will cause text to be hidden:
<HIDE_COUNT Orders GT 50>
<HIDE_COUNT
Orders GT 250>
<HIDE_COUNT Orders GT 500>
GT= (Greater Than or Equal)
The comparison is true if the value of the NetCloak variable is greater than or equal to any of the listed numeric values. In the following examples, the first one and the second one will cause text to be hidden:
<HIDE_COUNT Orders GT= 50>
<HIDE_COUNT
Orders GT= 250>
<HIDE_COUNT Orders GT= 500>
Comparison operators in NetCloak SHOW and HIDE commands can be negated by inserting a # character in the command immediately before or after the comparison operator. This character reverses the result of the comparison, so that the HIDE or SHOW occurs if the test is NOT true. Some examples will make this clear.
<HIDE_CLIENT #CONTAINS "AOL">
Welcome America Online users!
<SHOW>
This command shows a special message only to America Online users by hiding the text if the client name does not contain the text AOL. Read the command like this: "Hide if the client does NOT contain AOL".
You can put the # character either at the end of the show or hide command, or either before or after the comparison operator. All of the commands below are equivalent:
<HIDE_CLIENT# CONTAINS "Mozilla">
<HIDE_CLIENT #CONTAINS "Mozilla">
<HIDE_CLIENT
CONTAINS# "Mozilla">
Here is one more example:
<HIDE_VARIABLE OSPreference IS#
"MacOS">
You have selected MacOS as your preferred
operating system. Congratulations!
<SHOW>
This code hides the congratulatory message from users who have chosen some other OS. (The command reads "Hide if the form variable OSPreference is not MacOS".)
The negation operator can also be used with the default comparison by adding it directly to a HIDE or SHOW command. For example:
<HIDE><SHOW_DAY# SAT SUN>.
INSERT commands have the command name followed by one or more parameters. For example:
<INSERT_COOKIE moof>
This will insert the value of the cookie named moof. Parameters such as a name are common, but the exact parameters are appropriate for each command.
In contrast to show and hide commands, insert commands which accept more than one parameter only allow one of each. The parameters are recognized by the order in which they appear, so ordering must always be closely followed.
Some parameters may be optional. You may leave them out if you don't need what they do. For example, the INSERT_DATE command allows an optional offset and an optional format parameter. The command may be used without any parameters, or with only an offset parameter: If multiple parameters are used, they must be included in order:
<INSERT_DATE +24 SHORT>
<INSERT_DATE
SHORT +24>
Of the two commands above, only the first will work correctly because the parameters are in the correct order.
Now the INSERT_DATE command will allow either the format or the offset by itself. In some commands, though, to use the second or later parameters all of the preceding parameters must be specified.
An example is the INSERT_COUNTDOWN command, which accepts the date you would like to count down to as the first parameter, and then the label for the weeks, days, hours, and minutes values. If you intended to use INSERT_COUNTDOWN with a different label for the days value, you might try using:
<INSERT_COUNTDOWN_D 1/1/00 "x24 hours">
This would not work as intended. NetCloak will interpret x24 hours as the label for weeks, instead of days because the parameters are only interpreted in order. To use the second or later parameter in a command without specifying the preceding parameters, use a pair of quotation marks as a placeholder. The correct command for the previous INSERT_COUNTDOWN example would be:
<INSERT_COUNTDOWN_D 1/1/00 "" "x24 hours">
The Commands section specifies the order of the parameters, whether the order is required and which parameters are optional for each command.
Many NetCloak commands allow you to specify an asterisk in place of a single character in a parameter, where the asterisk will match any character. This is commonly known as a wildcard.
For example, the following command will display the line following it to any 3.x version of a browser:
<HIDE><SHOW_CLIENT CONTAINS
"3.*">
Please upgrade to version 4 of your browser.
INSERT commands do not allow wildcards. In most cases, a wildcard would not make sense for these commands. Wildcards are similarly disallowed in SHOW and HIDE commands which take numbers as a parameter, including COUNT, RANDOM and SAMERAND commands, or commands which take a date or a time as a parameter. The MACRO and EXEC_CGI commands do not allow wildcards in any of their parameters.
Variable commands (SHOW and HIDE LOCAL, GLOBAL or VARIABLE) will accept wildcards in parameters, however, you must use them carefully because an asterisk is used as the multiplication operator in SET_VARIABLE commands. Enclosing parameters in quotation marks make the commands easier to read.
<SET_VARIABLE myVar "bob">
<HIDE><SHOW_VARIABLE myVar IS "b*b">
This will
be shown.
This example will show the text following if the value of the variable is bob, bib or any other three letter combination starting and ending with b. Wildcards do not work in variable values, however.
<SET_VARIABLE myVar "b*b">
<HIDE><SHOW_VARIABLE myVar IS "bob">
This will
not be shown!
The example above will not show the text even though the wildcard in b*b should match bob.
Parameters within NetCloak commands are separated by one or more spaces, tab characters or line breaks (collectively known as "whitespace" characters). For example, the following command contains four parameters after the command name -- Country, CONTAINS, USA, and Canada:
<HIDE_GLOBAL Country CONTAINS USA Canada>
If you omit a space between parameters, the meaning of the command changes, and you will get unexpected results. For example, the following command only contains three parameters (Country, CONTAINS, and USACanada), and thus behaves differently:
<HIDE_GLOBAL Country CONTAINS USACanada>
You may use any combination of whitespace characters between command parameters to improve readability of the HTML source code. For example, the following two commands are treated exactly the same by NetCloak:
<SET_VARIABLE Total = Item1Total + Item2Total + Item3Total + Item4Total + Item5Total + Shipping + Tax>
<SET_VARIABLE
Total
=
Item1Total +
Item2Total +
Item3Total +
Item4Total
+
Item5Total +
Shipping +
Tax
>
In most cases, parameters can be placed in quotes, but quotes are not required. For example:
<SHOW_CLIENT CONTAINS "mozilla">
is functionally equivalent to:
<SHOW_CLIENT CONTAINS mozilla>
Using quotes, however, allows you to include spaces within a parameter. For example:
<SHOW_CLIENT CONTAINS "mozilla 3.0">
is very different from:
<SHOW_CLIENT CONTAINS mozilla 3.0>
The first case looks for a client that contains mozilla 3.0, but the second will recognize either client names that contain mozilla or client names that contain 3.0. This is because the space between mozilla and 3.0 is interpreted by NetCloak as a delimiter between parameters instead of the space that appears in the browser name.
When a parameter is set inside quotes, you must use two double-quote characters to specify a quote, so that NetCloak does not interpret the quote character as the end of the parameter. For example:
<HIDE_VARIABLE SomeVar "He said ""moof""!">
This command would look for the string He said "moof"! , because NetCloak interprets the two double-quote marks as a quote instead of the end of the parameter.
Quotes may not be used around variable names. If a variable name is enclosed in quotes it will be interpreted as a text string and not a variable name. For example, if you have a local variable called TestVar that is set to the value Moof, you might do something like this:
<SET_LOCAL NewVar = "TestVar" &
" Says the Dogcow">
<INSERT_LOCAL NewVar>
This would display:
TestVar Says the Dogcow
What is really desired is this:
<SET_LOCAL NewVar = TestVar & " Says the
Dogcow">
<INSERT_LOCAL NewVar>
Resulting in:
Moof Says the Dogcow
In the first example TestVar is specified as a string and NetCloak inserts it accordingly. In the second, NetCloak recognizes that TestVar may be some other kind of entity, and evaluates it correctly.
| Copyright © 1996-2000 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |