NetForms 2.5 User's Guide

Insertion Commands


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

<REPLACE><DATE>
<BULLET><YEAR>
<UNIQUE><MONTH>
<IF><DAY>
<LINKPREVIOUS><WEEKDAY>
<LINKNEXT><TIME>
<HTMLFILENAME><HOUR>
<MENUFILENAME><MINUTE>
<SECOND>


<REPLACE>

Syntax:

    <REPLACE FieldName>
    <REPLACE_FN FieldName>
    <REPLACE_RAW FieldName>
    <REPLACE_URL FieldName>

REPLACE inserts the contents of the entry form field "FieldName". In the case of text entry 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 NetForms inserts the contents of a field, it will replace single line breaks with <BR> or pairs of line breaks with <P> tags. If the "Convert Brackets" option is selected in the Configuration window, NetForms will also convert angle bracket characters in the field ("<" 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 NetForms 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 user-entered fields without any conversion at all by NetForms, the REPLACE_RAW command is available. For example, if you don't want NetForms to insert line breaks ("<BR>") and paragraph marks ("<P>") into a given field, you can use the REPLACE_RAW command.

Finally, if you want to insert a field 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 field 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>

Syntax:

    <BULLET FieldName>

The BULLET command will create a bullet list from the contents of the specified field, complete with <UL> and </UL> HTML tags. Each line entered into the specified text field by the author and separated by a return key 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>

Syntax:

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

Syntax:

    <IF FieldName CONTAINS "Value" THEN "TrueText" ELSE "FalseText">
    <IF FieldName BEGINS "Value" THEN "TrueText" ELSE "FalseText">
    <IF FieldName ENDS "Value" THEN "TrueText" ELSE "FalseText">
    <IF FieldName IN "Value" THEN "TrueText" ELSE "FalseText">
    <IF FieldName = "Value" THEN "TrueText" ELSE "FalseText">

The IF command compares the value of a field to a constant, 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 field to be tested comes one of five different comparison "operators", which determines how the field value will be compared to the constant. The currently supported operators are:

CONTAINSEvaluates TRUE if the field contains the given constant.
BEGINSEvaluates TRUE if the field begins with the given constant.
ENDSEvaluates TRUE if the field ends with the given constant.
INEvaluates TRUE if the field value is contained in the given constant.
=Evaluates TRUE if the field exactly matches the given constant.

You may also use a hash mark character, "#", to negate the comparison:

#CONTAINSEvaluates TRUE if the field does NOT contain the given constant.
#BEGINSEvaluates TRUE if the field does NOT begin with the given constant.
#ENDSEvaluates TRUE if the field does NOT end with the given constant.
#INEvaluates TRUE if the field value is NOT contained in the given constant.
# or #=Evaluates TRUE if the field does NOT exactly match the given constant.

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 two double-quotes with nothing between them (""). For example, a common <IF> usage is:

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

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

If you need to use a double-quote (") within the text of your match, then put two double-quotes ("") in the text. For example, the <IF> statement above could have read:

    <IF MyTextField = "" 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 = "John" AND EMail CONTAINS "@" THEN 
        "John entered his e-mail address.">

You can also use "OR", as in:

    <IF Name = "John" OR Name = "Bob" OR Name = "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 = "John" OR Name = "Bob" OR Name = "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 '=' 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>

Syntax:

    <DATE>
    <DATE_FN>
    <DATE_URL>

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

Syntax:

    <YEAR>

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


<MONTH>

Syntax:

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

Syntax:

    <DAY>

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


<WEEKDAY>

Syntax:

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

Syntax:

    <TIME>
    <TIME_FN>
    <TIME_URL>

The TIME command inserts the current time of the Web server running NetForms 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 NetForms 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>

Syntax:

    <HOUR>

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


<MINUTE>

Syntax:

    <MINUTE>

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


<SECOND>

Syntax:

    <SECOND>

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


<HTMLFILENAME>

Syntax:

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

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>

Syntax:

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

Syntax:

    <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 NetForms configuration settings.


<LINKNEXT>

Syntax:

    <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, NetForms 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 NetForms configuration settings.


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

    <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 = "" THEN "No Options Selected!<BR>">
    <IF MyOptions[1] # "" THEN "Option: <REPLACE MyOptions[1]><BR>">
    <IF MyOptions[2] # "" THEN "Option: <REPLACE MyOptions[2]><BR>">
    <IF MyOptions[3] # "" THEN "Option: <REPLACE MyOptions[3]><BR>">
    <IF MyOptions[4] # "" THEN "More than 3 options selected!<BR>">


[ Previous | Table Of Contents | Next ]

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