NetForms 2.5 User's Guide

Supplemental Directives


There are eight Supplemental Directives and nine Insertion Commands available for use in an FDML document. Both of these types of commands are used to augment the functionality of the four Primary Directives of NetForms.

Supplemental Directives are put at the very beginning of an FDML document, typically before the Primary Directive, and allow you to specify operations to be performed by NetForms in addition to that specified by the Primary Directive.

Insertion Commands (described in the next section) are used to place the contents of fields (entered by the author, or generated by the system) into the text of the finished HTML page, e-mail message, or ASCII text file.

Within each FDML document you may use each Supplemental Directive only once, but Insertion Commands may be used repeatedly.

The NetForms Supplemental Directives currently available will allow you to:

AUTOLINKAutomatically replace text entered into articles with text you specify
CHAINConnect more FDML documents to process data from the same form
COPYSave a second copy of an article
MENUDOCAutomatically insert a link to a new article or other text into an existing document
RECENTLISTAdd the new article to an internal list of recently submitted articles
RESPONSESend a customized response file to the user after the form data is processed
VERIFYVerify that specified fields in the form are not empty
RETURN_PAGESend a customized response file and abort form processing (used with the IF command).


<AUTOLINK> - Replace text entered into articles

Syntax:

    <AUTOLINK>"Filename"</AUTOLINK>

One of the most popular features of NetForms is AUTOLINK. The AUTOLINK directive allows you to specify a file that will be used to automatically insert hypertext links into new articles and inserted text. The filename may be specified as a full path from the web server root folder, or as a relative path from the FDML file, depending on your NetForms configuration.

AUTOLINK is not limited to just building hypertext links. It can also be used to replace any sequence of characters found in a page or e-mail message. This is handy for censoring foul language within submitted text, for instance.

The AutoLink file specified is a simple text file which lists the links to be generated. This will be explained in detail in the section "Creating an AutoLink File".

Since the AUTOLINK directive can appear in each FDML file, you may specify a different AutoLink file for each form, if you wish.


<CHAIN> - Process the same entry with another FDML

Syntax:

    <CHAIN>"Filename"</CHAIN>

The CHAIN directive is used within any FDML document, and allows you to specify additional FDML documents to be processed using the same input form data. In other words, if you would like for a single form submission to generate two or results, you can chain two FDML documents together. For example, you may want to have NetForms create a new Web page, and then have an e-mail message with the text of the new page e-mailed to the Webmaster for content verification. You may chain as many FDML documents as you wish.

The filename may be specified as a full path from the web server root folder, or as a relative path from the FDML file, depending on your NetForms configuration.


<COPY> - Save a second copy of an article

Syntax:

    <COPY>"Filename"</COPY>

The COPY directive is used to save a second copy of an article file created by the CREATEDOC directive. The filename is specified exactly as it is in the <CREATEDOC> directive described above.


<MENUDOC> - Link to a new article from an existing document

Syntax:

    <MENUDOC "MarkerText">"Filename" LinkText</MENUDOC>

Once you have created an article, you'll probably want to have the article included on an HTML page with a list of links to all the articles available for browsing. With MENUDOC, you specify the HTML page to which you want the link added, complete with the HTML text for building the link. "Menu documents" may be up to 96K in size. The MarkerText is optional. A simple MENUDOC example follows:

    <MENUDOC>"/Recipes/RecipesMenu.html" <LI> <A HREF="<HTMLFILENAME>"><REPLACE RecipeName></A></MENUDOC>

The <LI> tag will be added to an unordered list within the file "RecipesMenu.html", which will become the list of articles.

By default, NetForms inserts the link text just after every unordered list (<UL>) tag in the specified menu file. If there is more than one list in the menu document, the link will be added to all lists. The link is added to the top of the list, so that the most recent articles will be displayed first.

If you wish to maintain a menu page with multiple unordered lists of different items, or to insert the menu item into some structure other than an unordered list, you may specify the place within the menu page for the new link to be added. To use this feature, you will need to add text to your menu document at the point where you would like new links to be inserted. While the marker text may consist of anything, it is most useful to use an HTML comment, so that the marker text does not appear in the browser. Then, you add the text marking the insertion point to the opening <MENUDOC> tag in your FDML file. For example, if your menu document contained the comment "<!--INSERT_LINK_HERE-->", then the MENUDOC directive would be:

    <MENUDOC "<!--INSERT_LINK_HERE-->"> ... </MENUDOC>

Finally, if you would prefer that links to articles in your menu document be added to the bottom of the list instead of the top, add an asterisk to the MENUDOC command, like this:

    <MENUDOC* ...> ... </MENUDOC>

The articles will then appear in chronological order (oldest first) instead of reverse-chronological order (newest firstŠ the default)


<RECENTLIST> - Add to the list of recently submitted articles

Syntax:

    <RECENTLIST ListID>LinkText</RECENTLIST>

NetForms will automatically maintain a "Recent List" that allows users to retrieve a list of articles that have been recently added to your server. This command is very much like the MENUDOC directive, except that you do not need to specify a file name to be updated since the article list is maintained internally, and the web page displaying this list is built on-the-fly by NetForms. For example, to keep a list of recently added recipes, you might use the following example:

    <RECENTLIST> <LI><A HREF="<HTMLFILENAME>"><REPLACE RecipeName></A> </RECENTLIST>

The RECENTLIST directive adds the link to an internal list, which will be automatically time-stamped. When users ask for the recent articles, the internal list is searched and the appropriate links are returned. Up to 256 links can be stored in the internal list. (More that 256 links would be confusing, and the user would be better off just using the normal menus that are maintained by MENUDOC).

NetForms maintains up to 26 such internal lists, each named by a letter of the alphabet. You specify which list to add the document to in the "ListID" parameter of the <RECENTLIST> tag, like this:

    <RECENTLIST B><LI><A HREF="<HTMLFILENAME>"><REPLACE RecipeName></A></RECENTLIST>

The "ListID" parameter is optional. If no list is specified, the first list (list "A") is assumed.

For more information on creating and accessing multiple Recent Article lists, see the section entitled "Creating & Accessing Recent Article Lists" later in this Guide.


<RESPONSE> - Send an html file to the user after processing

Syntax:

    <RESPONSE>"Filename"</RESPONSE>

The RESPONSE directive allows you to specify an HTML document that will be returned to the author after they have submitted an article using NetForms. An example follows:

    <RESPONSE>"/Feedback/Response.html"</RESPONSE>

Note that a filename, not an URL, is specified in the RESPONSE directive.

If you don't use RESPONSE to specify a file, a very simple default "Thank You" response will be sent back to the author. See "Creating a Response File" for more details.


<VERIFY> - Verify that specified fields have been filled out

Syntax:

    <VERIFY FieldList>"Filename"</VERIFY>

Unlike all other supplemental directives, you may use as many VERIFY directives as you like within a single FDML file. Like other directives, VERIFY is best used at the top of the FDML file, in a block of directives.

VERIFY allows you to check one or more input fields to make sure the user entered data into the field(s). If one or more of the fields were left blank by the user, NetForms will not process the form and instead display the specified "error" response page, as in the following example:

    <VERIFY Email UserName Message>"/Folder/IncompleteForm.html"</VERIFY>

You may specify as many fields as you like within the <VERIFY> tag, and each will be checked. If any of the fields are blank, the file specified will be returned and the form will not be processed.

Note: For more extensive error detection and field validation, use the RETURN_PAGE directive along with the IF command.


<RETURN_PAGE> - Send an error page to the user and abort processing

Syntax:

    <RETURN_PAGE>"Filename"</RETURN_PAGE>

The RETURN_PAGE directive works like the RESPONSE directive, with one important difference. As with the RESPONSE directive, the command specifies a page to be returned to the user in the "Filename" parameter. However, RETURN_PAGE causes NetForms to abort all processing of the input form data and simply return the specified page.

There are two cases where RETURN_PAGE can be used.

The first is when all you want to do in response to a form submission is return a page of data. In this case, you can create an FDML file containing nothing but the RETURN_PAGE directive specifying the document to be returned. This might be useful in a simple FAQ document retrieval system, for example, like this:

    <RETURN_PAGE>"/FAQs/<REPLACE FAQNumber>.html"</RETURN_PAGE>

The second case, which is far more common, is when you need to perform some kind of input validation on the form data. You then use RETURN_PAGE in combination with the IF command so that an error page is returned when some condition, specified in the IF command, is met. When the condition is not met, the IF command essentially removes the RETURN_PAGE directive from the FDML file, and the primary directive is then allowed to perform its task. Here is a common example of this usage of the RETURN_PAGE directive:

    <IF EmailAddress #CONTAINS "@" THEN
        "<RETURN_PAGE>""InvalidEmail.html""</RETURN_PAGE>">

This FDML snippet tells NetForms "If the form field named 'EmailAddress' does not contain an '@' character, then abort processing and return the page named 'InvalidEmail.html' instead."


[ Previous | Table Of Contents | Next ]

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