Return CGI Library
Return Form Handling

The "save to file" feature of the mail2 gadget is compatible with the e-mail and the reply/redirect options (i.e. you can do all three operations at once).

To save your form data to a file, you need to add at least two or three variables to your form.

• A variable called SAVE specifies the path to a file to save the results into. UNLIKE the template paths, this file is relative to your home directory (the directory above the top directory of the webserver).
  
  Important: The name of the datafile must end in ".dat" if the file you specify with the SAVE variable doesn't have this ending... then .dat will be appended to the value you specify. This is a security feature designed to prevent the gadget from creating 'dangerous' files in your account. You can easily get the data back into an HTML file using a server side include:
  <!--#include file="filename.dat"--> .
  
  
• A variable called FORMAT indicates the format in which you would like this data saved. The gadget understands four built in formats and also allows you to use templates. The built in values are: tab, comma, quote, and human. If the FORMAT specifies any of the four built in values, then that format is used, otherwise FORMAT is taken to specify the path to a template. (More on the built in formats later.)
  
  
• A variable called LOGIN specifies the userid under whose directory to save the file.
  
  
• For the built in formats: A variable called FIELDS specifies the list of fields to be saved, and which order to save the fields in.
  
  
• Adding ":OVERWRITE:" to the FLAGS variable will cause the gadget to over-write the datafile instead of appending to it. This is probably not usefull for datafiles, but it can make for "easy to update" sections of HTML pages :-). [I've been asked for an example... ok try this example.]
  
  

The built in formats

Here are descriptions and examples of the 4 built in formats.

[Please note: all of these files are TEXT FILES and should be transfered to and from the server as such in FTP... transfering in BINARY MODE may cause you trouble when loading them into a database... especially on a MAC.]

The "tab" format is the simplest. Each all the fields are written to the file in the specified order with a "tab" character (control I, ASCII code 8) between them. The line (record) is ended with a newline character. Since tab characters are hard to see, we'll write them as <tab>. Example:

field1<tab>field2<tab>field3<tab>field4

The "comma" format is the same as the "tab" format, except that a "," (comma) character is used instead of a tab character. This works fine unless there is a comma in your data :-(. Example:

field1,field2,field3,field4

The "quote" format is similar to the "comma" format. Every field is surrounded with double quotes ("), an comma is inserted between fields and the line (record) is ended with a newline character. This can solve the problem of commas in your data. Example:

"field1","field2","field3","field4"

The "human" format is not intended for database use. It lists each field name and the corresponding field data on a separate line. There is a blank line between records. It looks like:

field1name: field1data
field2name: field2data
field3name: field3data
field4name: field4data

The examples

The only meaningful example I can see here is to make our own guestbook gadget ;-). This will serve to demonstrate the flexibility of the gadget, but since it's not a particularly appropriate demonstration of a database file, A second example is shown using the quote format.

Hhhmm, what should we put in our guestbook? Should we just clone the existing one? Let's do that....

Before going on, let's note that the 'real' guestbook gadget has some important features that we can't duplicate here: it strips HTML by replacing < > symbols with their &lt; &gt; equivalent, it gives the choice of adding the recent entries at the top or the bottom of the page, and it inserts the date.

Here's the template (example4.tpl):

<b>{NAME}</b> from {FROM} wrote:<br />
<i>"{COMMENT}"</i> <br /><br />

Here's the HTML for the form:

<form action="/cgi-bin/mail2" method="post">
<input type="hidden" name="SAVE"
  value="baremetal/gadgets/mail2/example4.dat" />
<input type="hidden" name="LOGIN" value="tbrown" />
<input type="hidden" name="FORMAT" value="/gadgets/mail2/example4.tpl" />
<input type="hidden" name="REDIRECT" value="/gadgets/mail2/example4.html" />
               Who are you: <input name="NAME" size="40" />
        Where are you from: <input name="FROM" size="40" />
What would you like to say: <input name="COMMENT" size="40" />
<input type="submit" value="Leave your comments" size="40" />
</form>

And here's the form:

               Who are you: 
        Where are you from: 
What would you like to say: 

Note that we had to use a UNIX symbolic link to get at the output with a .html extension :-). [That capability is an advantage of being an administrator.]

OK... for those building real databases, here's another example, with the relevant form HTML shown and a link to the output data file.

<input type="hidden" name="SAVE"
  value="baremetal/gadgets/mail2/example4.2.dat" />
<input type="hidden" name="LOGIN" value="tbrown" />
<input type="hidden" name="FORMAT" value="quote" />
<input type="hidden" name="FIELDS" value="NAME FROM COMMENT" />
<input type="hidden" name=REDIRECT value="/gadgets/mail2/example4.2.txt" />

               Who are you: 
        Where are you from: 
What would you like to say: