Version 3.0 Pro User's Guide
Insertion Commands	Previous | Next Contents

Each of these commands is discussed in detail in the sections that follow.

<REPLACE>

    <REPLACE VarName>    <REPLACE_FN VarName>    <REPLACE_RAW VarName>    <REPLACE_URL VarName> 

REPLACE inserts the contents of the form field variable, global variable, cookie, or counter named "VarName". In the case of text entry form fields, this will be the text entered by the user. In the case of radio buttons, checkboxes and other fields which allow the user to select from pre-defined options, it will be the value specified for the field that the user selected.

When NetCloak Pro inserts the variable value, it will replace single line breaks with <BR> or pairs of line breaks with <P> tags. If the "Convert Brackets" configuration setting is enabled, NetCloak Pro will also convert angle bracket characters in the value ("<" and ">") to equivalent HTML entities ("<" and ">" respectively).

The three extensions to the standard REPLACE command modify the format of the data when it is inserted.

The REPLACE_FN command will remove or convert characters that are not allowed in file or folder names. This extension must be used within the "Filename" parameter in any NetCloak Pro directive so that legal folder and file names will be created. For example, a recipe system might start like this:

    <CREATEDOC>    "/Recipes/<REPLACE_FN RecipeName>.html"    </CREATEDOC>

In this example, a new HTML page will be created in the "Recipes" folder and will be named with the title of the recipe the author entered into the submitted form.

The REPLACE_FN command is very strict about the characters it inserts. The only characters that will be inserted will be upper and lower case alphabetic characters, numbers, underscores ("_"), periods ("."), and dashes ("-"). Colons (":") and slashes ("/") entered into the field will be converted to periods. All other characters will be removed. This is to ensure that the result will be both a legal Macintosh file name and a valid URL.

In cases where you would like to insert variable values without any conversion at all by NetCloak Pro, the REPLACE_RAW command is available. For example, if you don't want NetCloak Pro to insert line breaks ("<BR>") and paragraph marks ("<P>") into a given value, you can use the REPLACE_RAW command.

Finally, if you want to insert a variable value into a URL, say when building a link to a database query document or a search page, use the REPLACE_URL extension. Using REPLACE_URL will "URL-encode" the value before inserting it. URL-encoding converts any non-alphanumeric character in the data to a three-character sequence of the form "%XX", where "XX" is the hexadecimal equivalent ASCII value of the character. This is the format used when a web browser sends form data to a web server in an HTTP GET request. See the "MetaSearch" demo for an example usage of REPLACE_URL.

<BULLET>

    <BULLET VarName>

The BULLET command will create a bullet list from the contents of the specified NetCloak form variable, global variable, cookie, or counter, complete with <UL> and </UL> HTML tags. Each line of the specified variable separated by a return character becomes a bullet point. The command...

    <H3>Ingredients -</H3>
    <BULLET Ingredients>

...would place the ingredients entered into an unordered list. This command is almost always used to process a scrolling text field, but any field type is supported.

<UNIQUE>

    <UNIQUE>

The UNIQUE command will insert a string of up to six alphanumeric characters that is guaranteed to be unique each time the FDML containing the command is used to process a form. The text is safe for use in filenames and URLs. This can be used to guarantee a unique filename for created documents, or to generate a unique identifier for each record in a TEXTSTORE file.

<IF>

    <IF VarName operator "Value" THEN "TrueText" ELSE "FalseText">

The IF command compares the value of a form variable, global variable, cookie, or counter to a constant value, and inserts a specified string of text into the page if the comparison evaluates TRUE, and inserts another (optional) string of text if the comparison evaluates FALSE. This allows you to insert different text, and even execute different commands, based on the contents of a field.

After the name of the variable to be tested comes one of the NetCloak comparison operators, which determines how the variable value will be compared to the constant. The supported operators are documented in the NetCloak Standard User's Guide, under "Comparison Operators" in the section "General Rules of NetCloak Syntax". The list of operators supported is shown below:

The comparison operator is optional. If it is not present, then an "IS" text comparison is performed, requiring an exact match between the named form field value and the text parameter.

As in NetCloak HTML commands, you can combine the comparison operator with a '#' character to negate the result of the comparison.

Note: For backward compatibility with NetForms, the '=' text operator is still supported, operating identically to the IS operator. The IS operator is preferred.

The keywords THEN and ELSE must be used. However, they do not have to be upper case. Uppercase is recommended because it enhances the readability of the command.

To check to see if a field was left blank by the author, use the EXISTS operator, or use the IS operator with an empty pair of double-quotes. For example, a common <IF> usage is:

    <IF MyTextField IS "" THEN "Sorry, no text entered in this text field.">

You may use any FDML directive or command within either replacement string.

Unlike NetCloak commands, the FDML IF command requires double-quote characters around the text values following the comparison operator.

If you need to use a double-quote (") within the text value, the THEN clause, or the ELSE clause, then use two double-quotes ("") in the text of the parameter. For example, the <IF> statement above could have read:

    <IF MyTextField IS "" THEN "Sorry, no text entered in ""MyTextField"".">

If MyTextField were left blank, the inserted text would be:

    Sorry, no text entered in "MyTextField".

The double-quote pair can also be used in the comparison constant.

The IF command can accept multiple conditional statements using "AND" and "OR" conjunctions. For example:

    <IF Name IS "John" AND EMail CONTAINS "@" THEN 
        "John entered his e-mail address."    >

You can also use "OR", as in:

    <IF Name IS "John" OR Name IS "Bob" OR Name IS "Bill" THEN
        "Hi <REPLACE Name>!"    >

The IF command also supports an ELSE clause. If the condition is true, the first replacement string will be used. If the condition is false, the second replacement string, following the ELSE, will be used. For example:

    <IF Name IS "John" OR Name IS "Bob" OR Name IS "Bill" THEN
        "Hi <REPLACE Name>!" 
    ELSE 
        "Sorry, <REPLACE Name>, I don't know you..."    >

The IF command above will replace the value of the field "Name" if it contains either John, Bob, or Bill. Otherwise, it will insert "I don't know you...".

Note, finally, that there is usually more than one correct way to compare field values using an IF command. For instance, the example given above, using 'IS' and 'OR' operators, could be rewritten using the 'IN' operator, like this:

    <IF Name IN "John,Bob,Bill" THEN
        "Hi <REPLACE Name>!" 
    ELSE
        "Sorry, <REPLACE Name>, I don't know you..."    >

    <DATE>    <DATE_FN>    <DATE_URL>

The DATE command inserts the system date of the machine running NetCloak Pro into the text, in the "short date" format specified in the Date & Time control panel. You might use this to date when your articles are posted, for example:

    This article was submitted on <DATE>.

If you want to use the DATE command as part of a "Filename" parameter in other FDML directives, use the extension <DATE_FN>. For example:

    <COPY>"/FolderName/<REPLACE_FN TitleName><DATE_FN>.html"</COPY>

The above insertion would provide a date-stamped title to each article submitted. NetCloak Pro will replace the slashes normally found in the date into periods so that they are not misinterpreted by the server as path delimiters.

Use the <DATE_URL> extension to URL-encode the current date before it is inserted, as you would need to do when inserting the date into a hypertext link URL. See the REPLACE command for a description of URL-encoding.

<YEAR>

    <YEAR>

The YEAR command inserts the current year, according to the system date, into the text, including the century digits.

<MONTH>

    <MONTH>    <MONTH#>    <MONTH_FN>    <MONTH_URL>

The MONTH command inserts the current month name, according to the system date, into the text. The month name is given in the language set in the Date & Time control panel.

The MONTH# extension merely inserts the value (1-12) corresponding to the current month instead of the month name.

Because in some languages, month names contain non-alphanumeric characters, you can use the MONTH_FN extension to include the month name in "Filename" parameters in other FDML directives. Similarly, you can use the MONTH_URL extension to insert an URL-encoded month name into URL text. See the REPLACE command for a description of URL-encoding.

<DAY>

    <DAY>

The DAY command inserts the value for the day of the month into the text. This value ranges from 1 to 31.

<WEEKDAY>

    <WEEKDAY>    <WEEKDAY#>    <WEEKDAY_FN>    <WEEKDAY_URL>

The WEEKDAY command inserts the current day of the week, according to the system date, into the text. The name of the day is given in the language set in the Date & Time control panel.

The WEEKDAY # extension merely inserts the value (1-7) corresponding to the weekday instead of the name of the day.

Because in some languages, weekday names contain non-alphanumeric characters, you can use the WEEKDAY_FN extension to include the month name in "Filename" parameters in other FDML directives. Similarly, you can use the WEEKDAY_URL extension to insert an URL-encoded weekday name into URL text. See the REPLACE command for a description of URL-encoding.

<TIME>

    <TIME>    <TIME_FN>    <TIME_URL>

The TIME command inserts the current time of the Web server running NetCloak Pro in the same way the date is inserted using the DATE command.

If you want to use the TIME command in a "Filename" parameter in other FDML directives, use the extension TIME_FN (where "FN" stands for " File Name"). This command will replace the colons normally found in the expression of time into periods so that they are not misinterpreted by the server.

Similarly, if you want to use the current time in a URL embedded in the text, use the TIME_URL command. See the REPLACE command for a description of URL-encoding.

You would implement this command in the same way as DATE above.

<HOUR>

    <HOUR>

The HOUR command inserts the hours value of the current time into the text. This value ranges from 00 to 23.

<MINUTE>

    <MINUTE>

The MINUTE command inserts the minutes value of the current time into the text. This value ranges from 00 to 59.

<SECOND>

    <SECOND>

The SECOND command inserts the seconds value of the current time into the text. This value ranges from 00 to 59.

<HTMLFILENAME>

    <HTMLFILENAME>

The HTMLFILENAME command is used to specify the path and filename of a newly created HTML article so that links can be created to it. It works properly with the CREATEDOC and INSERTFILE primary directives.

Used in the text of a response file, you can allow authors to review their finished articles. In the MENUDOC directive, HTMLFILENAME is especially useful to provide a link to the new article. Simply place the HTML link command...

    <A HREF="<HTMLFILENAME>">

...in the link text parameter of the MENUDOC command. In a response page, you could use the following command to allow users to see their finished article:

    <A HREF="<HTMLFILENAME>">Review Your Article</A>

    <MENUFILENAME>

The MENUFILENAME command is used to specify insertion of a URL to the menu document of a newly created article. In most cases, this command is used to provide a hypertext link back to the new article's menu. Obviously, this command can only be used when a MENUDOC directive has been specified.

<LINKPREVIOUS>

    <LINKPREVIOUS>

The LINKPREVIOUS command allows you to add a hypertext link between the document currently being processed and the last document that was added to the same menu (in the MENUDOC directive) of an HTML page. Users can navigate between articles that are on the same menu without having to constantly be moving back and forth between the menu document and the individual articles. Simply insert the command into the text template of your FDML file, like this:

    <LINKPREVIOUS>

By default, the hypertext link will be labeled with the text, "Previous Article". You can change this phrase to anything you like in the NetCloak Pro configuration settings, or using a SET_NETCLOAK command in your FDML file.

<LINKNEXT>

    <LINKNEXT>

The LINKNEXT command is identical in its implementation to the LINKPREVIOUS command except that the hypertext link inserted is labeled "Next Article" by default, and when the next article is submitted, NetCloak Pro automatically adds a link to the new document in place of "Next Article". As with LINKPREVIOUS, the phrase used in the hypertext link can be customized in the NetCloak Pro configuration settings, or with a SET_NETCLOAK command.

<VARIABLE_LIST>

    <VARIABLE_LIST>    HTML<VARNAME>HTML<VARVALUE>HTML
    </VARIABLE_LIST>

This command behaves the same way in an FDML file that it does in cloaked HTML pages - it repeats the text in between the <VARIABLE_LIST> and </VARIABLE_LIST> tags once per each form field variable defined in the current form submission. Within this repeating text, each occurrence of the tag <VARNAME> is replaced with the variable name, and each occurrence of the tag <VARVALUE> is replaced with the corresponding variable value. For more information, see the "Commands: Utility" section of the NetCloak Standard User's Guide.

<REPLACE_OFF>
<REPLACE_ON>

    <REPLACE_OFF>    <REPLACE_ON>

Sometimes, you may not want FDML insertion commands in an FDML file to be processed immediately. This most often occurs when you want to use an FDML file to actually create another FDML file.

In these cases, you can use the special commands <REPLACE_OFF> to tell NetCloak Pro to not process FDML insertion commands (including REPLACE, IF, BULLET, VARIABLE_LIST, date/time commands, etc.) until the next <REPLACE_ON> command is encountered in the FDML file.

These commands also come in handy with the VARIABLE_LIST command, since it is supported in both cloaked pages and in FDML file templates. To avoid replacing the VARIABLE_LIST tags when the FDML processes the form, you could do this, for instance:

    <PRE>    <REPLACE_OFF>    <VARIABLE_LIST>    <B><VARNAME>:</B> <VARVALUE>    </VARIABLE_LIST>    <REPLACE_ON>    </PRE>

Using Multiple Instances of a Field

    <REPLACE MyOptions[1]><BR>    <REPLACE MyOptions[2]><BR>    <REPLACE MyOptions[3]><BR>

The square brackets are used to specify the number of the instance to be used. If the brackets are left off and only the variable name is given, then the first instance is used. The IF command can be used to test to see if a particular instance exists. For example, to include "Option:" before each selected item in the example above, you could use...

    <IF MyOptions IS "" THEN "No Options Selected!<BR>">    <IF MyOptions[1] IS# "" THEN "Option: <REPLACE MyOptions[1]><BR>">    <IF MyOptions[2] IS# "" THEN "Option: <REPLACE MyOptions[2]><BR>">    <IF MyOptions[3] IS# "" THEN "Option: <REPLACE MyOptions[3]><BR>">    <IF MyOptions[4] IS# "" THEN "More than 3 options selected!<BR>">

Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/	Previous | Next Contents