Overview of SiteGrinder Pro Forms

(NOTE: THIS IS BETA DOCUMENTATION AND IS THEREFORE INCOMPLETE AND SUBJECT TO CHANGE. PLEASE NOTIFY HELP@MEDIALAB.COM OF ERRORS OR SUGGESTIONS)

A form is a way of collecting information on a web page and doing something with it. Some examples include:

SiteGrinder Pro supports two types of email forms: PHP and CGI, and it also supports generic forms that users can customize to do anything.

Form elements like menus and text entry fieds are represented in Photoshop type layers using a simple short-hand. You tell SiteGrinder which type layers have form elements in them by adding the -form hint to their layer names.

All forms require one or another specific technology, like PHP or CGI, to be available and properly configured on your web server.


NOTE:  SiteGrinder can also import forms from external HTML files using its -xmedia hint.  For forms the require complex layout or sophisticated user interaction, this would be the best route, rather than trying to push too hard on SiteGrinder's basic form abilities.




Basic Forms

Hint: -form

SiteGrinder Pro supports a simple method of adding form elements to type layers. Adding the -form hint to a type layer tells SiteGrinder Pro to look for a special short-hand we designed to represent various form elements.

SiteGrinder looks for lines of text containing colons in a -form layer and tries to interpret them as a form element based on this short-hand.

Here is a list of the form elements currently supported along with brief descriptions of the short-hand used to create them:

Text Entry Fields
Label text followed by a colon followed by underscores representing the length of the field. There may be multiple lines of underscores for a multi-line entry field. Example "name: _________"
Checkboxes
Label text followed by a colon followed by brackets with an optional "X" inside to represent the default check. Example "can we contact you? : [x]"
Menus
Label text followed by a colon followed by menu items separated by spaces and vertical lines. Example "Favorite browser: IE | Firefox | Opera"
Multiple choice list box
Label text followed by a colon followed by options in brackets, one option per line. (Example below)
Buttons
Label text inside parentheses. Usually there is one button named something like "Send" or "Submit". Example "(Send)"
Formsets
A formset is a way of grouping form elements together visually. It consists of a label sitting on a rectangle surrounding the form elements. When there is any text on the line just before a form element, it will be used as the formset label. The form elements that appear on the lines after the formset label are grouped together in the formset.
Descriptive text
You can have regular styled text interspersed with form elements in the same type layer. Text that doesn't have any colons and is separated by at least one blank line from form elements will just appear as styled text. You can put descriptive text before and after form elements. You can also place normal text between form elements. This will break the elements into multiple formsets.

On the left is a working formset, on the right appears the contents of the type layer that created it:  

Contact Us

This is some descriptive text

SiteGrinder Pro Survey
 

Contact Us

*email address: _______________

name: ________________________

comments: ______________________

         ______________________

         ______________________

         ______________________

can we contact you? : [x]

Operating System: Mac | Windows | Unix

 

This is some descriptive text

 

SiteGrinder Pro Survey

Top 2 Features: [External media]

[Galleries]

[Forms]

[Flash slideshows]

(Send)

 

  

Explanation:

Contact Us
Since this text is on the line before the form starts it becomes the legend for the field set, titling the box that surrounds the fieldset.
*email address
Also a text entry line.  The star ( * ) preceding the name means this field is required.  SiteGrinder can enforce this requirement for the CGI and PHP mail forms, but not generic forms
name
A text entry line.  The repeated underscores  ( _ ) mean text entry line.  The more underscores, the wider the entry box.
comments
A text area box. The width of the area is the number of underscores in the top line, it's height the number of underscore-only lines.
Can we contact you
A checkbox. [x] means checkbox that starts checked, [ ] is an unchecked checkbox.
Operating System
This one will become a popup choice.  Each choice is separated by a vertical line character ( | ) and they must all appear on one line.

After the "Operating System" menu there is a blank line.  This stops the form processor. The descriptive text contains no colons so it is just added as text.

The SiteGrinder Pro form generator kicks in again when it hits the "Top 2 Features:" entry.  Because the descriptive text splits the form elements, two formsets are created.

Top 2 Features
A multi-select list. The values appear on separate lines. People filling out the form can select on or more of the items.
( Send )
A text bound in parenthesis defines a button. If the button is not on a line with a label, then the button will take its name from itself. Thus, buttons can appear on their own line without a label.
 
 

Advanced Forms

Names and Values
If we have a form entry like this:   

email: ______________________


the text on the left (email) becomes a <label>  and the underscores get translated into the appropriate form control.  The name and id of the control is the name of the label.  In some forms, the control names are important.  For example, in the mail forms it is important to have controls with names like  email, subject, and name.  Because those names influence how the form works. The default SiteGrinder behavior is to give the control the same name that appears within the label.


Separating Names and Values  ( / )  -- Other Languages.
If you are making a contact form in Spanish then you might want the following form:

nombre:_______________________

*correo electronico: ____________________________

But, while that form may look right, it may not work 100% correctly, because the software that processes the form for sending mail wants fields named name and email, not nombre and correo electronico.  

If you need to separate the way a label is displayed from the value it is given, put a slash in the name with the display part on the left and the value on the right:

nombre/name : ________________________

*correo electronico/email : ____________________

This form will only display the Spanish names to the user, but apply the important form values to the controls.

This feature is useful in other situations besides localization of forms.  If you are using our generic form generator then you may very well be hooking the form up to a third party action (like a google search) where the values are not user friendly names.

Note:  This feature is also available for list boxes and choices, as in:

platform: Mac/m | Win/w | Unix/u

x-mas wishes: [ dos dientes/ two front teeth ]

              [ world peas / b    ]


Right to Left
Not all languages read left to right like English.  Some (like Hebrew and Arabic) read right to left.   The SiteGrinder form parser will understand entries in either order.  For example, the following is perfectly acceptable:

________________________ : name

However, SiteGrinder won't apply the right-to-left attribute ( dir="rtl")  to the form or fieldsets.  You'll have to do that yourself in the final HTML.


Two Controls Per Line, One Control On a Line
As far as the SiteGrinder CGI and PHP mail forms are concerned, every line except the send button needs a label.   But, you can, if you wish, forego labels and put just one control on a line, or replace the labels and put two controls on a line, like so:

______________________ : Mac | Win | Unix                     

[x]

But, note that form parsing doesn't start until the parser hits a colon and finds a valid control on one side of it.  Also, there is no way to set the ids and values for these control items. They'll be given random ids. 


Form Layout and Styling
SiteGrinder will layout the form for you.  It automatically places all the items such that they are lined up.  It is not necessary that you line up the colons when you are typing in a form, but it is a good habit to do so because you'll be able to anticipate overly long label names or controls. For that reason it is very helpful to use a non-proportional font, such as Courier.

When SiteGrinder is calculating the text styles for the form it calculates the average of all the styles used by all the labels and makes that the text style for the every fieldset.  Thus, you can select the font, color, size and other character attributes of the form elements, but not individually.

When displayed on the HTML page, the forms tend to grow considerably, especially vertically.  Plan for this with your design.  The form will be constrained to the width of the paragraph box it is in, so try to make these generous.


PHP Mail Forms


If your server supports PHP and it is configured to use sendmail  (a fairly common configuration) then you'll be able to benefit from SiteGrinder's PHP Mail form ability.

The nice thing about using PHP Mail forms from SiteGrinder is that they just work. Nothing fancy is required.  They work.

Required - Recipient and Thank You Page
There are two pieces of data you provide the PHP forms in the PHP form user interface panel. The recipient is the email address that all the form data will be sent to.   The Thank You Page is the page the user will see after successfully completing the form.

Subject, Email, Name
The words subject, email, and name, are special reserved words for the PHP form.  They set the subject,  reply-to email address and the name of the sender when the email is sent.  They can be handled in two different ways. 

If the form has a control with an id that matches one of these keywords, then whatever value the user types in there will be used on the email that is sent out.  Example:

*name    :_______________________

*email   :_______________________

*subject :_______________________

The form above lets the user set the name and email address that the email will appear from as well as the subject line of that email.  The star ( * ) preceding each entry means that field is required.  The form will require that the user complete those fields before proceeding.  The star is not part of the control name.

OR, one of more of those values can be set in SiteGrinder's Forms panel using the PHP dialog:

[]

Some configurations of sendmail and PHP will only allow certain recipients or certain "from" email addresses (or certain subject lines).  Check with your host for the allowed configurations and use the PHP dialog to set them if necessary.


CGI Mail Forms


Most servers support CGI mail.  CGI Mail is not standardized, but there aren't too many CGI form mail scripts floating around and they are all fairly similar.

Before you can use the CGI mail option, you must know the name and location of your server's "formmail" CGI script file.  A full URL would be easiest, but in some cases you may have to use a relative URL.You can find out this information from your web hosting company.

Most CGI mail scripts support both post and get methods, with post generally being preferred

Reserved Keywords
Like the PHP form above, every CGI script has keywords that it uses to help process the mail.  But unlike the PHP form above, these keywords are not standardized. Therefore, there is no guarantee that the words name, email, and subject will behave as expected (though they probably do).  Like the PHP forms above, the important reserved words can appear in the form itself and thus be user supplied, or be preset in the CGI user interface.

Here are the common keywords you might use for a CGI mail script

IMPORTANT: unlike the PHP mail, the recipient is set via a keyword (or possibly even in the form itself).  And the thank you page is usually called redirect and it should be an absolute URL ( http://www.medialab.com/thankyou.htm) not just a page name.


[]



The Generic Form


You can attach a SiteGrinder form to any action you want, specify post and get, and provide hidden input values as well using the generic form dialog of the SiteGrinder Pro Forms panel.

Emacs!



Example: Making a Google search form


You can use the form parser and the generic form feature to make a google search form.  Of course, these things are very standardized, so it might just be simpler to copy/paste the HTML into a SiteGrinder HTML snippet or into an external HTML document that you include via an -xmedia layer.

For example, here is the HTML for a common Google search form, it will search the Media Lab website:

<form method="get" action="http://www.google.com/custom">

<input type="submit" name="sa" value="Search">

<input type="text" name="q" size="20" value="">

<input type="hidden" name="sitesearch" value="medialab.com">

</form>

<small><a href="http://www.google.com/search">Powered by Google</a></small>


Or, to use SiteGrinder Pro's form grinder, make a text layer, give it the -form hint and enter the following into it.


Search/q:___________________________

(Go/sa)

Then open SiteGrinder, choose the Forms pane, find your text layer and click on its entry to open the form dialog.  Change the type to generic form.

Set the action to: http://www.google.com/custom
Set the method to :  get

If you want to limit the search to a specific site, then add a row to the hidden input grid in the lower part of the dialog and enter the name sitesearch, and provide your domain as the value   (Example:  medialab.com )

Done.