Saveform 3.02a

• Why Saveform?
• Installation
• Setting up Saveform -- A quick tutorial
• Setting up a form to use Saveform
• Setting up runfiles
• Setting up templates
• Conditionals
• Versions
• Copyright

Perhaps Saveform can help.

Saveform is a WWW form proccessing tool that is designed to run in either DOS, Windows or UNIX, and to be highly powerful and extensible, while remaining very easy to use. And, it's freeware!

There are other programs out there which aim to let you write a form, plug in the program, and forget about it. However, all I've seen handle one very specific purpose, such as sending an email, or saving a user's comments. Most of these programs have a inflexible output style as well.

I've configured Saveform to:

• Mail feedback from users to me.
• Save a completed survey to a file, or complain if they didn't answer all the questions.
• Handle over 75% of the forms on Mainsail, a commercial site.

You should get 2 files -- saveform.pl, and saveform.cfg. Copy both these files to a directory your web server can run cgi scripts from.

To run Saveform, you will need perl 5.0 or above. You may need to edit the first line of saveform.pl to point to the location of the perl program.

Saveform has several items that need to be configured. These are located in the saveform.cfg file. The most important part of this file is the "mydir=" line. This specifies a directory Saveform uses for its datafiles. For security, this directory should contain only Saveform datafiles, and should have no directories under it. Make a directory for this purpose, and set the "mydir=" line to point to it.

Setting up Saveform -- A quick tutorial

Let's set up a simple comments form that saves the message to a log of messages. First, the HTML form that calls Saveform will look like this:

<FORM METHOD="POST" ACTION="/cgi-bin/saveform.pl?comments.run">
From:<INPUT TYPE="text" NAME="name"><P>
Email:<INPUT TYPE="text" NAME="email"><P>
Subject:<INPUT TYPE="text" NAME="subject"><P>
Message:<P>
<TEXTAREA NAME="message" ROWS=10 COLS=60></TEXTAREA><P>
To submit your message, press this button: 
<INPUT TYPE="submit"VALUE="Submit Comments">
</FORM>

Now, we need to tell saveform how to handle this form. All it really has to do is append the form to the end of a file, and then display a message to the user to let them know that their comments have been recieved.

As the first step in doing this, let's create two templates. Save them both to the directory you told Saveform to use for its datafiles. This one generates a message to the user, letting them know that everything's been taken care of. Save it as "comments.ok".

<H1>Your comments have been saved.</h1>
Thanks for your comments, ~name~. They have been saved, and I will take a look 
at them soon. 

The second template is appeneded to the comments file, to save their comments. Save it as "comments.sav".

Name: ~name~
Email: ~email~
Subject: ~subject~
Message:
~message~
---------------------------------------------------------------

Finally, we have to write the runfile that tells Saveform what to do with these files. Save this runfile as "comments.run":

append comments.sav /comments/comments.dat
return comments.ok

With the creation of this runfile, everything should be ready to go. Just create a directory named /comments/ (or change the runfile to use a different directory), and create a comments.dat file so there is a file for Saveform to append to. If you are on a unix system, make sure that comments.dat can be written to by the web server.

Give it a try.. Once you get it working, try editing the templates to customise the output to your liking.

Now, the sample template and runfiles I showed you are simple, and easy to understand. The one downside is that if you have many runfiles, each using make templates, you can end up with lots and lots of files and a cluttered Saveform data directory. Saveform has a feature which moves the templates into the runfiles, so you have just one Saveform file per form.

Here is feedback.run, rewritten to use that feature:

append /comments/comments.dat [
	Name: ~name~
	Email: ~email~
	Subject: ~subject~
	Message:
	~message~
	---------------------------------------------------------------
]
return [
	<H1>Your comments have been saved.</h1>
	Thanks for your comments, ~name~. They have been saved, and I will take a look
	at them soon.
]

Setting up a form to use Saveform

For DOS or Windows, a form that uses Saveform should be defined like this: (Be sure to uncomment the "dos=yes" line of saveform.cfg.)

<FORM METHOD="POST" ACTION="dir/perl.exe/feedback.run?/dir/saveform.pl">
                            |-----a----| |-----b----| |-----c--------|       

<FORM METHOD="POST" ACTION="dir/saveform.pl?feedback.run">
                            |------d------| |-----b----|

Commands:

• save template file
  This fills out a template and saves it to a file.
  • template: The template to use. The template must be in Saveform's data directory, so you don't need to specify the path to it.
  • file: The file to save the template to. You should include the full path.
• append template file
  This works just like the save command, except the template is appeneded to the end of the file. The file you are going to append to must already exist.
• return template
  This fills out a template and returns it to the user.
  • template: The template to return to the poster of the form. This is generally some sort of confirmation that the data was recieved.
• mail template address:from:subject
  This mails a template to someone. Note that the last 3 parameters are seperated by :'s, not spaces.
  • template: The template to fill out and mail.
  • address: The address to mail to.
  • from: Who should the mail be coming from?
  • subject: The subject of the message. Can be any number of words.

  Note: For NT, this requires the "blat" utility. Be sure to set up the "mail=" line in saveform.cfg to make it use blat.

  Note: For UNIX, Saveform comes pre-configured to use sendmail to send email. If you don't have sendmail, edit sendmail.cfg, and set it up to use your mail delivery program.

• printheader text
  This prints a "Content-type" header. Use this to print something other than the default "Content-type: text/html". The blank line after the header is automatically included.

  Common headers are:
  Content-type: text/html
  Content-type: text/plain

  If you do not include a header command, a "Content-type: text/html" header will automatically be used.

• run command
  This runs the commands, as if they were a part of saveform itself. These commands should be standard perl code.
  You can use the run command in two ways:
  • Just run any commands after the "run" keyword:

    run print "This is one way to do it\n"; $a=100;
    	

  • Or, run a whole series of commands, inlined. This is especially handy for defining entire subroutines all at once:

    run [
    	print "This is another way to do it\n";
    	$a=100;
    ]	
    	

• Any lines beginning with "#" are comments.
• You can now use Conditionals in the runfile just as in a template. Simply place the conditional commands before the command to be run if the conditionals test to be true.
• You can now "inline" templates in a runfile. This is an example.

In addition to variables defined by the controls you put on the form, Saveform defines the following additional variables (all must be enclosed in the ~'s):

• date -- the current date
• time -- the current time
• params -- any special parameters passed to Saveform To pass parameters, add a "*" and the parameters you want to pass, right after the name of the runfile, in the URL that calls Saveform. You must format the parameters by changing space to "_" Here is an example that sends Saveform the parameters "everything is ok":

  	http://cgi-bin/saveform.pl?sample.run*everything_is_ok
  	

'~name~'| text            <-- print text if name was filled in
!'~name~'| text           <-- print text if name was not filled in
'~name~' eq 'joey'| text  <-- print text if name = 'joey'
!'~name~' eq 'joey'| text <-- print text if name is not equal to 'joey'

'~name~'| command            <-- run command if name was filled in
!'~name~'| command           <-- run command if name was not filled in
'~name~' eq 'joey'| command  <-- run command if name = 'joey'
!'~name~' eq 'joey'| command <-- run command if name is not equal to 'joey'

('~name~') and ('~age~') and (!'~name~ eq 'joey')| You entered your name and age, and your name is not joey.