NetForms 2.5 User's Guide

Primary Directives


The commands provided by FDML are used to execute the four Primary Directives of NetForms. There must be always exactly one Primary Directive specified in any FDML document.

The four Primary Directives of NetForms are designed to perform the following tasks:

The following sections describe these four capabilities, and you are encouraged to refer to the on-line examples to see each of the Primary Directives in action.


<CREATEDOC> - Creating New HTML Pages

The <CREATEDOC> directive tells NetForms to build a new HTML page and save it as a file specified by the "Filename" parameter, as in the example below. Depending on how NetForms is configured, 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 section on the REPLACE command for more information.

When the filename you specify contains path elements that are MacOS 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 NetForms 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 NetForms insertion commands to dynamically insert form data into the created document. See the on-line demonstration systems for examples of HTML document templates used with the CREATEDOC directive.

Note: FDML syntax is similar to HTML, but is different enough to cause problems when using "WYSIWYG" HTML editing applications like Adobe PageMill 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.


<INSERTFILE> - Updating Existing Pages

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"</INSERTFILE>
    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 client's browser.

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.

    <HTML>
    <HEAD>
    <TITLE>Test Document</TITLE>
    </HEAD>
    <BODY>
    
    <H1>This is a test document</H1>
    
    <!--EnterText-->
    
    </BODY>
    </HTML>

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 new document. As with the CREATEDOC directive, you may use any standard HTML tag and any NetForms 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. Use the variation <INSERTFILE*> to have new entries added before the comment, which will cause the list of entries to grow down.

Note: The maximum size of an INSERTFILE target document is 96K. When this limit is reached, NetForms will simply stop inserting text into the document.


<TEXTSTORE> - Storing Data

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. For example, you may want to load the data into a spreadsheet or into your favorite 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 NetForms FDML documents.

In either case, the NetForms directive TEXTSTORE will handle this for you by creating and maintaining a simple 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 it, when configured properly. 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 NetForms will create and maintain. As with any directive, you may use NetForms insertion commands within the parameter to allow multiple 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 plain 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 is placed by itself on a line of the FDML file. For example, if you want to allow users to submit their names and e-mail addresses you would create an HTML entry form with two fields, "Name" and "E-mail". The syntax for a very simple FDML document to store data in a file named "Signup.text" would be:

    <TEXTSTORE>"Signup.text"</TEXTSTORE>
    Name
    E-mail

This would result in a text file named "Signup.text" 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 NetForms to insert the line 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 NetForms 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>
    Name
    E-mail

Which would result in a text file that looked like this:

    Date: 12/14/97 Time: 14:25:27    Chris Patterson    chris@maxum.com
    Date: 12/15/97 Time: 08:42:18    John O'Fallon      john@maxum.com
    Date: 12/16/97 Time: 18:02:44    Steve Jobs         steve@apple.com

The "Name" and "E-mail" fields could also be labeled, as in the following example:

    <TEXTSTORE>"Signup.text"</TEXTSTORE>
    +Date: <DATE> Time: <TIME>
    +Name: <REPLACE Name>
    +E-Mail: <REPLACE Email>

Resulting in:

    Date: 12/14/97 Time: 14:25:27    Name: Chris Patterson    E-Mail: chris@maxum.com
    Date: 12/15/97 Time: 08:42:18    Name: John O'Fallon      E-Mail: john@maxum.com
    Date: 12/16/97 Time: 18:02:44    Name: Steve Jobs         E-Mail: steve@apple.com

TEXTSTORE FDML files are completely parsed, so you can use all NetForms insertion commands, and IF commands within TEXTSTORE documents. For example, the IF command can be used effectively within TEXTSTORE documents to selectively insert user responses based on the contents of other fields. In addition, you can specify text to be inserted into the data file "as is". Use the plus sign ("+") to tell NetForms "This isn't a user-entered field, it's just some text you should put into the file." See the TextDemo example included in this package for additional information on how this works.

Note: Using "WYSIWYG" HTML editors such as Adobe PageMill or Claris Home Page to create TEXTSTORE FDML files is not recommended by Maxum. This is simply because the TEXTSTORE directive does not create an HTML file it creates a plain text file. Therefore, it should not contain HTML tags of any kind. Only FDML insertion commands and field names should be used in the record formatting portion of the FDML file.


<SENDMAIL> - Sending E-mail

NetForms is capable of sending e-mail messages using Simple Mail Transfer Protocol (SMTP). This command uses threaded, native Open Transport calls for greater speed, but is also compatible with Mac OS versions that use MacTCP. An HTML response file is sent to users before e-mail has been completely sent, so errors in e-mail transmission may not be displayed to the user. To ensure that mail is never lost, NetForms saves each mail message as a file on the server until it is sent.

When a form is submitted, NetForms 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, you specify four parameters, described below.

Server

This is the address of the e-mail (SMTP) server that NetForms uses 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 may be sent to "ed@somewhere.net", you can configure NetForms to connect to any mail server you like. The server that NetForms gives the message to will then forward the e-mail to the appropriate SMTP 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.

To

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 SMTP 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 "double-double-quotes" to "escape" the embedded double-quote characters within the SENDMAIL tag. For example:

    <SENDMAIL ... """Chris S. Patterson"" chris@maxum.com" ... >

See the "BetterMailDemo" system for an example.

NetForms insertion commands can be used to dynamically set the "to" parameter.

From

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. It could be an address that would let recipients know who generated the message or from what URL the message was sent, or it could also be the address of the user sending the message, if you use a NetForms REPLACE command.

CC

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 NetForms insertion commands to dynamically "cc" recipients.

Immediately following the <SENDMAIL> tag is the message subject. This is the phrase that will be used as the subject of the e-mail message. This is followed by the closing </SENDMAIL> tag. As with any directive parameter, NetForms Insertion Commands, like <REPLACE>, can be used to dynamically create a subject line.

Anything after the </SENDMAIL> tag will be sent in the body of the message. A combination of plain text and NetForms insertion commands may be used to customize the body of the message from the input form data.

Using NetForms 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, NetForms 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).

See the "MailDemo" and "BetterMailDemo" systems in the NetForms release package.

Note: Again, because the SENDMAIL command does not create HTML documents, you are discouraged from using "WYSIWYG" HTML editing software such as Adobe PageMill, Claris Home Page, or Microsoft Front Page to create SENDMAIL FDML files. It is best to use a plain text editor such as BBEdit, Text-Edit, or even SimpleText, since most e-mail packages display plain text (more or less).

How NetForms Manages SENDMAIL Messages

When a mail message is created using the SENDMAIL directive, NetForms stores the information about the message in a uniquely-named text file inside the folder named "NetForms Mail Queue" inside the "NetForms 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:

NetForms will retry 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 "NetForms Files" folder. This is the electronic equivalent of the "dead-letter" bin at your post office. Once moved, these files are ignored by NetForms.

Periodically, the NetForms 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 NetForms 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 NetForms to send email messages! The text file created need only conform to the format of NetForms-generated mail files in order for NetForms to be able to send a message.


[ Previous | Table Of Contents | Next ]

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