NetCloak 3.1 Reference Guide rev. C: Forms Processing- Insertion Commands, Multiple Instances

Version 3.1
Reference Guide

Forms Processing Commands:

Insertion Commands, Using Multiple Instance Fields

Insertion Commands

Insertion commands are used to insert user-entered information into the body of the template contained in the FDML document. The commands used to insert text are as follows:

<REPLACE>

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

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 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 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 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, use the REPLACE_RAW command. This suppresses conversion of line breaks and angle brackets to their HTML equivalents normally done by the REPLACE 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 ASCII value of the character in hexadecimal. This is the format used when a web browser sends form data to a web server in an HTTP GET request.

<BULLET>

The BULLET command will create an HTML bullet list from the contents of the specified NetCloak form variable, global variable, cookie, or counter, complete with <UL> and </UL> 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 a bullet list; the resulting HTML might be something like this:

<H3>Ingredients -</H3>
<UL BULLET>
<LI>Malt
<LI>Barley
<LI>Hops
</UL>

And the HTML would be rendered like this in a browser:

Ingredients

Malt
Barley
Hops

This command is almost always used to process a scrolling text field, but any field type is supported.

<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.

Adding an asterisk to the command (UNIQUE*) will insert the same unique value set by a previous UNIQUE command. This is useful for re-using the unique value when producing links or other references to a new file whose name was created with UNIQUE.

The original unique value is preserved for an entire submission, so UNIQUE* can be used across multiple chained FDMLs and in the response page.

<IF>

<IF VarName comparisonValue THEN " TrueText " ELSE " FalseText

The IF command compares the value of a form variable, global variable, cookie, or counter to a constant value or another variable, 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 or 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 covered in detail in the section General Rules of NetCloak Syntax. The list of operators supported is shown below:

Number Comparisons
CONTAINS	== (Equals)
BEGINS (With)	LT (Less Than)
ENDS (With)	LT= (Less Than or Equal)
BEFORE (Alphabetic)	GT (Greater Than)
AFTER (Alphabetic)	GT= (Greater Than or Equal)
IS (Exact Match)	IN (List)

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 older versions, the '=' text operator is still supported, operating identically to the IS operator. The IS operator is preferred.

The next parameter is the comparison value. This can be a variable or field name, or a text string. Text strings should be enclosed in double-quotes or else NetCloak will attempt to interpret the text as a variable name first. If the comparison value is not enclosed in quotes and there is no variable with that name, NetCloak will use the specified value as text.

Comparison values can be form fields or NetCloak global or user variables. NetCloak will use variables in that order if there are field values, global variables or user variables with duplicate names.

The keywords THEN and, if used ELSE, are required. 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 two double-quotes with nothing between them . For example, a common IF usage is:

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 were left blank, the inserted text would be:

Clarus the dogcow said "Moof!"

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:

You can also use OR, as in:

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 frequently 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>

The DATE command inserts the system date of the machine running NetCloak 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 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>

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

The optional format parameter can be either LONG or SHORT, and defaults to LONG if no format is specified. If SHORT format is specified, the year will be returned as a two-digit number without the century.

<MONTH>

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. The optional format parameter can be either LONG or SHORT, and defaults to SHORT if no format is specified. If LONG format is specified, single-digit numbers will include a leading zero. The format parameter may be included in other forms of the command, but has no effect.

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>

The DAY command inserts the value for the day of the month into the text. This value ranges from 1 to 31. The optional format parameter can be either LONG or SHORT, and defaults to SHORT if no format is specified. If LONG format is specified, the day will include a leading zero for single-digit numbers.

<WEEKDAY>

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 of 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>

The TIME command inserts the current time of the web server running NetCloak 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.

See the DATE command for and example of using the _FN variation of the command.

<HOUR>

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

The optional format parameter can be either LONG or SHORT, and defaults to SHORT if no format is specified. If LONG format is specified, single-digit numbers will include a leading zero.

<MINUTE>

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

The optional format parameter can be either LONG or SHORT, and defaults to SHORT if no format is specified. If LONG format is specified, single-digit numbers will include a leading zero.

<SECOND>

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

The optional format parameter can be either LONG or SHORT, and defaults to SHORT if no format is specified. If LONG format is specified, single-digit numbers will include a leading zero.

<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 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 in the link text parameter of the MENUDOC command.

In a response page, you could use HTMLFILENAME command to allow users to see their finished article:

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

Note that if several FDMLs are chained together with the CHAIN directive, the value of HTMLFILENAME will only be valid within CREATEDOC FDMLs. If the last FDML in the chain uses CREATEDOC, HTMLFILENAME will also work in the response file.

<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>

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:

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 configuration settings, or using a SET_NETCLOAK command in your FDML file.

<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 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 configuration settings, or with a SET_NETCLOAK command.

<VARIABLE_LIST>

<VARIABLE_LIST>
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 opening and closing VARIABLE_LIST tags once for each form field 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 VARIABLE_LIST dynamic page command.

<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 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:

Using Multiple Instances of a Field

When a field name is used multiple times within the same HTML form (as in a series of checkboxes), you can access instances other than the first. For example, the first three items chosen from a group of checkboxes named MyOptions could be added to a page using...

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...


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

Forms Processing Commands:

Insertion Commands, Using Multiple Instance Fields

Insertion Commands

<REPLACE>

<BULLET>

<UNIQUE>

<IF>

<DATE>

<YEAR>

<MONTH>

<DAY>

<WEEKDAY>

<TIME>

<HOUR>

<MINUTE>

<SECOND>

<HTMLFILENAME>

<MENUFILENAME>

<LINKPREVIOUS>

<LINKNEXT>

<VARIABLE_LIST>

<REPLACE_OFF> <REPLACE_ON>

Using Multiple Instances of a Field

<REPLACE_OFF>
<REPLACE_ON>