| Electronic Manual - PowerForm
© SunnyScript - www.sunnyscript.com |
| Table of contents | |||||||||||
Smart
tip: This handbook is also designed to be printed... set your
printer's page orientation to landscape format, so there is enough space
to place hand-written notes on the left and right margin easily.
|
| Administration panel | ||||||||
|
The administration panel is a convenient way to work interactively with PowerForm. You can start the admin panel by calling admin.cgi with your favorite web browsing software:
|
||||||||
| Admin menu... | ||||||||
|
This screen allows the following actions:
Usage
note: The top menu line provides links to all menu entries regardless
on which page you are currently. This will help you to navigate more convenient
through the software.
|
| Form creation and basic commands | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
This chapter contains all information you need to write your own PowerForm powered HTML forms. Important
note: In order to get faster results, it is helpful to be familiar
with some basics of HTML programming.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Basic form structure... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
An HTML based form may look like this simple example:
Let's explain it line
by line:
Technical
note 1: Beside of the POST method, you can also use GET to send
form content to PowerForm (see line 2).
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Command fields at a glance... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
A "command field" is a (mostly hidden) form field which controls the behavior of PowerForm and enables advanced features like autoresponders or field verifications.
* These command fields are
described in the next chapter more detailed.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Form submission recipients (recipient)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Recipient(s) of the form submission mails; comma-separate multiple entries. Example:
Usage note: This field is mandatory. It may be limited to known recipients, see "Security settings" in admin panel. Hidden form recipients: It could be a security issue to provide form recipients in clear text. The reason is that these addresses may be spidered (by automatic robots) and then used for receiving UCE (unsolicited commercial e-mail). This is especially a problem when you've whitelisted the recipient e-mail addresses in your mail filtering software (e.g. to ensure that form submissions pass an existing UCE filter). PowerForm allows to determine pre-defined form recipients at admin panel (see "Security settings"), which can be activated by the keyword $default_email provided as value of the recipient command field. Example:
It is possible to combine $default_email and visible e-mail addresses. In this case, use commas to separate each entry. Example:
Important note: In order to keep hidden form recipients really invisible to UCE senders, it is essential that their e-mail addresses are never used anywhere else (even for sending or receiving e-mails). Technical
note: If "Allowed recipient e-mail addresses" is used to limit
form recipients, then ensure that all e-mail addresses listed for $default_email
are also included in this list (otherwise sending a form is not possible).
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Subject of form submission mails (subject)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
This field allows you to specify a custom subject for the form submission mails; alternatively a pre-defined one applies. It is also possible to use field content within the subject (see example). Examples:
Important
note: Although possible, it is not recommended to include special
characters (ä, ö, ü, &, ...).
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Name and e-mail address of form sender (email, realname; visible)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Both fields should be made visible and - except of email, which is required for autoresponders, the only purpose is to appear in the header of form submission mails. Examples:
Smart
tip 1: It is recommended to use the email
field, so you have a "reply" address in form submission mails.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Redirection URL (redirect)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Each time a form was submitted successfully, PowerForm shows a standard page to the user (HTML output template). By including this command field, you can specify a given URL to be displayed instead of the standard page. Example:
Usage
note: Suited especially for "thank you" / confirmation pages
within order forms and surveys.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Required fields (required, missing_fields_redirect)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Determine required fields: Some fields of a form may be of high importance (e.g. postal address, e-mail). You can force users to fill in selected fields before form submission is processed by marking these fields as required ones: Example:
Usage note: Field names are handled case sensitive. Smart
tip 1: Use the verification feature to check required fields
for correct content.
Required field not filled in - what happens ? Standard page (default)... If a required field is not filled in, PowerForm shows a standard page to the user and asks to go back and fill out missing fields. Missing fields redirection... Alternatively you can specify a particular URL to be displayed instead of the standard page. Example:
Technical
note: The page used for redirection should state clear that
there are some missing form fields to fill in and should also contain a
link back to the form (e.g. by using a javascript:history.back()
tag). A better solution may be to customize the "standard page" (see part
"Templates" of chapter "Advanced features in detail").
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sorting of fields (sort)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
All form fields are normally shown as processed in form submission mails. However this command field allows to change the order of appearing fields, either alphabetically or according a defined list. Examples:
Technical note: The part "order:" is mandatory within this command field to sort according a defined list. Usage notes: Fields not included in the sorting list are not being sent with the form submission mails. Binary content fields are sorted by their concerned filenames, not field names (please refer to the following chapter for details). Smart
tip: Choose alphabetical sorting and start each field name with
a number (e.g. 01name, 02address, ...). In this way, you don't need to
have a long sorting list for a complex form, but still can determine the
fields' order as desired.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Environmental variables report (env_report)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
In order to get some technical info about the users filling your forms, PowerForm can retrieve environmental variables. Example:
Technical note: If a requested environmental variable is not available, it will be ignored. Smart
tip: Let PowerForm include REMOTE_HOST and REMOTE_ADDR to retrieve
details about the user's location (useful to prevent fraudulent actions,
especially when using PowerForm to process orders).
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Show command fields (print_config)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Normally command fields are not included in form submission mails. However you can determine to show selected command fields (e.g. for referencing purposes) by using this feature. Example:
Usage
note: Field names are handled case sensitive.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Show blank fields (print_blank_fields)... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Empty fields are not shown in form submission mails by default. When setting this command field to value "1", also blank fields will be included in form submission mails. Example:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Advanced features in detail | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| Autoresponders... | ||||||||||||||||||||||||||||||
|
PowerForm provides personalized autoresponders which allow to answer automatically to incoming form submissions by using customizable messages. You can create an unlimited number of autoresponders for all forms. Creation of autoresponder files: First of all, you must create a text message used for the autoresponder. This can be a short note only or a message including form fields which are replaced by the appropriate form content (as submitted). Save the autoresponder message as ASCII file and upload it to the "template.en" directory of PowerForm. Example of a simple autoresponder
message:
Example of an autoresponder
message with personalized content:
Technical notes: If a field is not available, it will be simply ignored. Field names are handled case sensitive. Binary content fields cannot be submitted in autoresponding messages, while calculated ones are allowed. HTML mails are possible. Pre-requisite for autoresponders: In order to allow PowerForm sending autoresponding messages, the form must contain the email command field to ask for a valid e-mail address of the user filling the form, like <input type=text name="email">. How to enable the autoresponder feature: Structure of the autoresponder command: <input type=hidden name="autoresp" value="{filename}"> {filename}: File holding the autoresponder message (must be located in "template.en" directory). Example:
Custom subject of autoresponder messages: You can specify a custom subject for the autoresponder messages; alternatively a pre-defined one applies. It is also possible to use field content within the subject (see example). Example:
Important note: Although possible, it is not recommended to include special characters (ä, ö, ü, &, ...). Special message content type declaration: In some cases, autoresponding messages should be sent in HTML format or a special language encoding, which requires the target mail program to receive a particular content type declaration. Structure of the encoding command: <input type=hidden name="autoresp_encoding" value="{declaration}"> {declaration}: Value html for HTML messages, value text for text messages or a complete content type declaration. Examples:
Usage
note: If a special encoding command is missing, the declaration
type "text" automatically applies.
|
||||||||||||||||||||||||||||||
| Uploading binary content... | ||||||||||||||||||||||||||||||
|
PowerForm can handle also file uploads, so people are able to send binary contents like images, programs and data files through a form. Submitted files are attached to the form submission mails (MIME compliant format) and/or stored on the server. Structure of the file uploading command: <input type=file name="upload_{field}"> {field}: Name extension, intended to give each uploaded file a unique name. Example:
Form submission mail content: The submitted files are attached to form submission mails sent to the recipient(s) by using this scheme: upload_{field}: {path/filename}, {size} bytes, {stored / not stored} upload_{field}:
Field name as specified during form creation.
Pre-requisite to enable file uploads: In order to allow file uploading, the form action tag must show an enctype attribute for a multipart form. Example:
Technical note: Although not restricted, uploaded files should not be larger than 5 MB due to limitations of some web servers and web browsing software (contact your webhosting provider for details). File uploads and save-to-file feature: It is possible to use this feature together with a save-to-file command (see next part). All submitted files are placed in different sub-directories of the "data/uploads" directory and named with their original filenames (as submitted by the user). However it's recommended
to receive uploaded files only via form submission mails, to prevent the
risk of storage capacity problems when someone submits many large files
without your consent.
|
||||||||||||||||||||||||||||||
| Save-to-file ability... | ||||||||||||||||||||||||||||||
|
Beside of receiving form submissions by e-mail, PowerForm can also save them to a database file on your server. In order to enable file storage, add this PowerForm command field to the concerned form: <input type=hidden name="storage_filename" value="{filename}"> {filename}: File containing the saved form submissions (will be created within the "data" directory automatically). Example:
Usage note: For security reasons, having at least one recipient receiving the form submission mails is mandatory. Smart tip 1: Different forms can write to the same storage file, so you are able to collect submissions from various sources. Smart tip 2: The save-to-file feature is suited for importing submissions to a database system like EasyData from SunnyScript. PowerForm uses a tab delimited storage in ASCII format with a newline character at the end of each record. Optional... Save only selected fields: In some cases, you may wish to save only selected fields to the storage file, here is the command field for this application: <input type=hidden name="store_fields" value="{list of fields}"> {list of fields}: Comma-separated list of form fields to save (field names are handled case sensitive). Optional: Enable file size warning: A warning message can be sent by e-mail when the storage file exceeds a maximum limit. The following two command fields are required to enable the file size warning feature: <input type=hidden name="max_storage" value="{size}">
{size}: Max. allowed
size in KB, before the warning message is sent.
Example:
In this example, a warning message is sent to tobias@sunnyscript.com as soon as the file exceeds 2048 KB (2 MB). Technical notes: The warning message is hardcoded and cannot be altered; 1 MB is equal to 1024 KB. Important
notes: File size warning covers only the data submitted to the
database file, not any binary uploads. New incoming form submissions are
still added, even the maximum size is exceeded (to prevent data loss).
|
||||||||||||||||||||||||||||||
| Verification of fields... | ||||||||||||||||||||||||||||||
|
Form content can be verified before further processing. If a verification procedure fails, PowerForm shows a standard page to the user telling about the occurred error (see below for available redirection command). Structure of the verification command: <input type=hidden name="{fieldname}_check" value="{conditions}"> {fieldname}: Existing
field to check against the required conditions.
Possible verification
conditions:
* Please refer to available documentation for more information about Perl regular expressions. Some application examples: Check the form field item
to contain a positive integer between 1 and 10.
Check the form field website
to contain a valid URL.
Check the form field gender
to contain either values "female" or "male".
Technical note: Please take care that verification rules are used in a logical way (e.g. "negative;alpha" would not work). Smart tip: Field verification has priority before field calculation, so you can check fields intended for calculations first. Redirection in case of failed verification: By default, a standard page is displayed telling about a failed verification. Instead of, you can also specify a particular URL. Example:
Technical
note: The page used for redirection should state clear that
some verifications failed. A better solution may be to customize the "standard
page" (see part "Templates" of this chapter).
|
||||||||||||||||||||||||||||||
| Calculations with fields... | ||||||||||||||||||||||||||||||
|
You can process calculations based upon the form content. Each calculation creates a new form field containing its result. It is possible to perform arithmetic calculations, string manipulations and even execute complex Perl scripts. Any kind of operator can be used, which is supported by Perl (e.g. if, else, elsif, while, foreach, next and others) as well as all mathematical operators (e.g. +, -, *, / and others). Important note: Before using Perl scripts for calculations, you should be familiar with the basics of this programming language. Structure of the calculation command: <input type=hidden name="calculation_{fieldname}" value="{calculation string}"> {fieldname}: New
field created and intended to contain the result of calculation.
Smart tip: Calculations are done after verifications, so you can verify fields first for suited contents. Example of simple arithmetic: <input type=hidden name="calculation_result" value="([amount1]+[amount2])/[age]"> A new field result is created, containing the result of [amount1]+[amount2])/[age]. Usage note: Fields involved in the calculation string must be enclosed by square brackets, e.g. [field1]. Example of complex calculations (if / then / else): <input type=hidden name="calculation_subtotal" value="
Expert note: Only single quotes are allowed inside the calculations (to avoid conflicts with HTML language specifications). Expert
tip: You can use the calculation feature to build your own tiny
shopping solution (e.g. determine subtotals, total amount and taxes; in
an enhanced way also shipping fees, required delivery time and more).
|
||||||||||||||||||||||||||||||
| Auto-numbering and random fields... | ||||||||||||||||||||||||||||||
|
Auto-numbered fields: This command field lets PowerForm create an auto-increased number as value for a specified field. Possible applications are to provide an individual ID to each user submitted a form (e.g. for later referencing purposes or as order identification) or to build "intelligent forms" with verification and calculation parts requiring an auto-increasing value. Structure of an auto-numbered field... <input type=hidden name="{fieldname}" value="<auto-number:autoinc({filename})>"> {fieldname}: Name
of the field containing the auto-increased number.
Usage notes: In order to start an auto-numbered field from 0 again, just go to the "data" directory and remove the concerned counter. You can use an infinite number of fields basing on different counter files and even fields accessing the same counter. Examples:
Technical notes: Auto-numbered fields are created before field verifications and calculations, so these fields can be used for calculations. Additional text parts surrounding the generated value are also allowed (see second sample). Random numbered fields: This command field lets PowerForm create a random number as value for a specified field. Possible applications are to provide an individual ID to each user submitted a form (e.g. for later referencing purposes or as order identification) or to build "intelligent forms" with verification and calculation parts requiring a random value. Structure of a random numbered field... <input type=hidden name="{fieldname}" value="<auto-number:{start}-{end}>"> {fieldname}: Name
of the field containing the auto-increased number.
Technical notes: Leaving the start and end range, a random number between 0 and 1 is generated. Depending upon the internal server configuration, the entire string length may be anything between 3 and 17 digits. Examples:
Technical notes: Randomly numbered fields are created before field verifications and calculations, so these fields can be used for calculations. Additional text parts surrounding the generated value are also allowed (see third sample). Combination of auto-numbering and random numbers: It is also possible to combine both features, e.g. to get a random value with an unique auto-increased component. Example:
Creates a field
OrderID
with an auto-increased value, followed by a fix text part and a random
number, e.g. "8-abc03790".
|
||||||||||||||||||||||||||||||
| Templates... | ||||||||||||||||||||||||||||||
|
Form submission mail template: Whenever PowerForm sends submission mails to form recipients, the template admin.txt located within the "template.en" directory is used to generate the message structure. In order to achieve a custom layout, you can either modify this file directly (don't forget to create a backup copy first) or instruct PowerForm to use a specific submission mail template of your choice: <input type=hidden name="mail_template" value="{filename}"> {filename}: Mail template file, which must be located at the "template.en" directory. System tags used in this
template:
Sample form submission
mail template:
Usage note: In this way, you can also only pass through selected fields (rest may be stored in a file). HTML output template (the so called "standard page"): Whenever PowerForm finished a form submission successfully or experienced an error (e.g. failed verification, missing required field), the template result.htm located within the "template.en" directory is used to generate the page structure. In order to achieve a custom layout, you can either modify this file directly (don't forget to create a backup copy first) or instruct PowerForm to use a specific HTML output template of your choice: <input type=hidden name="templatefile" value="{filename}"> {filename}: HTML output template file, which must be located at the "template.en" directory. Technical note: The HTML output template will be ignored, if a redirection command field takes effect. System tags used in this
template:
Displaying fields in this template: Furthermore it is possible to use any field from your form also on the HTML output template (format: <!--$field-->). Hereby field values are passed through in HTML-safe format (e.g. "<" character is replaced by "<" to avoid destroying the layout). Technical notes: When using fields having the same names as above stated special tags, these tags are processed instead of (they have a higher priority compared to common fields). Non-existing fields or empty field values are ignored. HTML error output template: Whenever PowerForm is unable to process a form submission, it either redirects to a set URL or displays error messages by using the standard page (default result.htm). But it is also possible to specify a separate template for this purpose by adding the following system field: <input type=hidden name="errortemplatefile" value="{filename}"> {filename}: HTML error output template file, which must be located at the "template.en" directory. Technical note: The HTML error output template will be ignored, if a redirection command field takes effect. Displaying system tags and fields in this template: As for templatefile, you may use system tags and field values also here. Maintaining templates: You may alter existing templates or create new ones with a text or HTML editor of your choice (depending upon the template). However a more convenient way is to use the integrated templates editor accessible via admin panel. There you also find further information about existing templates delivered with the software package. For each template you create,
an informational header can be added containing internal comments and notes
not appearing at the template itself. Furthermore it is also possible to
copy&paste source code from an outside editor.
|
||||||||||||||||||||||||||||||
| Multi-page forms... | ||||||||||||||||||||||||||||||
|
Another powerful feature is the ability to split long forms (e.g. job applications) or complex processes (e.g. shopping checkouts) into several smaller ones by spreading one form over multiple pages. This way is called "multi-page" forms. Guidelines for creating multi-page forms: First page of the form: 1. Just use a common initiating form action tag to start. Example:
2. Add this hidden field to indicate starting a multi-page form: <INPUT type="hidden" name="multipage" value="1"> 3. Add this hidden field to let PowerForm know the next page of the multi-page form: <INPUT type="hidden" name="templatefile" value="{nextpage}"> {nextpage}: Filename of the second form part (see following notes). Technical note: Please note that templatefile has two different meanings here; specifying a custom HTML output template (common intention of this command field) is possible at the last form part (refer below for details). Further pages of the form: 1. Use the same initiating form action tag as done for the first page. Example:
2. Add this hidden field to indicate that the next page is also part of the multi-page form: <INPUT type="hidden" name="multipage" value="1"> 3. Add this special tag to let PowerForm hand over all fields from previous pages: <!--$PREVIOUSFORM--> 4. Add this hidden field to let PowerForm know the next page in range: <INPUT type="hidden" name="templatefile" value="{nextpage}"> {nextpage}: Filename of the next form part. Last page of the form: Equal as before, but now set the command field "multipage"'s value either to zero or skip this command field entirely. Examples:
Technical note: You can now use the command field "templatefile" to specify a custom HTML output template. Uploading and testing multi-page forms: After creating the form pages, please put all files (except the first one, which can reside at its original location) into the "template.en" directory. For security reasons, all follow-up form parts are taken from this directory only. Helpful hint: You may use the templates editor for creating these pages or just copy&paste forms created with an HTML editor. In this way, you do not need to log in by ftp for transferring files or doing later modifications. Now give it a try by calling the first form page. If anything is done correctly, the "Submit" button of the first page leads to the second form part located at "template.en" directory and then to the third one, etc.. Implementation notes: SSL encryption may work also at multi-page forms depending upon the way your server handles it (SSL access must be server-wide available, not limited to a particular directory). By using tags like <!--$field-->, it's possible to take over field values from previous parts for being displayed at the current part; values are passed through in HTML-safe format (e.g. "<" character is replaced by "<" to avoid destroying the layout). Fields used to upload binary
content (upload_{field})
have to be placed at the last form part only.
|
| Customer services |
|
Depending upon your license type, this software package includes various support services. Please refer to the license document or visit our website for more information about available services. Before you contact our customer service department, please read this manual first. In most cases you find the answer here. However if you still experience problems, we will be more than happy to help you... For all support inquiries, please contact support@sunnyscript.com and provide the following information: * The license number of the
concerned product.
|
|
|
| © SunnyScript
- A subsidiary of Star Enterprise.
Visit the
SunnyScript website.
Please read our terms of business located at... http://www.sunnyscript.com/terms.htm |