NetCloak Demo

This first example will be the simplest. Sending mail with NetCloak Pro is very straightforward using the SENDMAIL directive.

Creating HTML Input Forms

The first step in building all forms processing systems isn't the FDML file, but rather the HTML input form itself. Any HTML editor will allow you to build HTML forms, and they can also be created using any text editor without much difficulty. Building HTML forms is outside the scope of this tutorial, and how this is done wil vary depending on your HTML editor. See the User's Guide that came with your HTML editor, or one of the excellent on-line HTML tutorials for complete details on creating input forms in HTML. The NetCloak user's guide also has a brief reference list of HTML form fields if you need to brush up.

To get started, fire up your favorite HTML editor and create a simple form for requesting information. Add a field for entering a name. Don't forget to name the field "Name" as well as labelling it on the HTML page. When you are done, add a submit button. Don't worry about what it will do... we'll get to that later.

There is one aspect of the form that is dictated by NetCloak, the FORM ACTION. Every HTML form includes a FORM tag, and one of the parameters of this tag, the ACTION parameter, tells the browser where to send the information once the user fills in the form and clicks the submit button. When you create the form, be sure to specify the ACTION as the URL to the FDML file. The URL is no different from any other link, it can be a full URL, root relative, or partial, just like any hypertext link.

For now, just enter "Test.FDML", which is a filename for the FDML file we will create in the next section. Don't include a leading slash or any folders or other path information. The FDML file will then be put in the same folder along with the input form, and the browser should process the FORM ACTION correctly. Here is how your complete FORM command should look:

    <FORM METHOD=POST ACTION="Test.FDML">

Starting the FDML File

When your HTML input form is ready, put it on the server like you would any other HTML page and open it in your Web browser. You should be able to fill in the various fields, but when you click the submit button, the server will return an error. You are now ready to create the FDML file, which will tell NetCloak how to process the form data.

Using a text editor (not your HTML editor), create a new file. This will be the FDML template that tells NetCloak to send data from the form you just created as a mail message. Now enter the SENDMAIL command, the syntax of which will specify what mail server to use to send the message, who the message is going to, who the message should be from, and what the message subject is. Here is an example:

    <SENDMAIL "mail.myorg.com" "bob@myorg.com" "tim@myorg.com">Form Submission</SENDMAIL>

The first parameter ("mail.myorg.com" in the sample above) is the address or domain name of your local SMTP mail server. If you aren't sure of the name or address of your mail server, check the mail server setting of your own e-mail program to find out what it is.

The second parameter is the e-mail address of the recipient of the message. For now, simply enter your own e-mail address. This is followed by the "From" address, which is the mail account the message will appear to have been sent from. In the sample above, this parameter is set to "tim@myorg.com", but for now you should set this paramater to your own e-mail address.

---

NetCloak Tip: One of the most common problems encountered when having NetCloak send e-mail is an invalid "From" address. Many, if not most, mail servers these days are configured to only process mail from known senders, which prevents spammers from using the mail server to forward junk mail. Unfortunately, this restriction also prevents legitimate mail forwarding. So, you need to be certain that the "From" mail address is a correct address and that the user specified has an account on your mail server. When in doubt, start by entering your own mail address for this field, and once you have confirmed that mail is being sent properly, you can try changing the setting to any other "From" address you like.

---

In between the "SENDMAIL" and "/SENDMAIL" tags, the message subject is specified. You can set this to anything you like, but for now make sure that the subject wil be unique and easily identifiable for testing.

The rest of the FDML file is simply the text of the mail message. For now, just type a line of text or two that will let you recognize the message. When you are done, your complete FDML file will look something like this:

    <SENDMAIL "mail.myorg.com" "bob@myorg.com" "tim@myorg.com">Form Submission</SENDMAIL>



    The form was submitted and NetCloak sent you this message.

Now save the file in the same folder on your Web server as the input form you created earlier, and name it "Test.FDML".

When that's done, go back to a Web browser and open the input form again through the Web server. Enter some information into the input fields, if you like, and click submit. This time, instead of an error message, you should get the generic NetCloak "Thank You". Wait a couple of minutes and check your e-mail account... There should be a new message waiting for you.

Debugging SENDMAIL

If the FDML example above doesn't work, you'll need to figure out why. The first possibility is that the server couldn't find the FDML file. If you submitted the HTML input form and got a "Can't Find FDML File" error instead of the "Thank You" message, then this is the case. Check to be sure that the FDML file is in the same folder as the input form, and check the FORM ACTION parameter to make sure it specifies the exact name of the FDML file you created.

If NetCloak did return the "Thank You" message but you don't receive the e-mail message after 5 or 10 minutes, then an error occurred sending the e-mail. Open the "NetCloak Files" folder on the server, then open the "Failed Mail" folder. A text file should be sitting in this folder that you can open with SimpleText or BBEdit. It will include all of the details about the message, including the "To" and "From" addresses, the message body itself, and an error line that describes what went wrong. If the error message doesn't lead you to a resolution to the problem, send the failed mail file to "support@maxum.com" and our Maxum support people will help you identify the trouble.

Extending The Example

Now that NetCloak has accepted the form submission and sent you e-mail, we've got a firm grounding to work from. The trouble is that the e-mail message you get doesn't have anything interesting in it. That's easy to fix.

Remember that an FDML is essentially just a template. Whatever message you included in your FDML file after the SENDMAIL command is what shows up in your e-mail message. If you put a carriage return between two lines in the FDML file, then a space will be included in the e-mail message when you receive it. To have the user entered information included in the message, you use the NetCloak REPLACE command to insert the field into the e-mail message according to the FDML template.

For example, let's say your input form has the fields "Name", "Phone", and "Message". These fields can be simple text fields, pop-up menus, radio buttons, etc. The form is defined by the standard HTML... All that matters to NetCloak is the field NAME parameter. To include the "Name", "Phone", and "Message" information entered into the form by the user, you would update the FDML file to look something like this:

    <SENDMAIL "mail.myorg.com" "bob@myorg.com" "tim@myorg.com">Form Submission</SENDMAIL>

    A Message was submitted by <REPLACE Name> (Phone: <REPLACE Phone>).

    

    Message -

    <REPLACE Message>

If a user named "John" with the phone number of "555-5555" submitted the message form, you would then receive an e-mail message like this:

    A Message was submitted by John (Phone: 555-5555).

    Message -
    This text was entered into the "Message" field on the input form.

Other commands can also be used to represent the user entered information in an FDML template. In particular, the "IF" command is very useful. For additional details on all of the "Insertion Commands", see the NetCloak Pro User's Guide.

The new form-to-e-mail system can be extended in other ways as well. For example, in almost all cases you will want to return your own message when a form is submitted instead of the simple NetCloak "Thank You" message. This is done with the RESPONSE directive, which is put at the top of your FDML file, along with the primary directive. Here is how the FDML above would be changed to return the page "MyResponse.html":

    <RESPONSE>"MyResponse.html"</RESPONSE>

    <SENDMAIL "mail.myorg.com" "bob@myorg.com" "tim@myorg.com">Form Submission</SENDMAIL>

    A Message was submitted by <REPLACE Name> (Phone: <REPLACE Phone>).

    

    Message -

    <REPLACE Message>

Other directives allow your FDML file to confirm input of required fields, "chain" to a second FDML file, and more. As you gain confidence in your ability to process forms using FDML files, review the NetCloak Pro User's Guide for ful details on the variety of options available.