This script requires Perl on either a UNIX or WINDOWS server. All you need is a cgi-bin.
Configuration
This Script requires no Configuration, however if you have trouble installing the Script, you can hard code some values in the _key.cgi file.
Exporting Data
To export Survey Submissions to as CSV files, you must open the esurvey_key.cgi file and enter your website domain name in the $ExportURL variable.
Installation - Linux/Unix/Mac Servers
[script] refers to the first portion of the name of the CGI Scripts you purchased.
Setting the Path to Perl. Open all CGI Scripts (except [script]_key.cgi) in a Plain Text Editor and make sure the first line of the CGI Script is the Path Perl for your server. Most Users can skip this step being the default Path to Perl shipped in the CGI Script is very common.
NB: if you do not you a Plain Text editor such as Windows NotePad or Mac Textedit (in Plain Text Mode), your Text/HTML editor will add extraneous code to the CGI Script when you save it which will result in a server 500 Error.
Upload all CGI Scripts to your cgi-bin or any cgi enabled
directory and CHMOD
all the CGI Scripts to 755. It is imperative that you upload (transfer) all CGI Scripts to your server in ASCII mode.
If you forget to CHMOD all CGI Scripts to 755, Step 3 will
yield a Server 500 Error.
If you do NOT upload (transfer) all CGI Scripts to your
server in ASCII mode, Step 3 will yield a Server 500 Error.
Load your Browser, point it to the [script]_setup.cgi file and follow the on-screen instructions for installation. For example, in your browser, type :
Enter a Username and Password. This will be your Username and Password for the Administration Section. If the Setup Routine is successfully processed a link to the Administration Section will appear on the resulting page. Click the link to access the Administration Section with the Username and Password you just entered in the Setup Script.
Should you encounter any Permission problems with the Setup Routine follow the instructions returned by the Script.
Upon successful completion of the Setup Routine the [script]_setup.cgi_setup.cgi script attempts to delete itself. This ensures the Setup Routine can not be repeated by another Surfer who would effectively reset your Administration Section Username and Password. Manually delete the [script]_setup.cgi
CGI Script you uploaded if the Setup Routine could not automatically
delete it (Refresh your FTP directory listing to check).
Should you ever forget your Administration Section Username and Password you can repeat this Step to set a new Username and Password.
Common Installation Problems - Linux/Unix/Mac Servers
NB: Shared Secure Servers, VPS, SBOX and Free Servers.
Server 500 Error. This most often occurs because Step 2 was not followed precisely. Make sure the CGI Scripts you are uploaded are CHMOD to 755, the folder the CGI Scripts reside in is also CHMOD to 755, and the CGI Scripts were transferred in ASCII Mode. Auto-Detect only detects the extensions you specify in your FTP client's Settings.
I can initially load the Setup Script and punch in my Username and Password, but when I submit the Form, I receive 404 Error Page or an alternate Error Page stating "Page Cannot be found".
This suggests your Server is operated by a very nervous System Administrator employing strict security measures, you're using a Shared Secure Server which dynamically sets your domain name to something other than the a standard Top Level Domain (www.yourdomainname.com) or sbox is employed by your server.
In any case, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and enter the URL to the folder you uploaded the CGI Scripts to in the $SecureServer Variable. If you uploaded the CGI Scripts to your cgi-bin, then you'd set the following:
Do NOT enter the CGI Script name, do NOT enter a trailing slash. After setting the Variable refresh the Setup Routine's Page that asks you to enter your Username and Password. Unless you refresh the initial Setup Page, the Form's URL will not be updated to reflect your Variable value.
I cannot find the correct path to my WebSpace or the required Data Directories and/or Password file cannot be created.
You need to find that Path. Ask your host, or Download a copy of our free E-Vars CGI Script and install it on your server. CHMOD it to 755 then load it in your Web Browser which will print your Server's environment variables and other useful information. Determine your Server's Document_ROOT or Absolute Server Path to the folder your home page (index.html) resides in. You may need to append "/www" or "/httpdocs" to your Document_ROOT or Absolute Server Path to complete the path to your Writable WebSpace.
Once you've determined your Absolute Server Path, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and set the $DefaultData Variable. For example:
$DefaultData = "/var/username/www/htdocs";
Finally, on some Server's it's necessary to CHMOD the folder just above your WebSpace to 777 granting permission to the CGI Script to create the Required Directories at WebSpace Level. In the example above, the "htdocs" folder would need to have it's permissions set to 777.
We offer a very reasonably priced Custom Installation Service. We'll Setup the CGI Script for you and send you the Log in details which you can update at your own leisure. If we cannot successfully Setup the CGI Script we will refund both the Installation fee and the purchase price of the CGI Script. To Order Custom Installation, please fill in our Secure Installation Order Form.
Installation - Windows Servers
[script] refers to the first portion of the name of the CGI Scripts you purchased.
Your Windows Server may not execute CGI scripts even if Perl is Supported. Many Server Administrators do not modify the Registry to accommodate Scripts with a .cgi extension. In this case, contact us for a copy PL Version.
Setting the Path to Perl. Your Server may or may not require the Path to Perl. It's highly likely you don't need it, and you can ignore this Step. However you may want to check with your Host if you can not load the Setup Script in your web Browser.
NB: if you do not you a Plain Text editor such as Windows NotePad or Mac Textedit (in Plain Text Mode), your Text/HTML editor will add extraneous code to the CGI Script when you save it which will result in a server 500 Error.
Upload all CGI Scripts to your cgi-bin or any cgi enabled directory. It is imperative that you upload (transfer) all CGI Scripts to your server in ASCII mode.
If you do NOT upload (transfer) all CGI Scripts to your
server in ASCII mode, Step 3 will yield a Server 500 Error.
Load your Browser, point it to the [script]_setup.cgi file and follow the on-screen instructions for installation. For example, in your browser, type :
Enter a Username and Password. This will be your Username and Password for the Administration Section. If the Setup Routine is successfully processed a link to the Administration Section will appear on the resulting page. Click the link to access the Administration Section with the Username and Password you just entered in the Setup Script.
Should you encounter any Permission problems during the Setup Routine, you need to contact your Host and request "Full Read/Write Permissions" be applied to at least one folder on your Server. Many Servers have at least one writable folder, often named "database". See Common Installation Problems below for more information.
Upon successful completion of the Setup Routine the [script]_setup.cgi_setup.cgi script attempts to delete itself. This ensures the Setup Routine can not be repeated by another Surfer who would effectively reset your Administration Section Username and Password. Manually delete the [script]_setup.cgi
CGI Script you uploaded if the Setup Routine could not automatically
delete it (Refresh your FTP directory listing to check).
Should you ever forget your Administration Section Username and Password you can repeat this Step to set a new Username and Password.
Common Installation Problems - Windows Servers
NB: Shared Secure Servers, VPS, SBOX and Free Servers.
Server 500 Errors are usually misleading on Windows Servers. It seems to be the default error page for just about every error. Make sure you typed in the correct Website Address (URL) to the CGI Scripts on your server. Make sure the CGI Scripts were transferred in ASCII Mode. Auto-Detect only detects the extensions you specify in your FTP client's Settings.
I can initially load the Setup Script and punch in my Username and Password, but when I submit the Form, I receive 404 Error Page or an alternate Error Page stating "Page Cannot be found".
This suggests your Server is operated by a very nervous System Administrator employing strict security measures, you're using a Shared Secure Server which dynamically sets your domain name to something other than the a standard Top Level Domain (www.yourdomainname.com) or sbox is employed by your server.
In any case, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and enter the URL to the folder you uploaded the CGI Scripts to in the $SecureServer Variable. If you uploaded the CGI Scripts to your cgi-bin, then you'd set the following:
Do NOT enter the CGI Script name, do NOT enter a trailing slash. After setting the Variable refresh the Setup Routine's Page that asks you to enter your Username and Password. Unless you refresh the initial Setup Page, the Form's URL will not be updated to reflect your Variable value.
I cannot find the correct path to my WebSpace or the required Data Directories and/or Password file cannot be created.
You need to find that Path. Ask your host, or Download a copy of our free E-Vars CGI Script and install it on your server. You will need to rename the E-Vars CGI Script to "myserver.pl" if your Server only executes Scripts with .pl extensions. Upload it to your cgi-bin or any cgi executable folder then load it in your Web Browser which will print your Server's environment variables and other useful information. Determine your Server's Document_ROOT or Absolute Server Path to the folder your home page (index.html) resides in. You may need to append "\\www" or "\\httpdocs" to your Document_ROOT or Absolute Server Path to complete the path to your Writable WebSpace.
Once you've determined your Absolute Server Path, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and set the $DefaultData Variable. Be sure to separate folder names with two backslashes, not one slash. For example:
$DefaultData = "C:\\html\\username\\htdocs";
We offer a very reasonably priced Custom Installation Service. We'll Setup the CGI Script for you and send you the Log in details which you can update at your own leisure. If we cannot successfully Setup the CGI Script we will refund both the Installation fee and the purchase price of the CGI Script. To Order Custom Installation, please fill in our Secure Installation Order Form.
License and Disclaimer
The following constitutes an agreement between you (the end user/purchaser) and us, PerlScripts JavaScripts.com (a wholly owned subsidiary of InterActive Scripts). By purchasing and using our software, products or services you agree to and accept the licensing agreement stated on this page. All documentation, goods and services are provided "as is" and without warranty. We hereby disclaim all warranties relating to any documentation, goods and services, whether express or implied, including warranties of suitability. In no event shall we be liable for any direct, indirect or consequential damages resulting in loss of revenue or data, incurred by you or any of our products, information or services. We reserve the right to revise the terms and conditions stated on this page at any time without notice. You agree to be bound by such revisions, and you are encouraged to periodically revisit this page to review the then current terms and conditions.
We grant you the right to use one copy of the software, product or service purchased, for testing and familiarization purposes. We also grant you the right to implement, install and use one copy of the software, product or service purchased on a single web site domain for use by one entity once the evaluation copy is removed / deleted.
By purchasing a product you are also subscribing to our periodic newsletter which will notify you of new software releases, updates and special offers. In accordance with United States and International anti-spamming laws, an unsubscribe link that removes you from all future mailings will accompany each e-mail notification.
For taxation purposes, we must keep accurate transaction and installation records. At the time of software installation, you will be asked to enter information such as your web site's domain name and your product's serial number. This information is used to validate copies of our software.
We reserve all rights. Written permission must be obtained from us before you may copy, reproduce, publish, modify or alter in any way, any media, software, documents or products, in part or in whole, contained within our web site or traded by us. All media, software, documents and products are the property of PerlScriptsJavaScripts.com. We retain ownership and copyright of software products purchased from us and all copies of the software. As a licensee you may make one copy of the software product solely for backup purposes. Removal of any copyright messages, publicly visible or otherwise without prior written permission from us is expressly forbidden. Unauthorized reproduction of any of our software, documents or products is prohibited by Federal and International laws and subject to criminal prosecution.
Any use of software and accompanying documentation on our Web site is subject to the terms of a software license agreement between you and us. You must read this license agreement in it's entirety and agree to it's terms prior to installing or using the software. All ownership rights and rights not implied are reserved. We reserve the right to revoke these permissions and terminate this agreement at anytime or at it's own discretion without reasonable notice. We reserve the right temporarily or permanently discontinue any software product or the support associated the product at anytime or at it's own discretion without reasonable notice. You agree and accept that we shall not be liable to you or to any third party for any such cessation.
You agree that any issue or dispute that may arise between PerlScriptsJavaScripts.com and yourself in respect to this web site or it's goods or services will be resolved and governed by and within the courts and laws of Melbourne Australia. If your local laws do not allow for such an agreement, you must delete all copies of products supplied to you by us and you are hereby notified of the termination of this license.
eSurvey Summary
eSurvey, and eSurvey Plus, are Perl scripts which you can install on your web server to enable you to run and manage an unlimited number of Web surveys created by you and displayed anywhere on your website. No special software is required by you or your website visitors.
Upon successful installation of the program, you'll be presented with a link to the Admin section. Log in to the Admin section and you'll see a list of current Surveys (if you have created any). To create a new Survey, click on the "Create new" link and enter any name for the Survey. This will create a data folder on the server to store the Survey's results as well as all data files associated with the particular Survey.
The Summary page provides navigation to all sections of the program, as well as a Summary of submissions for each Survey in the system.
Creating Surveys
Two steps are involved in creating a new Survey. First you must enter a Reference name for the new Survey. This can be anything you like. This first step creates a dedicated folder in eSurvey's data directory which stores all data pertaining to the Survey. The second Step is of course constructing the Survey with Questions.
To Create a new Survey :
1. Click the Create new link in the Main Control Panel
Adding new Questions to your Survey is a simple and intuitive process. eSurvey Supports the following types of form fields. Choose the type you feel is the most appropriate for the Question being asked.
Radio buttons
Radio buttons are suitable for multiple choice Questions which require no more of less than one selection by the Survey taker. i.e. a maximum of one selection.
Checkboxes
Checkboxes are suitable for multiple choice Questions which allow the Survey taker to make one or more selections from the available list of Answers.
Text field
Text fields are suited to Questions that require the Survey taker to manually type in a short Answer, such as an email address or name.
Textarea
Textareas are suited to Questions that require the Survey taker to manually type in long Answers with line breaks preserved, such as comments or instructions.
File upload
File upload fields allow the Survey taker to upload files to your server, which can also be delivered to your inbox via the Admin e-mail notification.
Supplementary text fields allow you to ask follow up or supplementary Questions, such as : What did you dislike about the event?; Do you have any other favorites not listed here?; Supplementary Text fields accompany the critical Question.
To Add a new Question :
1. Select the desired Survey, then the Edit Questions action
2. Scroll down to the "Add a new Question" form
3. Select the Question type
4. Optionally enter instructions for the Question
5. Enter the Question
6. Enter all possible Answers if this is a multiple choice Question (one Answer per line)
7. If this is a Multiple choice Question, select whether Answers should be printed on one line (Horizontal) or one per line (Vertical)
8. Optionally type in a Supplementary Question. Leave blank to omit.
9. Press the Button labelled "Add Question"
Notes :
Question types cannot be edited. You must delete then re-add the Question to modify the type.
Instructions can utilize standard HTML formatting and are displayed just above each Question.
Answers are only absorbed in to the database if the Question type is a Radio or Checkbox field.
Email address
eSurvey encrypts each form field's name to ensure proper functionality of checkbox and radio button fields. Given the nature of the form field name generation it is impossible for eSurvey to know which of your fields are the contact fields. Hence we've built in a feature that allows you to designate them and enable eSurvey to send Autoresponders. Simply enter the fields as you normally would, then follow the steps below to designate the e-mail address, first name and last name fields.
To set the Contact Fields :
1. Select the desired Survey, then the Edit Questions action
2. Create a text field requesting the Survey taker's e-mail address, first name or last name
3. When the page reloads and all Questions are listed, select which of the Questions requests what information. The EM column specifies the e-mail field. The FN column specifies the first name field. The LN column specifies the last name field.
4. Press the button labelled "Re-order Questions"
Notes :
If you've made a mistake and want to dissociate the contact fields, scroll down to the bottom of the list of Questions and select one or more of the Deselect Radio buttons.
The Question designated as the e-mail address is validated for a properly formatted e-mail address before a submission is accepted by eSurvey.
Editing Questions
Once Questions have been input in to the database they can be subsequently edited individually, re-ordered by batch or set as required fields by batch.
To re-order the Questions in a Survey :
1. Select the desired Survey, then the Edit Questions action
2. In the list of current Questions, in the Pos column enter the numeric position for each Question.
3. Press the button labelled "Re-order Questions"
Notes :
Questions with lower numerals are displayed higher up on the Survey
We suggest you enter numerals in multiples of 10 or 100 for easier management when it comes to adding new Questions. i.e. Question 1 could have a value of 10, while Question 2 has a value of 50. This does not slow down rendering time.
To set Questions or fields as required :
1. Select the desired Survey, then the Edit Questions action
2. In the list of current Questions, tick all boxes in the Req column that should force the Survey taker to supply an Answer.
3. Press the button labelled "Re-order Questions"
To Edit a Question :
1. Select the desired Survey, then the Edit Questions action
2. Click the desired Question (displayed as Green links)
3. When the page reloads, scroll to bottom of page to modify the Question's parameters
4. Press the button labelled "Edit Question"
Notes :
Existing Questions cannot have their Type changed. You will need to delete then re-create the Question
Deleting Questions removes submitted Answers from the database of submissions and Survey results
Deleting Questions
To Delete Questions :
1. Select the desired Survey, then the Edit Questions action
2. In the list of current Questions, tick all boxes in the Del column that are to be deleted from the Survey
3. Press the button labelled "Re-order Questions"
Notes :
Deleting Questions removes submitted Answers from the database of submissions and Survey results
Survey Settings
Each Survey has it's own configuration area. These Settings govern the functionality of each Survey, as well as the aesthetical appearance of the Public Form. From here, you control colors, e-mail autoresponder templates, file upload locations, Thank you pages, Header and Footer for the Public Form and more. Scroll through all settings, taking the time to click on each of the Option titles for more information.
To configure a Survey's Settings :
1. Select the desired Survey, then the View Submissions action
2. Enter desired configuration
3. Scroll to bottom and press the button labelled "Save Settings"
Notes :
When creating new Surveys, the program's Default Settings are copied over and used as the defaults for the new Survey,
Resetting Surveys
If you'd like to purge a Survey of all submissions, but retain the Survey's Questions and configuration, use the Reset function. This function is useful once you have completed testing a newly created Survey.
To Reset a Survey's Results :
1. Click on Summary in the Main Control Panel
2. Click the Reset link in the row displaying the desired Survey
3. Click "OK" to confirm you want to purge the Survey
Notes :
There is no repeat confirmation. Purging takes place immediately you press the "OK" button.
Deleting Surveys
Creating a Survey creates a dedicated for all data files pertaining to the Survey. Deleting a Survey deletes this folder and hence all data associated with the Survey is permanently deleted, including settings and submissions.
To Delete a Survey :
1. Click on Summary in the Main Control Panel
2. Click the Delete link in the row displaying the undesired Survey
3. Click "OK" to confirm you want to delete the Survey
4. Click the button labelled "Delete This Survey" to permanently delete all data.
Notes :
Deleted data is irretrievable.
Viewing Results
Survey results are illustrated by number of selections, percentage of selections against number of possible Answers, and horizontal bar graphs. Each Answer for multiple choice Questions is listed in the order in which you entered them. Questions that require manually typed Answers, including supplementary Questions, are hidden by default when viewing Results. To view manually typed Answers, click the link titled Show/Hide manually typed Answers adjacent to the desired Question.
To View Survey Results :
1. Select the desired Survey, then the View Results action
Viewing Submissions
Each Survey Submission made is stored in a flat file database and can be viewed individually. Submissions are listed chronologically (most recent submission last). Individual submissions can be viewed and deleted. The Submission Synopsis table headers can also be controlled by you, allowing you to quickly view the most significant Answers. Column Headers are determined by the Show column when editing Questions. Simply enter a name for the Column Header.
To View Submissions Individually :
1. Select the desired Survey, then the View Submissions action
2. Click on the Submission Date to view a specific submission
Notes :
To delete one or more Submissions, place a tick in the Checkbox beside the date of submissions to be deleted and then Press the button labelled "Delete selected"
Deleted Submissions effect and update Survey Results
Exporting Data
eSurvey has a built in Export Wizard which allows you to export all submissions for each individual Survey. Data is printed to a .csv file and stored on your server. If a copy of Microsoft's Excel resides on your computer, it will automatically load the data file created. Otherwise the data is loaded in to your web browser as a Plain Text file. In the later case, you should view the source code and save it as a Plain Text file, as the web browser will string all data lines together to produce one long line of illegible data. Data files are named using the Reference name of the Survey with the current date appended. Data files can be automatically deleted from the server by modifying the CSV File deletions setting in your Default Settings.
Note the if you are receiving a 404 (file not found error), you need to modify the $ExportURL variable in your eSurvey_key.cgi script (line 34) so that it points to your website domain name. (This is no longer required as of Version 3+)
To Export Data :
1. Select the desired Survey, then the Export Data action
2. Change or remove the column numbers
3. Press the button labelled "Export"
Notes :
Survey Questions are printed in the first row of the exported data.
If a column has no numeric value, the Question/Answer set is not exported
Substitution Markers
Substitution Markers enable you to include variable data in Email Autoresponders and the Thank You page Template. Each marker must be padded by 3 percentage signs on either side. Any invalid markers or markers which can be determined will not show up in the email Autoresponders or the Thank You page. The following table shows all available markers and description of each.
Marker
Description
%%%GroupGraphImage%%%
A regular HTML <img> tag pointing to the Graph generated when creating Surveys with multiple categories. Graph is a Polar graph which tallies the scores in each category. This can be displayed on Thank You pages or inserted into HTML email Autoresponders.
%%%GroupGraphLink%%%
A link that points to the GroupGraph. This will be a URL when using Plain Text email notifications, or a <a href> tag in HTML email notifications and on the Than You page.
%%%ResultsLink%%%
A link that points to the Public Page showing Survey tallies. This will be a URL when using Plain Text email notifications, or a <a href> tag in HTML email notifications and on the Than You page.
%%%snapshot%%%
The entire survey and user selected answers.
%%%score%%%
The score calculated based on points assigned to multiple choice answers.
%%%maxscore%%%
The maximum score achievable based on points assigned to multiple choice answers. Radio button multiple choice answers will compute the highest available score per question, checkboxes will compute all available scores.
%%%percentage%%%
The percentile calculated based on points assigned to multiple choice answers. E.g. if a User scored 16 out of a possible 20, 80% would be returned.
%%%remark%%%
The remark associated with the percentile scored. Each percentile has it's own remark which you can edit at the very bottom of each Survey's settings.
%%%Date%%%
The Date and Time the User submitted the Survey.
%%%Files%%%
Full list of files attached to the Survey by the User
%%%UID%%%
Unique Submission ID assigned to each Survey Submission. The starting number can be set in each SUrvey's Settings just above the Admin Notification Template. This number is then incremented by one with each Submission. You can only increase this number, not decrease it.
%%%IP%%%
The IP Address used to submit Survey.
%%%Host%%%
The User's Host node, if one can be determined. This information contains details about the User's ISP
%%%Referrer%%%
The page the Survey is located on.
Additionally, each Survey's Questions can have the associated input included in email notifications and the Thank You page. You'll find all available markers for each Survey in the Survey's Settings. Simply focus on the template where you would like the marker inserted, select the Marker and click the button. For example, to insert the User's First Name into the Than You page, your template would look something like this :
Your first name is : %%%Surv_Text_1089051074%%%
Changing your password
Enables you to update or change the Administration log in details. Enter your current log in details, enter your new log in details and press the button labelled "Change Pass".
