Version 3.0 Pro User's Guide
Supplemental Directives	Previous | Next Contents

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 NetCloak Pro 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 NetCloak Pro Supplemental Directives currently available will allow you to:

    <AUTOLINK>"Filename"</AUTOLINK>

One of the most popular features of NetCloak Pro 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 NetCloak Pro 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

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

<COPY> Save a second copy of an article

    <COPY>"Filename"</COPY>

Requires: a CREATEDOC directive.

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, and the file created is otherwise identical to the document created by CREATEDOC.

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

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

Requires: a CREATEDOC directive

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. 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, NetCloak Pro 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

    <RECENTLIST ListID>    LinkText
    </RECENTLIST>

Requires: a CREATEDOC directive

NetCloak Pro 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 NetCloak Pro. 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).

NetCloak Pro 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> Return an HTML file after processing

    <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 NetCloak Pro. 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 fields have been filled out

    <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, NetCloak Pro 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> Return an error page & abort

    <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 NetCloak Pro 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 NetCloak Pro "If the form field named 'EmailAddress' does not contain an '@' character, then abort processing and return the page named 'InvalidEmail.html' instead."

Note that when the RETURN_PAGE directive is used in an IF command, the double-quote characters used to delimit the file path must be "doubled" to prevent NetCloak from interpreting them as the end of the THEN clause.

<EXPIRES> Automatically delete links & pages

    <EXPIRES n units>

Requires: a CREATEDOC directive and a MENUDOC directive, or an INSERTFILE directive.

After a while, a popular forum maintained automatically by NetCloak Pro can generate dozens, even hundreds, of entries in a menu document or INSERTFILE target file. Cleaning up old links and their corresponding files can be a tedious chore for the Web server administrator. NetCloak Pro provides the EXPIRES tag to automatically delete links and pages after a configurable period of time has passed.

The period of time is specified with the two parameters to the EXPIRES tag. "N" represents any numeric value, and the "units" parameter may be any one of the following: "WEEKS", "DAYS", "HOURS", or "MINUTES".

For example, to automatically remove menu document entries and delete the corresponding created files after 90 days, you would put the following directive into the FDML file:

    <EXPIRES 90 DAYS>

The EXPIRES directive can be used with a CREATEDOC primary directive and a MENUDOC directive; in that case, it deletes the link in the specified menu document, and also deletes the corresponding file from the Web server.

It may also be used with the INSERTFILE primary directive, so that it deletes the text inserted into the target HTML file after the period of time has elapsed.

How it works: When the EXPIRES directive is found in an FDML file, NetCloak Pro adds special HTML comment tags around the menu item or the inserted text. These comments encode the date/time that the text is to be removed from the page. When NetCloak serves the menu document, it treats these special tags just like HIDE_DATE commands. Then, when NetCloak inserts a new item into a menu document or INSERTFILE target, it scans it for these comment tags, and permanently deletes everything between them when the expiration date is passed. When it deletes an item from a menu document, it also looks for the corresponding article file and deletes it as well.

<SET_NETCLOAK> Set NetCloak configuration options

    <SET_NETCLOAK Setting = Value> or
    <NETCLOAK Setting = Value>

These NetCloak configuration commands work exactly the same way as they do in cloaked pages (see "Commands: NetCloak Configuration" in the NetCloak Standard User's Guide and "Pro Commands: NetCloak Configuration" later in this User's Guide); they change the NetCloak configuration setting specified while the FDML file is processed. Like VERIFY directives, you can include as many SET_NETCLOAK or NETCLOAK directives in the page as you want to. The most common use for SET_NETCLOAK directives is to specify the link text used in LINKNEXT/LINKPREVIOUS tags in created articles, like this:

    <SET_NETCLOAK LinkNextText = "Next Recipe">    <SET_NETCLOAK LinkPrevText = "Previous Recipe">

Thus, you can customize the link text for the kinds of articles the FDML file is creating.

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