What's on This Page
IMPORTANT NOTE: You cannot test your form on your local disk. Pages with forms must be uploaded to a website where the webserver and other technologies, such as php and cgi, will allow the special code required for forms to work.
- An introduction to forms
- How to Create the Available Form Elements
- Anatomy of an Example Form
- Form layout and styling
- Advanced Form Techniques
- PHP Mail Forms
- CGI Mail Forms
- Generic Forms
- Generic Form Example: Making a Google Search Form
- Troubleshooting Forms Alignment
- Troubleshooting Email Forms
Introduction
A form is a way of collecting information via a web page and doing something with it. Some examples include:
- Allowing users to send an email directly from a page
- Providing directions to your location from a location entered by a user
- Providing a Google search of your site
- Collecting survey data from your user
HTML forms can contain text entry fields, menus, and other input controls.
While there is no direct analog to the various form elements in Photoshop’s bag of layer types, SiteGrinder Pro employs a straightforward short-hand to denote multiple form elements in a single type layer using the -form hint: buttons are represented by surrounding their text with parentheses, labels are followed by colons, Text entry areas are denoted by multiple underscores, etc.
SiteGrinder Pro supports the most commonly used form elements, including text fields, menus, multi-choice boxes, and checkboxes.
SiteGrinder supports CGI and PHP email forms out of the box. This means the only requirement for the user is to name the email field labels correctly, such as "subject", and SiteGrinder handles the rest.
Generic forms for myriad other purposes, such as looking up directions on Google's map page, require the addition of appropriate URLs and sometimes custom variable names and differ with each application.
The names of the variables whose values are given by the web page visitor, such as their email address, can appear right in the form layer next to the individaul field labels.
Names and values of variables that need to be set by the web page designer, such as the street address of a store, are added using the Forms pane of the SiteGrinder user interface. This is also where the URL to submit the form to is entered.
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.
How to Create the Available Form Elements
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.
Anatomy of an Example Form
On the left below is a working form, on the right are the contents of the type layer that created it:
This is some descriptive text |
|
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 SiteGrinder's form processor. The descriptive text that follows the blank line 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 of the colon. Because the descriptive text splits the form elements, two formsets are created.
- "Top 2 Features"
- This is a multi-select list. The values appear on separate lines. People filling out the form can select one or more of the items.
- "( Send )"
- Text surrounded by parentheses 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.
Form Layout and Styling
SiteGrinder will lay out the form for you. It automatically aligns the items of the form. 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, 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.
Advanced Form Techniques
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
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 Alphabets
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.
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.
Recipient and Thank You Page
There are two required pieces of data you provide the PHP forms in the PHP form user interface panel, the recipient and the location of the "thank you page". The recipient is the email address that all the form data will be sent to, perhaps the webmaster for the site. The "thank you page" is the page the user will see after successfully completing the form.
Subject, Email, and 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 or more of those values can be set in SiteGrinder's Forms panel using the PHP dialog:
![[]](formsmedia/phpmaildialog.jpg)
Some configurations of PHP will only allow certain email 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
- recipient
- name
- subject
- redirect
- realname
- title
- missing_fields_redirect
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 ( ie "http://www.medialab.com/thankyou.htm") not just a page name.
![[]](formsmedia/cgidialog.jpg)
Generic Forms
You can attach a SiteGrinder form to any action you want, specify post or get, and provide hidden input values as well using the generic form dialog of the SiteGrinder Pro Forms panel.
Generic Form 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 )
Troubleshooting Form Alignment
Sometimes form labels end up on top of their associated entry areas or otherwise off kilter. Here are some tips to avoid this:
- Make sure you have the latest version of SiteGrinder. A number of fixes to forms were added in 2.07
- Shorten your labels and control names
- Make your text field wider, possibly a lot wider depending on your label lengths
- Browsers align by the colons, so line up your colons to audition how the form will come out. If you can't line up the colons without the lines wrapping, then the browser won't be able to either. Also, make sure you have SiteGrinder 2.0.7.
Example:
Name: _______________________________________________________
check this box if you wish to subscribe to our newsletter: []
Those two lines look about the same width, right? But they are not. Once you line up the colons, then you'll see that you'd need a massively wide text box to have those two align correctly:
Name: _______________________________________________
check this box if you wish to subscribe to our newsletter: []
Troubleshooting Email Forms
If you have problems with your email forms sending:
- Forms only work after they are uploaded, not locally on your machine.
- Double check that recipient is set in the mail properties dialog. (90%)
- Contact your host and make sure they have PHP configured with sendmail, if they limit your sending or recipient addresses in any way, or require some other sort of set up.
