Reference Guide
Forms Processing Commands:
Primary and Supplemental Directives
Contents
|
Version 3.1 Reference Guide |
Forms Processing Commands:Primary and Supplemental Directives |
Previous |
Next Contents |
After you have created an HTML input form, you will need to create an FDML document. FDML stands for Forms Definition Markup Language and can be thought of as a language similar to HTML that understood only by NetCloak Pro. FDML documents are referred to as "templates", and contain tags that tell NetCloak how to format the data entered by an author in the input form as well as direct it how to act on the data once it is formatted.
There are three types of NetCloak Pro tags that can be used in FDML files:
The commands provided by FDML are used to execute the four Primary Directives of NetCloak. There must be always exactly one Primary Directive specified in any FDML document.
The four Primary Directives of NetCloak are designed to perform the following tasks:
The following sections describe these four capabilities, and you are encouraged to refer to the tutorial examples in the User's Guide to see each of the Primary Directives in action.
The CREATEDOC directive tells NetCloak to build a new HTML page and save it as a file specified by the Filename parameter, as in the example below. The Filename parameter can be specified as a path relative to the web server root folder or relative to the FDML document. The proper syntax for the CREATEDOC directive is:
<CREATEDOC>" Filename
"</CREATEDOC>
New document template...
Frequently the directive will contain other FDML insertion commands (like REPLACE, described in the Commands section) to build a dynamic filename so that documents are uniquely named on your server and are not overwritten each time a new user fills out your form.
When any of the insertion commands are used in a filename, you should use the REPLACE_FN (FN stands for File Name) command. This ensures that characters which are not allowed in file or folder names are removed before new files are created. See the REPLACE command for more information.
When the filename you specify contains Finder aliases to folders, the aliases are resolved automatically. Also, if any folders in the path do not exist, they are created automatically. If you use the YEAR or MONTH insertion commands in the Filename parameter, for example, you can have NetCloak automatically create a new folder for every year and every month, like this:
<CREATEDOC>"Reports/<YEAR>/<MONTH_FN>/MonthlyReport.html"</CREATEDOC>
What follows the closing CREATEDOC in the FDML file is text and/or HTML that serves as a template for the document to be created. This template defines the format of the new document, including the standard HTML, header, and body tags (<HTML>...</HTML>, <HEAD>...</HEAD>, and <BODY>...</BODY>). Throughout the document template, you may use FDML insertion commands to dynamically insert form data into the created document.
Note: FDML syntax is similar to HTML, but is different enough to cause problems when using WYSIWYG HTML editing applications like Adobe GoLive or Claris HomePage. If you plan to use such a program to create your document templates, Maxum recommends creating the template using the HTML editor first, until you are satisfied with the page layout. Then open the HTML file using a text editor like SimpleText or BBEdit, and add the FDML directives and insertion commands afterward.
The INSERTFILE directive allows you to insert text into an existing HTML page instead of creating an entirely new page. The syntax is shown below:
<INSERTFILE " MarkerText ">" Filename Text to insert...
There are two parameters used with the INSERTFILE directive.
The first, located within the opening INSERTFILE tag, is the text which marks the location within the file where the new text should be inserted. While any text may be used to mark the insertion point in the file, an HTML comment is most often used, so that the insertion point text does not appear in the page.
The second parameter is simply the path and name of the file to be updated and appears between the opening and closing tags.
The syntax of an HTML comment is shown in the following example.
<BODY>
<H1>This is a test document</H1>
<!--EnterText-->
</BODY>
To use the INSERTFILE directive to update this file, simply specify the HTML comment followed by the file path, like this, in your FDML file. For our example, the file is named testdoc.html, and is located in a folder named docs located in the root folder of the web server:
<INSERTFILE "<!--EnterText-->">
"/docs/testdoc.html"
</INSERTFILE>
Following the closing INSERTFILE tag is the text or HTML to be inserted into the document. As with the CREATEDOC directive, you may use any standard HTML tag and any FDML insertion command in this text to customize it based on the form input data. Since this text will be inserted into an existing HTML document, however, you should not include the HTML, header, and body tags.
Using the basic INSERTFILE directive, new text will be added after the comment, which will cause the new entries to be added to the top of the list of entries, creating a newest first listing. Use the variation INSERTFILE* to have new entries added before the comment, which will cause the list of entries to grow downward, in a newest last format.
The TEXTSTORE directive will store data submitted from a form in a tab-delimited text file without any other formatting. Data from subsequent form submissions are added as the next line of the file.
There will probably be times when you want to create a form to receive user input and use that information in another application such as a spreadsheet or a database application. You might also want to store data in a simple format for archival or backup purposes, and go on to process the form with other FDML documents.
In either case, the NetCloak directive TEXTSTORE will handle this for you by creating and maintaining a tab-delimited text file. This file can then be imported into the application or database of your choice whenever you need it. What you do with the file is up to you, but virtually all word processing, database, and spreadsheet applications will read or import it. Most personal information managers and other types of software will read the information as well.
The syntax for the TEXTSTORE directive is as follows.
<TEXTSTORE>" TextFileName
"</TEXTSTORE>
Record format...
The TextFileName parameter is simply the name of the file that NetCloak will create and maintain. As with any directive, you may use FDML insertion commands within the parameter to allow files to be created and maintained based on user input. Note that since the created file is not an HTML file, it should not have the .html file suffix . Instead, it should have a suffix of .text or .txt, to denote that it is a text file.
Following the TEXTSTORE directive in the FDML file is the list of fields you would like stored in each record in the text file. Records are separated in the text file by a single carriage return character, and fields within a record are separated by a tab character.
In the FDML file, each field name is placed by itself on a line of the FDML file in the order they are to appear in the file. The data specified on each line of the FDML will be separated by a tab and all of the lines of the FDML will be combined into a single line in the text file.
For example, if you have a form with fields for Name and E-mail, the syntax for a very simple FDML document to store the data in a file would be:
<TEXTSTORE>"Signup.text"</TEXTSTORE>
Name
E-mail
This would result in a text file named Signup.text (located in the same folder as the FDML file) which might contain the following text after a few users had used the form page:
Chris Patterson chris@maxum.com
John O'Fallon john@maxum.com
Steve Jobs steve@apple.com
You can also specify text constants to be stored in the text file by beginning a line of the FDML file with a plus sign (+). This tells NetCloak to insert the text exactly as it appears, without attempting to find user-entered data for that field. Inserting constant text by itself isn't terribly useful, but when used in conjunction with other NetCloak commands, the possibilities grow considerably. For example, we can add a time and date stamp to our signup example above, as in the following example:
<TEXTSTORE>"Signup.text"</TEXTSTORE>
+Date: <DATE> Time: <TIME>
E-mail
Which would result in a text file that looked like this:
Date: 12/15/97 Time: 08:42:18 john@maxum.com
Date: 12/16/97 Time: 18:02:44 steve@apple.com
The E-mail field could also be labeled, as in the following example:
<TEXTSTORE>"Signup.text"</TEXTSTORE>
+Date: <DATE> Time: <TIME>
+E-Mail: <REPLACE Email>
Resulting in:
Date: 12/14/97 Time: 14:25:27 E-Mail: chris@maxum.com
Date: 12/15/97 Time: 08:42:18 E-Mail: john@maxum.com
Date: 12/16/97 Time: 18:02:44 E-Mail: steve@apple.com
TEXTSTORE FDML files are completely parsed, so you can use all FDML insertion commands, including IF commands, within TEXTSTORE documents. The IF command can be used effectively within TEXTSTORE documents to selectively insert fields based on the contents of other fields. In addition, you can specify text to be inserted into the data file as-is.
NetCloak is capable of sending e-mail messages using Simple Mail Transfer Protocol (SMTP).
When a form is submitted, NetCloak can build an e-mail message and send it to anyone you like. As the author of the HTML entry form, you control which user-entered fields are included in the message and the format of the message. The SENDMAIL syntax is:
<SENDMAIL "server" "to" "from" "cc">
subject
</SENDMAIL>
Message to send...
Within the SENDMAIL tag, there are four parameters, described below.
This is the address of the SMTP mail server that NetCloak will use to send the message. Normally this is the address of your mail server or your ISP's mail server, not the server of the person receiving the message. While a message for ed@somewhere.net may be sent directly to the mail server somewhere.net, you would normally tell NetCloak to connect to your local mail server. The server that NetCloak gives the message to will then forward the e-mail to the appropriate server for the recipient.
To reduce the chances of failure, you should use the closest (and most stable) e-mail server available to you.
If you aren't sure of the address of your e-mail server, check your Internet e-mail client software configuration or ask your ISP or network administrator.
This parameter contains the e-mail addresses of the person or persons to whom the message will be sent. For example, bob@mycompany.com or bob@mail.mycompany.com.
You may specify multiple e-mail recipients in this parameter by separating the e-mail addresses with a comma, like this: "bob@company.com, fred@company.com, jill@company.com".
For each recipient, you may also include the user's real name, like this: "Bob Smith bob@company.com, Fred Jones fred@company.com, Jill Johnson jill@company.com".
Finally, for each e-mail address, you may use double quote characters to mark text that is to be ignored by the mail server when parsing the address, such as the real name. But because double quote characters are also used to delimit the to: address parameter, you must use two double quotes around the embedded double-quote characters within the SENDMAIL tag. For example:
<SENDMAIL ... """Chris Patterson"" chris@maxum.com" ... >
NetCloak insertion commands can be used to dynamically set the to parameter.
This parameter is required, and specifies an address from which the message has been sent. The from: address must be a valid e-mail address, otherwise the message may be rejected by the mail server. If there is a problem with the message, most mail servers will first attempt to return it to the sender.
This is an optional parameter, which lists additional email addresses of carbon-copy recipients of the message. As with the to parameter, you may specify multiple carbon-copy recipients, with or without real names, and may use NetCloak insertion commands to dynamically cc recipients.
Immediately following the SENDMAIL tag is the message subject. This is followed by the closing SENDMAIL tag. As with any directive parameter, REPLACE and other insertion commands can be used to dynamically create a subject line.
Anything after the </SENDMAIL> will be sent in the body of the message. A combination of plain text and insertion commands may be used to customize the body of the message from the input form data.
The content type of the mail message is normally plain text, which is the default content type, and is supported by all e-mail client software. However, you can send a message with HTML-formatted content. NetCloak will set the content type of the mail message to text/html if the very first text of the message, other than space characters, is the HTML tag. This allows HTML-formatted mail messages to be displayed properly by e-mail clients, such as Netscape Communicator, that can handle them.
Using NetCloak to send e-mail is very simple and is almost always set up in much the same way, so an example will make things clearer and is always a good place to start. For this example, we have an HTML form that accepts the following fields from the user: Email, Subject, UserName, Phone, and Message. The FDML would look like this:
<RESPONSE>"/MailDemo/Response.html"</RESPONSE>
<SENDMAIL
"mail.yourorg.com"
"John Smith john@mail.yourorg.com"
"<REPLACE UserName> <REPLACE Email>">
<REPLACE Subject>
</SENDMAIL>
Name: <REPLACE UserName>
E-Mail Address: <REPLACE Email>
Phone Number: <REPLACE Phone>
Message:
<REPLACE Message>
Here we've used a RESPONSE directive prior to the SENDMAIL directive to allow a predetermined HTML page to be returned to a user after the SENDMAIL form is submitted. The SENDMAIL directive then specifies exactly how to send the message, including SMTP host, sender, recipient (obtained from the person filling in the form), and subject (also obtained from the form). In this case, NetCloak will use the server mail.yourorg.com to send a message to John Smith. The message will be from the person that filled out the form, so when John uses his e-mail client to reply to the message, the reply will be automatically sent to the correct address.
Note that using REPLACE commands within the SENDMAIL directive is perfectly legal, and sometimes essential. Finally, following the SENDMAIL directive is the body of the message (which is also obtained from the form that has been completed).
When a mail message is created using the SENDMAIL directive, NetCloak stores the information about the message in a uniquely-named text file inside the folder named NetForms Mail Queue inside the NetCloak Files folder. At regular intervals, it looks for files in this folder, and attempts to send them using the SMTP protocol.
If the message is sent successfully, the mail file is deleted.
If the message cannot be sent, the mail file is updated with a retry count and an error message that explains the reason the message could not be sent. Common reasons that mail messages fail to be sent are:
NetCloak will try to send mail messages up to five times. After the fifth failed attempt, the corresponding mail file is moved from the NetForms Mail Queue folder into another folder named NetForms Failed Mail inside the NetCloak Files folder. This is the electronic equivalent of the dead-letter bin at your post office. Once moved, these files are ignored by NetCloak.
Periodically, the NetCloak administrator should check the contents of the NetForms Failed Mail folder. Some failed mail messages can be easily fixed by editing the mail file (they are simple TEXT files) and re-queuing them by moving them back to the NetForms Mail Queue folder. Other failed mail files may be simply dragged to the Trash to reclaim disk space.
Hot tip: Because NetCloak looks for text files in the NetForms Mail Queue folder to send email messages, any application or AppleScript that can create text files can also use NetCloak to send email messages! The text file created need only conform to the format of NetCloak-generated mail files in order for NetCloak to be able to send a message.
There are ten Supplemental Directives and many 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 NetCloak.
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 in addition to that specified by the Primary Directive.
Insertion Commands 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 text file created by NetCloak.
Within each FDML document you may use each Supplemental Directive only once, but Insertion Commands may be used repeatedly.
The NetCloak Supplemental Directives will allow you to:
| AUTOLINK | Automatically replace text entered into articles with text you specify |
| CHAIN | Connect more FDML documents to process data from the same form |
| COPY | Save a second copy of an article |
| MENUDOC | Automatically insert a link to a new article or other text into an existing document |
| RECENTLIST | Add the new article to an internal list of recently submitted articles |
| RESPONSE | Send a customized response file to the user after the form data is processed |
| VERIFY | Verify that specified fields in the form are not empty |
| RETURN_PAGE | Send a customized response file and abort form processing (used with the IF command). |
| EXPIRE | Automatically delete the created document or inserted text, and menu document links, after a specified period of time has passed. |
| SET_NETCLOAK | Temporarily modify NetCloak configuration settings while processing a form submission. |
<AUTOLINK>" Filename "</AUTOLINK>
One of the most popular features of NetCloak 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 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 is 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>" Filename "</CHAIN>
The CHAIN directive is used within any FDML document, and allows you to specify additional FDML documents used to process 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 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.
Syntax:
<COPY>" Filename
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.
Syntax:
<MENUDOC " MarkerText
">" Filename
LinkText
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. 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.
If no MarkerText is specified, NetCloak 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, add the text marking the insertion point to the opening MENUDOC tag in your FDML file. For example, if the 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)
<RECENTLIST ListID
LinkText
Requires: a CREATEDOC directive
NetCloak will automatically maintain a recent articles 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. 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 recent articles, the internal list is searched and the appropriate links are returned. Recent list requests can be for all articles or only those within a specified time period. Up to 256 links can be stored in the internal list.
NetCloak maintains up to 26 such internal lists, each designated by a letter A-Z. The RECENTLIST directive can include the list to add the articles to as below:
<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" in the User's Guide.
<RESPONSE>" Filename "</RESPONSE>
The RESPONSE directive allows you to specify an HTML document that will be returned to the author after they have submitted a form. An example follows:
<RESPONSE>"/Feedback/Response.html"</RESPONSE>
Note that a filename, not an URL, is specified in the RESPONSE directive.
If you do not 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" in the User's Guide for more details.
<VERIFY FieldList "</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, before the primary directive.
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 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>" 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 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 beyond simply checking whether a field is blank. To do this, use RETURN_PAGE in combination with an 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 primary directive will 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 "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, you must use two double-quote characters to delimit the file path to prevent NetCloak from interpreting them as the end of the THEN clause.
<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 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 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 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 permanently deletes everything between these tags if 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 Setting = Value <NETCLOAK Setting >
These NetCloak configuration commands work exactly the same way as they do in cloaked pages (see the section "Commands: NetCloak Configuration" above and "NetCloak Configuration" in the 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-2000 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |