phpQuestionnaire v3.12 User Manual
 
Table of Contents
    1) Getting Started
        1.1) Automatic Installation
        1.2) Logging in as Administrator
        1.3) Administrator Panel Sections

    2) Survey Overview

    3) Survey Editor
        3.1) Adding or Modifying a Survey
        3.2) Previewing a Survey
        3.3) Survey Activation/Deactivation
        3.4) Deleting a Survey
        3.5) Exporting a Survey
        3.6) Importing a Survey

    4) Question Editor
        4.1) Adding or Modifying a Question
        4.2) Preview a Question
        4.3) Deleting a Question
        4.4) Changing Question Order
        4.5) Create Page Breaks in Question Order
        4.6) Create Conditional Branches in Survey Questions

    5) Survey Results
        5.1) Selecting a Survey
        5.2) Survey Summary
        5.3) Viewing Question Results
        5.4) Removing a Survey Response
        5.5) Downloading Survey Results
        5.6) Cross Tabulation

    6) Configuration
        6.1) Set Administration and Survey Defaults
        6.2) Change Administrator Password
        6.3) Backup Database
        6.4) Restore Database
        6.5) Rate this Script

    7) Additional Information
        7.1) Templates
        7.2) Languages
        7.3) Populating Hidden Question Types
        7.4) Manual Installation
        7.5) XML Format
        7.6) Getting Support


1) Getting Started

Once you have purchased a copy of phpQuestionnaire, you will be given a link that allows you to download the current version. Depending on your operating system, you should grab one of the following packages:

Microsoft Windows
Download the file phpq.zip and use a program such as WinZip to extract the files. You should upload or place this entire hierarchy onto your web server. It will unpack into a directory named 'phpQ'. You will need to know how to access this directory on the web to properly install the script.

NOTE: If you are using Windows XP, it has built-in support for .zip files. Simply use the compressed folder feature of Windows XP to extract the files.

Unix, Mac OS X
If you are using a Unix based operating system (Linux, BSD, Mac OS X, etc.) you will need to download the file phpq.tar.gz. Once you have retrieved this file, you should place it in a directory on your web server and enter the following commands:

gunzip phpq.tar.gz
tar xvf phpq.tar

It will unpack into a directory named 'phpQ'. You will need to know how to access this directory on the web to properly install the script.

1.1) Automatic Installation

Once you have unpacked the program as detailed above, you can now begin the process of automatic installation. You must perform the following steps in the order they appear below:

  1. When unpacking the files, they will all be placed in appropriate locations within a base directory of 'phpQ/'. Move or Upload this directory onto your web server into a location accessible from your browser.

    NOTE ON UPGRADING: If you are upgrading from a previous version of phpQuestionnaire, we recommend backing up your current version in case you have any problems. Furthermore, there have been numerous changes in 2.0, including some that can affect the way a survey appears to the user. We strongly recommend setting up v2.0 in a parallel directory, upgrading the database (using the Upgrade option in the install.php file) and then testing your existing surveys. If everything looks good, you can then move the new version, overwriting your existing files (which you should backup) and the upgrade will be live. NOTE: Be careful if you have made changes to your current version. For instance, do not erase any templates you may have created or modified and if you have changed any other files in phpQ, your modifications may be lost if you have not properly backed them up to another directory. If you encounter any problems with the automatic upgrader (it can update any version prior to 2.0) please let us know.

  2. If phpQ is being hosted on a Unix based machine, you must change the permissions of the file 'phpQ/inc/mysql.php' so that your web server can write them. To do this, you must telnet, ssh or ftp into your machine and issue a 'chmod' command to change the permissions. To do this, login and go to the phpQ/ directory of your installation. Issue the following command:

    chmod 766 inc/mysql.php

    This step is necessary, even if upgrading, so that the automatic installation program can write your MySQL configuration. At the end of the installation we will ask you to change permissions on this file again.

  3. Load up the installation page by opening your web browser and going to the following URL:

    http://www.yourhost.com/path/to/phpQ/install.php

    You must modify this URL to include your actual domain and then the 'path/to' must be changed to the location on your web server where you have placed your phpQ program.

  4. You will now see a page in your web browser that looks like:

    Figure 1.1-01
    Figure 1.1-01 - Automatic Installation

    The Language option will only appear if you have multiple administrative language packs installed. If so, you can install in that language and it will become the admin and default language for phpQ.

    You must fill in the correct MySQL configuration variables. If you are unsure of any of the MySQL configuration parameters, please consult your web hosting provider.

    • MySQL Hostname
      In most cases, the MySQL Hostname should be set to 'localhost'. This is the most common configuration, in which both the MySQL server and the web server are running on the same machine.

      In some cases, your MySQL database may be running on a different machine from your web server. If this is so, you must enter the hostname of the MySQL database server here.

    • MySQL Username
      MySQL Password

      Logging into a MySQL database server requires a username and password. This may be different from the username and password you use to access your web server.

    • MySQL Database
      phpQuestionnaire needs to know the MySQL database to which it should add the configuration and survey tables. If you are able to create databases, you may wish to create one named 'phpQ'. In either case, please enter the name of your MySQL database into this box.

    If you are upgrading an existing set of phpQ tables to the newer version, you will also need to supply the Admin Password to prove that you are authorized to make this change. This password will be the same one you have been using to login to the phpQ admin control panel.

    Next to the upgrade button you will notice there is an option to 'Backup Database'. We recommend you click on this button before upgrading. Once clicked, you will be prompted to download a .phpQ file which contains all of the data from your phpQ installation. This file can then be used to restore your database in the very small chance something goes wrong with the upgrade. Starting with version 1.2, you can now backup your database at any time.

    You may now click the 'Install' or 'Upgrade' button depending on which you wish to do and phpQuestionnaire will automatically perform the requested action, alerting you to any errors it may encounter.

  5. Upon successful installation, you will see the following screen:

    Figure 1.1-02
    Figure 1.1-02 - Automatic Installation : Success

  6. If all of the items say success, phpQ has been correctly installed. Once you have checked to see that it is working, you need to change the permissions of your mysql.php configuration file back to normal, so that no one else may modify your database parameters. To do this, issue the following command, much like you did before:

    chmod 644 inc/mysql.php

  7. It is crucial that you also remove the install.php file once you have successfully setup phpQ. You need to delete the file 'phpQ/install.php' possibly using the following command (if you are still in the phpQ/ directory of your installation):

    rm install.php

    It is important to do this so that no one else may access this file in the future and create a new installation of phpQ without your authorization.

  8. Click the Done button shown in Figure 1.1-02 which will take you to Logging in as Administrator for the first time.

If for some reason the automatic installation fails or you wish to do a manual installation, you can follow the steps outlined in section 7.4 - Manual Installation.

1.2) Logging in as Administrator

When logging into the phpQuestionnaire administration section, you will be presented with a screen that looks like:

Figure 1.2-01
Figure 1.2-01 - Admin Login

For the first time...

If you have just installed phpQ and this is your first time logging in, you should enter the default login password, which has been configured as 'password' (without the quotes).

CHANGE YOUR PASSWORD
Since this is your first time logging in, you should immediately change the administration password. Failure to do so leaves your phpQuestionnaire installation open to anyone who knows our default password or tries to guess. This means anyone can create, modify or remove surveys from your site without your permission. To change your password, click on the 'Configuration' tab in phpQ administration. For further information, see Changing Administrator Password.

Again and again...

To access the phpQ Administration panel in the future, simply point your web browser to:

http://www.yourdomain.com/path/to/phpQ/admin/index.php

You obviously must modify the above URL to contain your actual domain name and the path to where you have installed the phpQ program on your web server.

1.3) Administration Panel Sections

After logging in to the administration panel, you will find 5 tabs at the top (the current section will be highlighted):

  • Main
    This link will return you to the Survey Overview that offers quick access to taking, editing, previewing or viewing the results of any specific survey. This is the page that you see when you first login.

  • Survey Editor
    This link directs you to a form for modifying an existing survey or adding a new one. From here you can also access the question editor. Any modification of a survey must be done through this section.

  • Survey Results
    As people complete your active surveys, their results will be available through this link. You will be able to view summaries, statistics and remove any specific survey submission.

  • Configuration
    This area of the administration allows you to alter the way the phpQ admin panel works. For instance, how many survey results are displayed per page, what template should be used by default, etc.

  • Log Off
    Click this tab when you are done using the phpQuestionnaire administration panel. Alternatively, quitting out of your web browser will end your session as well.

2) Survey Overview

Figure 2-01
Figure 2-01 - Survey Overview

The Survey Overview page displays each survey that has been created. To the left of the survey you will find an image that describes the state of the survey. You can manually activate and deactivate a survey. The following images may appear next to each survey:

  • ACTIVE
    This image appears any time the public is allowed to take your survey. This means that it has been manually activated and if a starting or ending date has been specified, it is within those bounds.

  • PENDING
    This image appears when a survey has been manually activated, but the public is not yet allowed to take the survey as it has not reached the starting date.

  • EXPIRED
    If a survey is still in the system as active, but the ending date has since passed, you will see this image appear. Users are no longer allowed to take the survey, but you may wish to manually deactivate it.

  • NOT ACTIVE
    This image will appear if you have manually deactivated a survey. No users will be allowed to complete the survey in this state.

A link to an individual survey's results is provided to the right of the survey's name. This link will also inform you of how many responses to that survey currently exist. Quick links to edit or preview the survey are also available. You may find the following items listed below each survey, depending on the active status of that survey:
  • Description
    This contains any survey description you have entered for this particular survey.

  • Active Dates
    This shows any date restrictions placed on the survey, such as a starting date, ending date or both. The survey will only be shown according to those dates when 'Active'.

  • Link to Survey
    This is the link visitors must follow in order to complete the survey. This is also the URL you can use in <? php tags in order to include() the survey into an existing page. Or use the portion of this URL after the domain name inside of a server side include call to import the survey into an existing page as well.

  • Public Results
    If you have chosen to make survey results public, a link to the public survey results will be made available here. You can use this to point your users to the results if you wish.

You will notice that an image will appears next to the text "Survey Overview". This image is fetched from our system every time you login. Should we release a security fix or product enhancement, you will be notified via this image (and possibly via email as well). Simply click on the image if you notice there is an update waiting and you will be able to login and download the patch or new version. Otherwise, it will normally state that no updates or announcements exist for the current version.

3) Survey Editor

The survey editor is where all modification and configuration of a specific survey is to be done. This is also where you should go if you wish to add a new survey, remove a survey or edit questions. At the top of the Survey Editor you will see a selection box allowing you to select the specific survey you wish to manage. It will appear something like:

Figure 3-01
Figure 3-01 - Survey Editor

Once a specific survey has been selected, the page will automatically refresh and you will see the:

Figure 3-02
Figure 3-02 - Survey Editor: Survey Selected

You now have access to the following actions which can be performed on this survey:
  • Edit Questions - Click on this button to be taken to the question editor. From there you will be able to add, modify and delete any questions and answers from the survey you have created.

  • Preview - Clicking on this button will popup a new window that allows you to preview your survey without actually submitting any results. Any question requirements are still enforced, so it will behave as would be expected for the final users. You can preview a survey when it is deactivated.

  • Activate or Deactivate - When your survey is created, it defaults to a Deactivated state. This allows you to fully complete and test the survey without users being able to access it. Once your survey is finalized and ready to go live, you should activate the survey by clicking the Activate button. Any starting and ending dates will still be enforced on an active survey. You can stop any submissions on the survey by clicking the Deactivate button on an active survey.

  • Export - You can export a survey, along with all questions, into a single file which will allow you to swap this file with another user of phpQ. That person can then import the survey using the form at the bottom of the Survey Editor. Survey Results will not be included in this export. If you wish to back those up, you should check out the Configuration tab.

  • Delete - To remove a survey and all related questions and results, click on this button. You will be prompted with a JavaScript alert box, and if you click OK the survey will be removed from the system. You cannot undo this action.

3.1) Adding or Modifying a Survey

The next portion of the Survey Editor contains the form used for adding and modifying surveys within phpQuestionnaire. There are two interfaces for this form, both of which are shown below. The Basic interface gives you quick access to the most important details of survey creation. If you wish to take full advantage of all that phpQuestionnaire offers, you will definitely want to use the Advanced interface, however.

Figure 3.1-01
Figure 3.1-01 - Survey Editor: Basic Interface

Figure 3.1-02
Figure 3.1-02 - Survey Editor: Advanced Interface

If a survey has been selected within the Survey Editor, the setup for that survey will be placed into the "Add/Modify a Survey" form and made available for modification. Once you have modified the setup, you can either click the "Add" or "Modify" button. Clicking "Add" will create a new survey with the values you have entered, while clicking Modify will simply update the existing survey with the new configuration. The setup in both basic and advanced mode is explained in detail below.

FIELDS APPEARING IN BASIC AND ADVANCED INTERFACES:

  • Survey Name
    This field is used within the phpQ admin to refer to the specific survey that you are creating or modifying.

    This value can also be substituted into survey templates using the marker ::SURVEYNAME::. In the default phpQ template, this value appears in the title bar of the user's browser.

  • Survey Template
    This field allows you to select the template that you wish for this survey to appear in. You can download more templates for phpQ at http://www.chumpsoft.com/products/phpq/.

    The program checks in your phpQ/templates directory in order to determine what templates are available for use in your survey program. Removing the files from this directory will cause phpQ to stop functioning properly.

    The values you can use inside of your template that phpQ will recognize are:

    • ::SURVEYNAME:: - phpQ will replace this text with the Survey Name. In the default template, this is placed in the <TITLE> tags.

    • ::CONTENT:: - phpQ will replace this text with the survey questions and answers. This tag is required in order to have the survey questions and answers appear on the page.

    • ::JSCRIPT:: - This will import any required JavaScript into the template. The only time this is needed is if your results are publicly viewable, so that the survey can popup extra results over the configured limit for textfields and other inputs. You are free to leave this out if you will not be offering public results in your template.

  • Survey Language
    Starting with version 2.0, phpQ allows you to create surveys in different languages. If this select box appears on the survey editor page, then you have more than one language available for creating surveys. Simply select the language you wish to use for this survey from the list. Although you control almost all data input to define the language, selecting the appropriate language from this list will cause any error messages and buttons to appear in your language as well as select the correct character set for the browser to use.

    You may also wish to read about creating your own translations or to find more translations by users such as yourself, you can check http://www.chumpsoft.com/products/phpq/!

  • User Restrictions
    These can be used to attempt to limit the number of submissions to one per user per survey. They are also effective in stopping accidental duplicate submissions and validating the user's e-mail address. They aren't, however, 100% effective and a determined user will still be able to make multiple survey submissions. You are allowed to select any of the following three options. Selecting none of them will allow any user to submit the survey as many times as they wish. You can select multiple restrictions to enforce multiple rules.

    • Unique IP Address - You can use a user's IP address as one method of blocking multiple survey submissions from the same computer. This is not a 100% guaranteed method and it can be fooled. In some cases, it may deny a legitimate user the ability to complete the survey if two different users are on the same IP address, and in other cases a user could simply change computers to submit the survey twice. In any case, it does provide protection against accidental duplicate submissions or someone who is not intent on submitting the survey more than once.

    • Cookies - Using these restriction, phpQ will attempt to place a cookie in the user's browser each time they complete a survey. If phpQ detects they have already completed the survey, they will not be allowed to make another submission. Using this restrictions requires them to have a cookie-capable browser to complete the survey as it also checks to make sure they don't have cookies turned off. This is not 100% protection and the program can still be fooled into taking multiple survey submissions from the same user.

    • Verified Email - This is by far the most effective restriction. It requires that every person who completes the survey also supply an e-mail address which they are then forced to validate. It is still not 100% effective and cannot guard against users who have multiple e-mail addresses and wish to submit several surveys, but it does provide you with a working e-mail address with which you can contact survey respondents.

  • Description
    This field contains text that will be displayed on the Survey Overview page which lists all of your active and inactive surveys. It is only there if you wish to provide a brief summary of the purpose or contents of this survey.

FIELDS APPEARING IN ADVANCED INTERFACE ONLY:

  • Instructions
    This field will be displayed at the top of the first page of the survey and can be used to explain what the survey is, how it should be taken or any other information you wish to communicate to the user. You can feel free to use any HTML markup you wish within this textarea and it will be shown as entered when a user begins to take the survey.

    Some information you may wish to display here are things such as User Restrictions so the user knows if they will need to have cookies enabled, supply a valid e-mail, etc.

  • Starting Date
  • Ending Date
    phpQ provides a way in which you can set up surveys with specific starting and ending dates. If you are not using starting and ending dates, you must manually activate and de-activate the survey when you wish for it to be available or taken down. The starting and ending dates allow you to activate the survey and have phpQ determine whether the user is allowed to access it based on the time. In this way, you don't have to be around at midnight if you wish for the survey to expire at the end of a day.

    Starting Date - By setting these fields to a valid date and time, phpQ will not allow anyone to fill out the survey before that specific time.

    Ending Date - By setting these fields to a valid date and time, phpQ will not allow anyone to fill out the survey after that specific time.

    You do not have to fill in both of the fields to use one of the functions. For example, if you wish to manually activate the survey, but have a pre-defined end time, you only have to set the Ending Date.

  • Survey Width
    When phpQ places the survey inside of your template, it embeds the survey within a table. The Survey Width parameter allows you to control the width of the table in which your survey appears.

    In some cases, the text or style of some of your questions or answers may cause the survey table to be expanded outside of your defined Survey Width. Therefore, this field is more useful for specifying a width when the table is smaller than you would like it to appear, and wish to expand it.

  • Answer Indentation
    This parameter specifies how many pixels your answers will appear indented from the leftmost text of each question. Leaving this blank or setting it to 0 will cause the answers to line up with the questions.

  • Auto Numbering
    If Auto Numbering is set to "Yes", each question will have a number appear in front of it. If you set this to "No", no numbers will appear in front of the questions and you will be responsible for placing the numbers in each individual question if you wish to have them.

  • Question Text Style
  • Answer Text Style
  • Error Text Style
    The goal of phpQ was to allow you to design your survey to look any way you wish. To do this, we have offered options on the way your questions, answers and error messages can appear.

    In these fields you may enter any CSS style definition that you wish to have applied to all question, answer or error text in the survey. You can also modify the question or answer text style individually when adding or modifying that question. The style of an individual question or answer will override the survey wide styles you define here. For example, if you wanted to have your error messages all appear in a red, Arial font of size 12px, you would enter the following into the Error Text Style field:

    color: red; font-style: Arial; font-size: 12px;

    This would then cause your error messages to appear as:

    Please complete this question.

    The style definitions will be placed inside of the <TD> that surrounds the question text or error text. Your answer text style will also be applied to <SELECT> fields allowing you to control the appearance of the text within those input items. You will also be able to override survey-wide defaults for Question Text Style and Answer Text Style within each question setup itself. Error Text Style can only be defined on a survey-wide basis.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Answer Input Style
    This field allows you to enter any CSS style definition that you wish to have applied to the table cells (<TD>) that surround answer input fields such as radio button, checkboxes, select boxes and text fields. It should be noted that this style will apply to the surrounding cells, not the input fields themselves. To affect the input fields themselves you should read about Text Input Style for textfields and textareas and Answer Text Style for select boxes (single and multiple). Radio and checkboxes cannot currently be altered using CSS.

    You will also be able to override survey-wide defaults for Answer Input Style within each question setup itself.

  • Text Input Style
    In this field you may enter any CSS style definition that you wish to have applied to all text field answer inputs (text fields and text areas). If you wanted all of your 'Other:' field text fields and all of your text area inputs to have a width of 300 pixels and no shading, you could set this to:

    width=300px; border-left: 1px solid black; border-right: 1px solid black;
    border-top: 1px solid black; border-bottom: 1px solid black;

    That would yield text fields throughout the survey that looked like:

    The style definitions will be placed inside of the individual input fields for each answer input they apply to. You will also be able to override survey-wide defaults for Text Input Style within each question setup.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Email From
  • Email Subject
  • Verification Email
    Should you choose to restrict survey results based on verified email addresses you will also need to fill in the following three fields. These fields control the appearance of the email that is received by the user once they complete the survey, requesting for validation of their email address.

    • Email From: - This data will appear in the 'from' line of the email message that the user receives asking for their email validation.

    • Email Subject: - This is the subject of the verification email that the user will receive.

    • Verification Email: - This is the body of the message that contains all of the information necessary for the user to validate the e-mail address they supplied and thus complete the survey. The valid template fields for this email message are ::SurveyName::, ::ConfirmPassword:: and ::ConfirmURL::. These values will be replaced with the name of the survey the user just completed, the confirmation password (automatically generated by phpQ) and a direct link to the script, so that with one click they can finish the survey. A sample of what you may wish to enter in this field is supplied as the default value for a new survey.

  • Upon Completion
    The Upon Completion option allows you to determine where the user will be sent once they have completed your survey. You may choose between the following options:

    • Display the completion notice shown below
      By default, this field is set to display a default completion notice stating that the survey has been completed. You can change the notice by modifying the Completion Notice field. The user will be shown this information once they have successfully completed your survey. Feel free to include a link to the survey results on this page by placing it in the Completion Notice.

    • Redirect user to the survey results page
      Starting with version 1.1, phpQuestionnaire now allows you to make the results for a specific survey publicly viewable via the Survey Results option. If you have chosen to make your results public, you may also elect to have the users redirected to these results once they complete your survey. To do so, simply select this option.

    • Redirect user to the URL specified below
      Selecting this option and completing the Redirect URL field will cause your users to be sent to the web page of your choice once they have completed the survey.

    • Redirect user to their individual survey response summary
      Starting with version 2.2, you can display a user's survey responses to them at the end of the survey. Select this option and they will be shown a listing of each question and answer that they have completed in your survey.

  • Completion Notice
    This field is the message that will be displayed to the user once they have successfully completed the Survey. You are free to use any HTML you wish and it will be shown in the ::CONTENT:: area of the survey template as entered.

  • Redirect URL
    Starting with version 1.2, phpQuestionnaire now allows you to redirect a user to any specific URL you choose Upon Completion. If you have set the "Upon Completion" field to "Redirect user to the URL specified below", simply enter the destination URL into this field. Once a user has successfully completed the survey, they will be redirected to that location.

    NOTE: This URL should be an absolute, beginning with http:// or https://

  • Response Notice
    Starting with version 2.2, phpQuestionnaire is now capable of sending email notices each time a survey response has been completed. The options are:

    • Do not send any notification email - This is the default option. If selected, no email notifications will be sent upon survey completion.

    • Email text notice of response to addresses listed below - If selected, the email addresses listed in Response Email will receive a short text message each time a survey has been completed. It will list the survey title, date of completion, IP address and a link to the full results.

    • Email HTML summary of response to addresses listed below - If selected an HTML-formatted message will be sent to the email addresses listed in Response Email that includes the user's response to each question in the survey.

  • Response Email
    The email address (or multiple addresses separated by commas) listed in this field will receive the Response Notice for each survey submitted.

  • Survey Results
    Starting with version 1.1, phpQuestionnaire now allows you to make the results for a specific survey publicly viewable. To do so, simply set this option to one of the "Make survey results public" options. If this option is set, users will be able to see the results for this survey. A link will be shown on the survey overview page of the admin which you can use to let visitors get directly to the results.

    There are two options when making your survey results public. The first option simply supplies you with a URL that you can place anywhere you wish allowing visitors to view the survey results (such as the Completion Notice). The second option (include button on survey) will place a "View Results" button next to each Next or Submit button that occurs on your survey. This allows your visitors to easily bypass the survey and get straight to the results, much like many polling scripts usually work.

    Either public results option also allows you to set the Upon Completion action to redirect users to this publicly viewable statistics page once they have successfully completed the survey.

    PLEASE NOTE: If you deactivate your survey, it will deactivate the ability for the public to reach your statistics. If you wish to stop users from submitting results, but still allow them to view results, you must set a specific ending date for your survey and leave it active.

    Figure 3.1-03
    Figure 3.1-03 - Customizing Public Survey Results

  • Results Table Width
    Starting with version 2.0, you can now customize the look of public survey results. You can define the width of your results boxes using the Results Table Width parameter. It should be defined in pixels (commonly between 400 and 800). phpQ will automatically calculate the maximum length for the resulting bar graphs, which are 110 pixels less than the width entered here.

    The default for this field is 500 pixels. In some cases, the text or style of some of your questions or answers may cause the survey results table to be expanded outside of your defined Results Table Width.

  • Results Border Style
    This field controls the table enclosing the results. You can set the color of this table using the background-color CSS property. It also controls the color of any text and links appearing in the border (using the color CSS property). Since this style will be placed inside any links in the border, you can also specify things such as text-decoration to control link highlighting, etc. By default, the border has a purple background color with white colored text and links:

    background-color: #333366; color: #FFFFFF; text-decoration: none;

    You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the table border as well as any <A> anchor tags for links such as "See More..." or page numbers.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Results Answer Style
    This field controls the appearance of rows in your results table that contain the selected answers. You can change either of these using the background-color or color CSS properties. Furthermore, this style will be applied to the 'Textfield Results' link should it appear. By default these rows have a white background and purple text:

    background-color: #FFFFFF; color: #333366;

    You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the answer rows as well as any 'Textfield Results' link.

  • Results Stats Style
    This field controls the appearance of rows in your results table that contain the statistics (how many people chose a specific answer, bar graph, etc.). You can change either of these using the background-color or color CSS properties. Although the results bar graph appears in this row, the style of the bar graph is controlled using the Stats Graph Style. By default these rows have a light-blue background and purple text:

    background-color: #DDEEFF; color: #333366;

    You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the stats rows.

  • Stats Graph Style
    This field controls the appearance of the bar graph within your survey results. You can control the color of it using the background-color CSS property, and even the thickness of the bar using the height directive. You may also wish to look into using background-image to create 3-d styled bars. To control the background color that appears behind the bar, you should look into the Results Stats Style. The default for this field is:

    background-color: #333366; height: 8px;

    You may, in fact, include any style definition here, and it will appear in the <TD> that creates the result bar. The bar is nothing but a transparent gif that can be styled howvever you wish.

  • Submit Button Style
  • Results Button Style
  • Next Button Style
    With the addition of button styles in phpQ 2.1, you can now customize every aspect of the survey. No longer are you restricted to using the default button styles for "Submit", "Next" and "View Results". With the introduction of the Submit Button Style, Results Button Style and Next Button Style you can now control all buttons that users may view. The following fields will help you to customize these buttons:

    • Text - When used with an Image, this text will become the ALT tag for your button. Otherwise, the text that you type in here (such as 'Submit' or 'Next') will become the label for your button.

    • Width and Height - When used with an Image, these fields will control the width and height of your image, as attributes in the tag. If you are not using an image, we will apply correct CSS definitions to your text button to make it this size. These fields are defined in pixels.

    • Image - If you are not a fan of boring looking submit buttons, you can now use any image on your web site as the next, submit or results button! Simply enter the URL to your image in this box and it will be used as the button.

    Please note that the Next Button Style will only appear if you have a multi-page survey and the Results Button Style will only appear if you have the Survey Results field set to 'Make survey results public (include button on survey)'. Furthermore, if you do have public results and a multi-page survey, the Next Button Style will also be used on the page-by-page view of your public results.

    Advanced CSS Trick
    Some of you may be wondering why we left out CSS customization of the button when it is readily available for all other areas of phpQ. We felt that the Text/Size/Image fields were more useful on a day to day basis for most users' needs. However, we have a little trick for those of you who want to customize your button CSS.

    When you leave the Image portion of your Button Style blank, the Text field will be included in the VALUE="" portion of your <input> tag. Normally, if you put 'Submit' as the Text, this would result in:

    <INPUT TYPE=submit VALUE="Submit">

    If you were instead, however to enter into the Text field something like 'Submit" STYLE="color: red;' you would achieve the following:

    <INPUT TYPE=submit VALUE="Submit" STYLE="color: red;">

    It is important to note that you need to include a double quote after the text you wish to have appear on your button and then leave off the last double quote from the end of your STYLE definition. Once you have the basic format down, it is easy to add any styles you want! If you have any further questions on this, simply contact chumpsoft support and we will be happy to help.

3.2) Previewing a Survey

phpQuestionnaire offers the ability to preview any survey that you have created. It will appear exactly as a user would see the survey. Any answers you supply will be checked for validity (such as whether the field is required, how many answers should have been supplied, and so on).

You can preview a survey at any time, whether or not it is active. This allows you to create and test a survey extensively before making it available to users. The survey preview from several areas of the phpQuestionnaire administration panel.

The most common way to access the survey preview is from the Survey Overview page. This is the page that is first shown when you log into the administration area of phpQuestionnaire (shown in Figure 2-01). Each survey is listed along with a purple image that says "PREVIEW". Simply click on that link to take a look at how a user would see this survey.

You can also preview a survey by clicking on the "Preview" button in the Survey Editor (shown in Figure 3-02) after selecting a survey from the list. The preview is also available from the Question Editor (shown in Figure 4-01).

3.3) Survey Activation/Deactivation

phpQuestionnaire allows you to manually activate and deactivate surveys within the administration panel. Any active survey that is within its defined starting and ending dates can be completed by users. If you wish to stop a user from taking the survey, or if the survey is currently in development, you should set the status to "Not Active" in order to prevent users from completing it. The survey may still be previewed from the administration panel at any time.

To activate or deactivate a survey, enter the Survey Editor and select a survey. Once a survey has been selected (as in Figure 3-02) a button will appear allowing you to either activate or deactivate the survey, depending on the current state.

3.4) Deleting a Survey

Once a survey has been completed and you no longer desire any of the results, you may wish to delete the survey and all connected data (questions, results, etc.) from the system. To remove a survey from the system, enter the Survey Editor and select a survey. Once a survey has been selected (as in Figure 3-02) click the Delete button to remove the survey. A prompt will appear asking you to verify the deletion. This process cannot be un-done.

Please keep in mind that you do not have to delete a survey in order to stop users from completing it. You may simply deactivate the survey, allowing you to continue to have access to the results and statistics.

3.5) Exporting a Survey

Starting with version 1.2, phpQuestionnaire offers you the ability to export a survey along with the questions and answers you have defined. You can then share this file with a friend, a colleague or even the entire phpQ user community by sending it to support@chumpsoft.com. Simply select a survey on the Survey Editor page and you will see an 'Export' button. Click on this button and your browser will prompt you to save a file ending in .phpQ. The filename generally begins with the word surveyswap and includes the survey id number. You or someone else can now import this survey using the form at the bottom of the Survey Editor.

We have implemented this feature because we know it can take a lot of time and effort to develop a good survey, and some users may enjoy sharing their surveys with others. We welcome any contributions you may offer!

Please note that survey exports do not contain any survey results or user data. If you wish to share or backup that information, you should read more about backing up the database for phpQ.

3.6) Importing a Survey

Starting with version 1.2 of phpQuestionnaire, the following has been added to the Survey Editor:

Figure 3.6-01
Figure 3.6-01 - Import a Survey

This form offers you two options for importing a survey:
  • Upload Data File
    This field offers you the ability to import a survey from a file you have on your hard drive. Simply click the "Browse..." button and locate an exported phpQ survey file. Once you have chosen this file, click on the "Import Survey" button and the new survey will appear in your phpQuestionnaire interface, assuming there are no errors with the file.

  • Fetch From URL
    This field gives you the power to import a survey from any URL. You must enter a full URL (starting with http://) to the location of a valid exported phpQ survey file. phpQ will then attempt to fetch and import this survey. This is very useful for importing surveys that may be offered at chumpsoft. If also comes in handy if your export file is too large to place in the upload field or file uploads are not working on your machine.

The following briefly explains the behavior of the import feature in phpQ:
  • When imported, all surveys will be "Not Active" and show a current-day creation date.

  • The imported survey will attempt to locate the template it was exported with. Failing that it will use the first template it finds in the following order: the configured default template on your phpQ installation, the 'default' template distributed with phpQ or the first template it can find in the templates directory.

  • Nothing in your phpQ installation will be overwritten or deleted by an imported survey. You can import the same survey multiple times and it will simply create multiple instances of that survey, along with all of the associated questions and answers.

  • Imported surveys do not retain the original survey or question ids they were exported under.

If you are looking to import survey results, maintain survey ids or restore your entire database, you will want to read about restoring the database.

4) Question Editor

After creating a survey with the Survey Editor and selecting it as shown in Figure 3-02 you will see a button that says 'Edit Questions'. By clicking on this button, you will be taken to the question editor for this survey. At the top of the page will be the name of the survey and a list of questions for this survey. An example list of questions is shown below in Figure 4-01:

Figure 4-01
Figure 4-01 - Question Editor: List of Questions

Using the above interface, you can Edit, Delete, Re-Order or Preview the questions contained in this survey. There is also the ability to create and remove page breaks from within the question order.

4.1) Adding or Modifying a Question

Below the question list, you will find a form that can be used to add a new question or modify an existing question for the selected survey. To edit a question, and have the existing values pre-populated into the form, you should select the question from the question list and click the Edit button. If there are already values in the form and you wish to start over and add a new question, simply click the "Clear Form" button at the bottom of the form to add or modify a question.

The form to add or modify a question will differ depending on what question type you have selected. Therefore, the screenshots below depict a typical form for adding or modifying a question with a type of radio button. There is also an advanced and basic display of the question editor which will either show or remove some of the optional fields for that question type. Although not all fields are shown in the screenshot below, all of them are documented both below this screenshot and within the program by clicking on the question mark icons.

Figure 4.1-01
Figure 4.1-01 - Question Editor: Radio Button Advanced

If a question has been selected within the question list, the setup for that question will be placed into the "Add/Modify a Question" form and made available for modification. Once you have modified the setup, you can either click the "Add" or "Modify" button. Clicking "Add" will create a new question with the values you have entered, while clicking Modify will simply update the existing question with the new configuration. The setup in both basic and advanced mode is explained in detail below.

  • Question
    The value of this field is what the user will be asked when completing this question in the survey. You are free to type either text or HTML into this field and it will be displayed on the survey exactly as you have entered it.

    If you wish to provide extended instructions for a specific question or group of questions, you may wish to look into the Instruction Text field which appears in the advanced "Add/Modify a Question" form.

  • Content Name
    This appears only for the "HTML Content" question type and is used simply as an identifier for the question within your phpQ admin panel. It will not be displayed within your survey.

  • Type
    The type of the question is one of the more important fields to select. Every type has its own distinguishing characteristics and will govern how your answer choices appear to the person taking the survey.

    • Radio Buttons - A radio type question allows the user to select only one of a pre-defined list of answers for the question. All answers will be displayed for the user to read. You may associate a textfield with any of the choices you create, allowing the users to enter a custom or 'Other' answer in their own words.

    • Check Boxes - A checkbox type, like the radio type, displays all of the answers for the user to read. However, should you choose the checkbox type, the user is allowed to select multiple responses. Once this type is selected, another option (Number of Answers) appears that you can configure. This allows you to optionally force the user to fill in a fixed number of answer boxes, at least X number of boxes, at most X number of boxes. You may associate a textfield with any of the choices you create, allowing the users to enter a custom or 'Other' answer in their own words.

    • Text Field - A text input field is provided that allows the user to enter an answer in their own words. You can supply a Default Answer when this question type is selected. Users may not enter line breaks into their answer with this type of response.

    • Text Area - A text input area, like the text input field, provides a spacious field for the user to enter text as an answer. Breaks or carriage returns are allowed for textareas as well as a Default Answer.

    • Select Box - A select box allows the user to choose one answer, similar to the radio type. Unlike the radio type, a choice can be made to make an answer un-selectable. This allows you to supply a default answer in a required field that will be invalid, forcing the user to select a valid answer. An optional text field can be added to the select field for a custom or "other" answer, but you may only flag one answer to correspond to the text field.

    • Multiple Select Box - This is identical to a select box, except that the user completing the survey can select multiple answers. The way in which this is done varies between platforms, but on a windows machine the user must hold down control or shift while selecting multiple answers. Once this type is selected, another option (Number of Answers) appears that you can configure. This allows you to optionally force the user to select in a fixed number of answers, at least X number of answers, at most X number of answers. An optional text field can be added to the select field for a custom or "other" answer, but you may only flag one answer to correspond to the text field. You may also choose the size of this multiple select field in the Select Size field that appears when a Multiple Select Box question type is chosen.

    • HTML Content - Although not actually a question, this type allows you to place any HTML or Text content into your survey where needed. For instance, you could create an HTML Content type at the top of your survey followed by a page break which would create introduction page that can describe the survey. You can also insert images, legends, etc. using this question type. This type will be omitted from exported and printer-friendly results.

    • Redirect - Although not actually a question, the Redirect question type was introduced in version 3.0 as a tool to aid in the creation of branching surveys. Only useful when you have page breaks built into a survey, this question type should normally appear at the end of a page when you wish to skip the participant ahead in the survey once the Next button is clicked. You can therefore use this question type when you need to skip a participant past questions that are not applicable to them. This question type can also be used to redirect a user to the end of the survey or to any web site.

    • Hidden Text - Starting with version 3.0, you can create hidden question types that allow you to pass in information at the start of the survey to be displayed alongside the response for the administrator to see. More detailed information can be found in the user manual under the section Populating Hidden Question Types.

  • Required
    If this field is set to Yes, the user completing the survey will be forced to supply a valid answer for this question before they can move on to the next page or submit the survey. If you wish to make a certain question optional, simply set the Required? field for that question to No.

  • Select Size
    When the Multiple Select Box question type is selected, you can enter the size of the multiple select form element. Enter an integer greater than 1 to increase the number of answers the user will see at any given time. The number entered corresponds directly to the number of answers the user will see without scrolling within the multiple select field.

  • Instruction Text
    In some cases, you may wish to have question-specific survey instructions appear in a paragraph of its own right above the question. Although this could be done simply by using HTML in the Question field, it creates for very long questions in the question editor and could have consequences if auto-numbering is used. This is especially true in cases where you wish to have instructional text appear above a group of questions. In that case, simply use the Instruction Text field for the top question in that group and mention that the instructions apply for the following questions. This option is only available from the Advanced Question Editor Interface.

  • HTML Content
    This appears only for the "HTML Content" question type. This is where you enter the HTML or text that you wish to have appear within your survey.

  • Hidden Variable Name
    Provide the name of the variable you will use to set the hidden field. As an example, let us create a hidden question type that passes the user id into the survey. You start by making a hidden question type with the variable name "userid". Then when calling the survey to pass via GET, the url will resemble something like this: fillsurvey.php?sid=3&userid=14. More detailed information can be seen in the section Populating Hidden Question Types.

  • Redirect Name
    The redirect name is used only with a Redirect question type. The only purpose is to supply the name that will be shown in your list of questions so you can identify it and edit it in your survey.

  • Redirect To
    Used only with the Redirect question type, this field will specify which question in the survey you wish to redirect respondents to. You can also choose to redirect them to the end of the survey or any other web site (See Redirect URL).

  • Redirect URL
    When you have set Redirect To to "[ URL specified below ]", you must complete the Redirect URL field to specify the web site location (such as http://www.example.com/) where you wish the visitor to be sent. This can be used in combination with branching to only allow certain people to complete a survey. For instance, you could have a question that asks whether the survey participant is over 18 years old. If they answer yes, you would branch them past the redirect. Otherwise, they would encounter a redirect question type that would cause them to leave the survey and be redirected wherever you wish.

  • Question Text Style
    Enter a CSS style here to manipulate the look of the question text. For instance, if you entered the following in the field:

    font-family: verdana; font-size: 12px; color: green;

    The question text for this specific question would appear green in the typeface of Verdana and be 12 pixels tall, such as:

    What is your question text?

    Any styles entered here will override similar styles that may have been set survey-wide on the Survey Editor in that Question Text Style field.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Answer Choices
    If you have chosen a Question Type of Radio Buttons, Check Boxes, Select Box or Multiple Select Box, a field for Answer Choices will appear. This field contains a listing of all of the current answers, the ability to change the order of, modify or delete the current answers as well as add additional answers. The following description will guide you through the functionality of this field:

    The largest input area in Answer Choices field is a multiple select field that displays all of the current answer choices. You can change the order in which the answers will appear under the question by using the Up and Down Arrows located to the right of the select box. Simply click on the answer you wish to move and then on the arrow pointing in the direction you wish to move the answer.

    To add a new answer into the current question, you should type the answer into the text field that initially says "Add answer choices here." Once you have typed in the answer as you wish for it appear in the survey, you can either hit enter or click on the "Add Answer" button in order to add it to the list of Answer Choices. If you wish to have a text input field associated with the answer choice you are adding, simply click on the "Add with Textfield" button. The user of the survey will then have the option of filling in a custom text response when that specific answer is selected.

    When adding an answer, you will also have the option of making it a pre-selected choice for the user taking the survey. This option appears a checkbox next to the word "Selected?". If you check that field, the answer will already be selected or checked when the user takes the survey. In this way, you can provide default answers or choose which answer you wish to have selected by default. In the case of a Select Box or Multiple Select Box field, you will also see an option for "Selectable?". This allows you to set a default field in your select box, such as "Choose an Answer" and then make it both selected and unselectable. In this case, the when the user takes the survey, they will see "Choose an Answer" already selected in the Select Box and will be required to switch the answer from the default to a valid "Selectable" value.

    Starting with version 3.0, the question types Radio Buttons and Select Box contain an additional field called Branch To that will appear for the answer choice section when editing in the Advanced Interface mode. This field will not appear when adding a new question or when there are no questions below it in the survey. It is usually best to add all of the questions to your survey and order them before configuring the branching option.

    When executing branching, the survey will skip to the targeted branch question, but it will display all the questions on that page that follows the target question. So if you had questions 5, 6 and 7 on a page, and you were branching to question 6, you will see the page with questions 6 and 7 only. Question 5 is omitted because it comes before question 6, which you designated as the question to be branched to.

    If you create multiple questions that branch on a single survey page, the very first branching detection is executed. Also, if you re-order a question after you have configured the branching so that the branch is no longer applicable, it will be ignored.

    If you wish to modify the text of an answer, click on the answer you wish to change. The answer text will appear in the text field and you can then edit it. Once you have modified the answer to your satisfaction, click on the "Modify" button.

    To remove an answer from the Answer Choices simply select the answer you wish to remove and then click on the "Delete" button. Doing so will remove the answer from the current question.

    PLEASE NOTE: Removing an answer choice from an active survey when results have already been submitted can cause major problems in your ability to view the results a user has submitted.

  • Default Answer
    You can specify a default text answer for question types of Text Field and Text Area. The default answers are displayed within the text fields when a user takes the survey.

  • Number of Answers
    If you have chosen a Question Type of either Check Boxes or Multiple Select Box, the field Number of Answers will appear in the Advanced Interface of the "Add/Modify a Question" form. Since the check box or multiple select types allow the user submitting the survey to select multiple answers, this field allows you to control exactly how many answers the user can make. It has the following options:

    • Any Number - Selecting this value, which is also the default, will allow the user completing the survey to select as many or as few responses as they wish. Of course, if the field is marked as Required the user will still be forced to mark at least one valid answer.

    When any of the following non-default options are selected, you should enter an integer in the textbox to the right of the select field to indicate the number of answers that should apply.

    • Exactly - When this is selected and an integer supplied in the field to the right, the user will be required to fill in exactly that number of answers before they can proceed to the next survey page or submit the survey. If Required is set to "No" they can also proceed by filling in 0 answers.

    • At Least - When this option is selected and an integer supplied in the field to the right, the user will be required to fill in at least that many answers to proceed. They will also be allowed to fill in more than that number. If Required is set to "No" they can also proceed by filling in 0 answers.

    • At Most - When this option is selected and an integer supplied in the field to the right, the user will be required to fill in at most that many answers to proceed. They can also fill in fewer. If Required is set to "Yes" for the question, they must mark at least one valid answer.

  • Number of Columns
    This field appears only under the Advanced "Add/Modify a Question" form when the Question Type is either Radio Buttons or Check Boxes. By default, the number of columns is 1 unless this field is set to an integer higher than 1. If the number of columns is greater than 1, your answer choices will be placed into multiple columns.

  • Answer Input Style
    This field allows you to enter any CSS style definition that you wish to have applied to the table cells (<TD>) that surround answer input fields such as radio button, checkboxes, select boxes and text fields. It should be noted that this style will apply to the surrounding cells, not the input fields themselves. To affect the input fields themselves you should read about Text Input Style for textfields and textareas and Answer Text Style for select boxes (single and multiple). Radio and checkboxes cannot currently be altered using CSS.

    You can also specify survey-wide defaults for Answer Input Style within the Survey Editor.

  • Answer Text Style
    In this field you may enter any CSS style definition that you wish to have applied to all answers within this question. If you wanted to have your answers all appear in a red, Arial font of size 12px, you would enter:

    color: red; font-style: Arial; font-size: 12px;

    This would then cause your answer to appear as:

    My first answer.

    The style definitions will be placed inside of the <TD> that surrounds each answer. You can also specify survey-wide defaults for Answer Text Style within the Survey Editor.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Text Input Style
    In this field you may enter any CSS style definition that you wish to have applied to all text field answer inputs (text fields and text areas) with the current question. If you wanted your 'Other:' text field or your text area input to have a width of 300 pixels and no shading, you could set this to:

    width: 300px; border-left: 1px solid black; border-right: 1px solid black;
    border-top: 1px solid black; border-bottom: 1px solid black;

    That would yield a text field for this question's answers that look like:

    The style definitions will be placed inside of the individual input fields for each answer input they apply to. You can also survey-wide defaults for Text Input Style within the Survey Editor.

    To find out more about CSS styles, go to Zvon.org CSS1 Reference.

  • Text Input Attributes
    Within this field you can specify any attributes of a text field or text area for this specific question. For instance, if you have chosen a Question Type of "Text Area" you may wish to fill in the Text Input Attributes with:

    COLS=30; ROWS=3

    That would cause your text area input field for this specific question to appear as:

  • Display in Summary
    On the survey results page, after selecting a survey, you will be presented with a list of all completed surveys submitted so far. Included in this list will be the date and time of submissions as well as either the IP or Email address of the user who completed the survey.

    Setting the Display in Summary? field to "Yes" for an individual question will cause the answer to that question to appear in the list of completed surveys. Since each survey in the list appears on one line, you should be selective about which questions you have displayed in the summary so that you do not run out of room.

    From the survey summary, the date and time of each submission will be linked to that individual user's survey so that you can access all responses by that user.

  • Show in Public Results
    Starting with Version 3.1, the field Show in Public Results allows you determine whether you want the results for this particular question to be displayed or not.

    This field option will only be available if the survey results are set to public. More specifically, having the field Survey Results set to either "Make survey results public (admin and user viewable)" or "Make survey results public (include button on survey)". Otherwise this field will be hidden since it only affects public results.

    If you decide to set this field to "No" the question will not be displayed in the Table of Contents of the survey results, nor will it be available for selection in the Cross Tabulation section. The default setting for this field is "Yes".
4.2) Previewing a Question

You may preview a question at any time once it has been added to a survey. This can be done from within the Question Editor. Highlight the desired question and click on the Preview button below the list of questions. This will open a new window displaying that question.

4.3) Deleting a Question

You may delete a question by selecting it from the list of questions and clicking the Delete button below the list. A prompt will appear asking you to verify the deletion. This process cannot be un-done.

4.4) Changing Question Order

You can change the question order by moving individual questions. Select the question you want to move and click the arrow buttons to the right of the question list to move the question up or down. You can also use this same process to move a page break up or down in the question list, effectively changing where the Next buttons appear throughout your survey.

PLEASE NOTE: After changing the question order, you must click the Save Order button to make the changes permanent.

4.5) Create Page Breaks in Question Order

You may not want to have all of your survey questions on one page. Inserting a page break will move all questions listed after this page break onto a separate page. In this way, you can create a multiple-page survey for your users so that they only see a limited number of questions per page.

To insert a page break into your survey, click on the Add Page Break button below the question list. This will add a page break at the end of the current list. You may move its position in the list in the same way you would change the Question Order. Select it and use the arrow buttons to the right of the question list. After adding a page break, you must click the Save Order button to make the changes permanent.

PLEASE NOTE: After changing the question order, you must click the Save Order button to make the changes permanent.

4.6) Create Conditional Branches in Survey Questions

Starting with version 3.0, you can now implement conditional branches within your survey which allow you to display certain questions depending on the response given in prior questions. You can only branch using the question types Radio Buttons and Select Box, which now contain an additional field called Branch To that will appear for the answer choice section when editing in the Advanced Interface mode. This field will not appear when adding a new question or when there are no questions below it in the survey. It is usually best to add all of the questions to your survey and order them before configuring any branching options.

Once you have determined the order of all questions, it is time to specify branching. Open up the question upon which you wish the display of future questions to depend. It must be a Radio Button or Select Box type so that only response can be selected by the respondent. When you click on each answer choice, you will see that you can set a Branch To for that answer. If you wish the respondent to flow through the survey naturally for a given answer, you do not need to set the Branch To field. However, selecting a specific question in Branch To for any given answer will cause the respondent to skip ahead to the selected question upon submitting the page with that question. It is always smart to place a page break directly after any question that branches. Otherwise, further questions will be displayed even if they aren't to be answered.

A small branching example:

There are other situations in branching that you must take into account. These occur when you may want to skip a respondent past a section of questions because it doesn't apply to them. Let's say that in question #1 you ask a Yes or No question where you want questions #2-4 answered if they select Yes and questions #5-7 answered if they select No. All respondents should resume at question #8. After adding all of your questions, you will need to add page breaks after questions #1, #4 and #7. Save the order and return to edit question #1. You would only need to set a Branch To on the answer No and point it to question #5. However, we now need to specify a way to skip those that answer Yes past questions #5-7. This is accomplished by using a Redirect question type. After saving your changes to question #1, you will need to add a new question of type Redirect and select question #8 in the Redirect To field of that question type. Now add this Redirect and move it up so that it appears at the end of the page after question #4. Once respondents have completed the page with question #4, they will be redirected to question #8. Those who had answered No to question #1 will move naturally to question #8 once they answer their page.

Further information about how branching has been implemented:

When executing branching, the survey will skip to the targeted branch question, but it will display all the questions on that page that follows the target question. So if you had questions 5, 6 and 7 on a page, and you were branching to question 6, you will see the page with questions 6 and 7 only. Question 5 is omitted because it comes before question 6, which you designated as the question to be branched to.

If you create multiple questions that branch on a single survey page, the very first branching detection is executed. Also, if you re-order a question after you have configured the branching so that the branch is no longer applicable, it will be ignored.

5) Survey Results

If you are creating surveys for your users, one of the most important things is going to be interpreting and viewing the results. phpQuestionnaire excels at this task, offering you many ways in which you can view the information, even allowing for customized summaries. To get started, you should click on the "Survey Results" tab that can be found at the top of the phpQ administration panel. Once you are there, you will need to select a survey for which you wish to view results. This is done in the same way as for the Survey Editor.

Starting with version 1.1, phpQuestionnaire now allows you to make survey results public. Doing so allows your visitors to view question results using the table of contents, pagebreaks or all questions at once. This brings the power of complex internet polling software to phpQuestionnaire, offering even further flexibility. Your users will not, however be able to view individual survey results for each user.

User survey results will be shown on the same template that the survey itself has been shown on, allowing you to easily integrate this data into your existing site design.

5.1) Selecting a Survey

Once you have selected a survey, you will see button(s) appear beneath it. The screen will now look like one of the following two screenshots:

Figure 5-01
Figure 5-01 - Survey Results: Select Survey (Using Email Verification)

Figure 5-02
Figure 5-02 - Survey Results: Selected Survey (No Email Verification)

Figure 5-01 displays the buttons that will be available if your survey includes a user restriction of Email Verification.

  • Verified Results
    This will show you the results, on a question-by-question basis, for all users who have verified the email address they have attached to the results. After completing the survey they were emailed a verification link. If the email address they gave was valid and they followed this link, their results will appear in this section.

  • Unverified Results
    This section displays the results, on a question-by-question basis, for all users who have not yet verified their results. This means that either the email address they provided did not work or they chose not to follow the verification link that was sent to them upon survey completion. These responses could still be valuable, and therefore, they are made available through this button.

  • All Results
    This button will display, on question-by-question basis, the results for all surveys, both verified and unverified.

If the survey you have selected to view results for did not have a user restriction of Email Verification, then the only button that will appear is:

  • View Results
    This button will display, on question-by-question basis, the results for all surveys.

After clicking one of these buttons you will be taken to the results on a question-by-question basis. More information about this view can be found in Viewing Question Results. If you wish to view results on a survey-by-survey basis, you should look at the Survey Summary which allows you to view and remove an entire survey response for an individual.

5.2) Survey Summary

Figure 5.2-01
Figure 5.2-01 - Survey Summary

After selecting a survey, the window will refresh, displaying a Survey Summary on the lower half of the page (see Figure 5.2-01 above). The summary includes a list of the survey responses, the date it was completed, and user identification information. If Email Verification was used, the user identification information will be the address they supplied. Otherwise, an IP address for that respondent will be shown. It will also display the answers to any questions you marked in the Question Editor to show in the Survey Summary. You may click the date to open a new window displaying the survey with their answers.

The number of responses shown in this summary can be configured, and if the total responses overflows, there will be links at the bottom of the summary to view the next page of data.

5.3) Viewing Question Results

Figure 5.3-01
Figure 5.3-01 - View All Results

You can view the results of survey responses on a question-by question basis by following the directions in Selecting a Survey. Once a category of results has been selected with one of the buttons, there are three methods of viewing the results and statistics (shown in Figure 5.3-01 above):

  • Table of Contents
    You may view statistics for each individual question by clicking on Table of Contents. This will list each question in the survey and allow you to view the results and statistics for each one by clicking on the question.

  • View with Pagebreaks
    Selecting this view will display the results for each question on a page by page basis with a similar structure to the way the users completed the survey. After viewing one page of question results and statistics you can then proceed to the following pages by using the "Next" button.

  • View All Questions
    You can view the statistics for all questions in your survey at once by clicking on View All Questions. This will display the statistics for every question in your survey on one page. This is ideal for short surveys, but could be a lot of information on one page if your survey is very long.

  • Cross Tabulation
    You can cross tabulate your survey results starting in version 3.0. Go here for more information on how cross tabulation works.
When viewing the results for a question, you should note that text answers are displayed in a popup dialog that allows you to read and scroll through all of the text responses to a specific question.

Figure 5.3-02
Figure 5.3-02 - View Question Results

5.4) Deleting a Survey Response

You may delete a survey response by accessing the Survey Summary window. Click on the circle with the red X to delete the survey response. A prompt will appear asking you to verify the deletion. This process cannot be un-done.

5.5) Downloading Survey Results

Starting with phpQuestionnaire version 1.2, you can now download the results of a survey in several different formats. Once you have selected a survey in the Survey Results portion of the Admin, you will see a screen that looks like:

Figure 5.5-01
Figure 5.5-01 - Download Survey Results

phpQ currently supports the following download options for your results:
  • CSV (Comma Separated Value)
    The comma separated file format is one of the most popular methods of exchanging data between different programs. This can be read in by many popular software programs such as Microsoft Excel and Access. Each survey response is placed on one line (unless the results contain newlines themselves), with each answer separated by commas (and enclosed in double quotes if necessary). There is also a header row on the data that contains the column names (such as "IP Address" or the question that was asked). Downloading this file and opening it with Excel or some similar spreadsheet application will allow you to manipulate and view the data in even further ways.

  • XML (eXtensible Markup Language)
    You can download survey results in valid XML, which is similar to HTML. This format is meant to be easily read by humans or machines (such as a program) and can be combined with style sheets to format the results to your liking. A brief description of the format of our XML file can be found in the Additional Information: XML Format section of this document. Warning: This file can become very large with many survey results, as the questions and answers are shown for each response.

  • XML Condensed (eXtensible Markup Language; Machine Readable)
    This representation of the survey results is also in valid XML, but is often around 25% the size of the above XML format. This format is not meant to be easily read by humans, but contains all of the survey information, including page breaks. This would allow you to use this file if you are planning on building applications to parse your results. It refrains from repeating the question and answer names, and supplies the data in a much more concise format. Further information on the format of this document can be found in Additional Information: XML Format.

  • SQL (Structured Query Language)
    If you choose to download the results in the SQL format, you will end up with a series of INSERT statements which you can use to place your data into the appropriate SQL tables. Executing every INSERT command listed in the file will replicate your survey data into another database, assuming you have created the appropriate tables. It will insert data into phpQSurvey, phpQQuestion, phpQUser and phpQAnswer, as these tables are defined in the Manual Installation section of this document. Because the answers remain unprocessed and difficult for a human to decipher, this is mostly useful for backing up a single survey along with all results. To backup the data in a phpQ compatible format, check out the 'phpQuestionnaire Backup Format' listed below.

  • Processed Excel Results for Graphing Purposes
    We have also included an option that allows you to download the results processed into a basic Excel compatible format (simple HTML tables). It displays the results for all multiple choice questions with tabulated results from which you can easily create charts and graphs. No results for textfield or textarea answers will be shown.

  • phpQuestionnaire Backup Format
    This file will contain all of your survey questions and results should you ever find the need to restore this data due to a new installation, a corrupted database or a crashed hard drive. You can also backup your entire phpQuestionnaire database if you wish. Both the backup and restore procedures are detailed more in the Configuration section of this document. Keep in mind that this is the only file format listed here that disregards whether you click on 'Verified', 'Unverified' or 'All' results on an email verified survey. All data from the survey will be backed up regardless of the button clicked.

If your survey is using email verification of survey responses, you will notice three buttons to download either the 'Verified Results', 'Unverified Results' or 'All Results'. Otherwise, the only button will be 'Download Results'. These options all perform as explained in Selecting a Survey, except that they cause you to download the results in the specified format, rather than viewing them through your web browser.

5.6) Cross Tabulation

Starting with version 3.0, you can create cross tabulations in the results section. View the results by Selecting a Survey and you will get four links on the top of the page, Table of Contents, View with Pagebreaks, View All Questions and Cross Tabulation, as seen in the picture below. Click on the Cross Tabulation link.

Figure 5.6-01
Figure 5.6-01 - Cross Tabulation

Select the two questions you would like to cross with each other and proceed to click on the Cross Tabulate button. The resulting cross tabulation chart will be displayed immediately. Similar to the sample chart below. When selecting your questions to cross-tabulate, keep in mind that Question 1 should be your independent variable and will have its answers displayed along the column headings. Question 2 will be your dependent variable and the answers will appear in rows.

Figure 5.6-02
Figure 5.6-02 - Cross Tabulation Chart

6) Configuration

Clicking the "Configuration" tab at the top of the phpQ Administration panel allows you to setup various defaults and customizations for the phpQ program. This is also where you should go to change your password. The administration screen looks like:

Figure 6-01
Figure 6-01 - Administration Configuration

6.1) Set Administration and Survey Defaults

  • Admin Language:
    The Admin Language field allows you to select the language that you wish to be used throughout phpQ Administration screens. It is possible that you will have a wider selection of languages for individual surveys than you do within the admin. This is because it takes significantly more work for the translator to convert the entire admin interface than it does to convert only the publicly visible text strings.

    Selecting your administration language will also cause phpQ to find translated images and help files if they are available in that specific language pack. In the case that the images or help files don't exist, english ones will be used instead.

    NOTE: This field only appears if you have more than one language available that has translations for the text strings used in the administration panels

    The program checks in your phpQ/languages directory in order to determine what languages are available for use in your survey program. Removing the files from this directory will cause phpQ to stop functioning properly. You can learn more about translating phpQ into your language below.

  • Default Template:
    You can select the template that you wish to be used as your default. This will be used in the following three places:

    • Any access to the phpQ/index.php file will use this template. When this file is accessed, it will generate a list of the currently active surveys.

    • Any illegal or error access to fillsurvey.php not related to a specific survey will use this default template.

    • When creating a new survey, the Default Template will be selected as the template for that survey. You can always modify what template a specific survey is displayed in.

    You can download more templates for phpQ at http://www.chumpsoft.com/products/phpq/.

    The program checks in your phpQ/templates directory in order to determine what templates are available for use in your survey program. Removing the files from this directory will cause phpQ to stop functioning properly. You can learn more about creating your own templates below.

  • Default Language:
    The Default Language field allows you to select the language that you wish to be used as your default. It was introduced in phpQ v2.0 and will only appear if you have multiple languages installed. The default language will be used in the following three places:

    • Any access to the phpQ/index.php file will use this language. When this file is accessed, it will generate a list of the currently active surveys.

    • Any illegal or error access to fillsurvey.php not related to a specific survey will use this default language.

    • When creating a new survey, the Default Language will be selected as the language for that survey. You can always modify what language a specific survey uses.

    NOTE: This field only appears if you have more than one language available that has translations for the text strings used in public surveys, results, etc.

  • Cookie Domain:
    Introduced in phpQ version 2.0, the Cookie Domain allows you to set a specific domain name for phpQ to use when setting cookies. This can be extremely important to prevent a loophole in cookie restrictions for users taking a survey.

    If you fail to set this, cookies will simply be set under the domain they are accessed. This means that a user could first complete the survey at yourdomain.com and later complete it again at www.yourdomain.com even if you have cookie restrictions enabled.

    To correctly set this field, you need to use at least two periods in the domain name, such as '.yourdomain.com'. This will allow cookies to be sent to the script even if they were set from www.yourdomain.com or a similar other name. Certain extensions, such as .us or .uk will require three periods in the domain name to properly function.

  • List Active Surveys:
    Inside of your base phpQ directory, you will find a file called index.php. If List Active Surveys is set to "Yes," this page will contain a list of all of your active surveys along with their descriptions. This is useful if you wish to allow your users to see all of the current surveys that are available. The feature can be turned off by setting List Active Surveys to "No."

    If the fillsurvey.php file (this is what users complete your surveys with) is accessed without any arguments, it will be redirected to index.php in your base phpQ directory.

  • Editor Interface:
    Use the Editor Interface configuration to set whether you wish to see the Advanced or Basic versions of the Survey Editor and Question Editor by default. You can always access either interface when adding or modifying a specific survey or question, so you should set this to the format you most often wish to use.

  • Admin Timeout:
    If this field is set to a positive integer greater than "60" then an administrator who is idle for longer than the value of Admin Timeout will be automatically logged out. This value represents the time in seconds. This helps to insure that if an administrator leaves his computer with the phpQ admin open, he will be logged out after a certain amount of time.

    To turn this feature off, simply enter "0" into the Admin Timeout field and the administrator will no longer be logged off due to idle time. This feature will actually be turned off if the integer is less than 60, to be sure that you always have time to change the value after logging in.

    Note that you will have to login to the phpQ admin every time you open your web browser, as the login is not stored once you close your browser.

  • Summary Display:
    When you access the Survey Results for a specific survey, you will be shown a list of completed entries sorted by Date and showing the IP or Email Address of each respondent as well as any answers to questions you marked Display in Summary within the Question Editor.

    The Summary Display field on the Configuration page determines how many of these survey summaries are shown per page. The default number is 20.

  • Text Input Display:
    When you View Statistics for a specific survey, the results for each question will be shown in detail. When you have a lot of survey submissions, the survey results for a text input field would be very lengthy, as each response will be different. The Text Input Display value specifies how many answers will be shown on the statistics page for a question before you are prompted to "See More..." This makes the size of the statistics/results more manageable. The default for this value is 2.

    Once this value is exceeded, you can use the "See More..." link to view the remaining results. The number of responses per page in the popup window for "See More..." is controlled by the Popup Display value.

  • Popup Display:
    If the Text Input Display value has been exceeded when viewing statistics for the results of a survey, you will be prompted to "See More..." Once you click this link, it will popup a window that shows you the rest of the results to that specific question in the survey.

    The Popup Display number specifies how many results are shown on each page of this popup window. The default is 20.

6.2) Change Administrator Password

If you wish to change the phpQ admin password, you will need to enter the Configuration and complete the following three fields. Once this has been done, you should click the Change Password button:
  • Current Password - This is the current phpQ admin password that you used to login. We require you to enter it to ensure someone doesn't find this window left open and change the password without you knowing.

  • New Password - This is the new password you wish to login to phpQ administration with.

  • Retype Password - We require you to re-type the password to ensure no typos were made, since you cannot see the password as you enter it.
You do not need to complete any of these three fields to modify other options within the phpQ Configuration. NOTE: When changing your password you can also update the other configuration options for phpQ.

6.3) Backup Database

Starting with version 1.2, phpQuestionnaire allows you to backup and restore your phpQ database. This is very useful in case you ever run into a corrupted database or your hard drive crashes. Using the database backup feature, you can be re-installed and running in minutes, without having lost any of your data prior to your last backup. Backing up your database can also be an excellent idea when you are upgrading, in the slight chance something should go wrong.

phpQ allows you to backup the entire database or a single survey and all results to one file. When clicking on the "Download Data" button, you will be prompted to save a file with a .phpQ extension to your machine.

When backing up a single survey, your phpQ configuration information will be omitted. A backup of the entire database, however, will store all of your phpQ configuration in the downloadable file allowing you to restore your installation exactly as it appears at that moment. The exception to this is your phpQ password, which will not be stored in the backup. Whenever restoring from a phpQ backup, your password will remain unchanged.

You can also use the survey backup feature to share a survey and all associated results with a friend who also uses phpQ. However, if you would prefer to share the survey and questions without the results, you should look into the Export and Import features on the Survey Editor page.

6.4) Restore Database

Starting with version 1.2, phpQuestionnaire allows you to backup and restore your phpQ database. This is very useful in case you ever run into a corrupted database or your hard drive crashes. After you have backed up your database, you can be re-installed and running in minutes, without having lost any of your data prior to your last backup. You can import survey results in two ways:
  • Restore Data File
    This line allows you to upload a phpQ backup file and restore your database using that file. Simply click the "Browse..." button find your phpQ backup ('backup_YYYY-MM-DD.phpQ' if you have downloaded all data). Then select your Restore Behavior and click the "Restore Database" button to have your backup restored into the database.

  • Restore From URL
    This field also allows you to restore your database from a phpQ backup file. However, using this row gives you the ability to type in a URL to the location of your phpQ backup file. This can come in useful on occasions where your backup file is greater than the max file upload limit imposed by your server (often 2 MB) or if file uploads aren't working for some other reason. Simply type in the URL to your backup file, select your Restore Behavior and click the "Retrieve Database" button.

One critical aspect to a database restore is the method in which you want the restore operation to behave with respect to your existing phpQ data. This Restore Behavior has two possible options and applies to restoring from a data file or URL:
  • Restore Data: SAVING ALL Current phpQ Data
    This is the default option and ensures that you will lose no data that is currently in your phpQ database. When using this option, no data will be imported to the phpQAdmin table (which covers all phpQ Configuration variables and your password). Only individual surveys, questions, and results will be restored. Furthermore, if any clashing survey ids, question ids or user ids are found, new ones will be generated. This is the safest option for a restore, but will also leave your current data in the database and has the potential to change the URLs you may have used to link to your backed up surveys.

  • Restore Data: ERASING ALL Current phpQ Data
    WARNING! This action cannot be undone. ALL DATA currently in phpQ will be erased and the data found in your backup file will be the only data placed into the restored database. This script will actually drop the current phpQ tables in your database, erasing all data and then insert all of your backup data. This function has the advantage of maintaining all survey, question and user ids in the data and replicating your database exactly as it appeared when you backed it up. Your password will be kept the same. Keep in mind that you may want to backup your current database before erasing all existing data, in case you later find there was information you wanted.

6.5) Rate this Script

We hope that you are extremely satisfied with the phpQuestionnaire program. We have put a lot of time and effort into making it an extremely flexible and easy-to-use, yet powerful, application. If you are pleased, we hope you can take the time to give us a decent rating at a couple of the premier PHP resource sites. These ratings are displayed to other users and allow them to get a better sense for the quality of our program.

To do so, simply select the rating you feel is appropriate, and click on the "Rate It!" button. Please keep in mind you must do this one site at a time.

Even more powerful, if you are so inclined, is to leave a registered member comment about our script. This gives you a voice to express how you feel about phpQ. To do so, simply follow the links that say "Comment on phpQuestionnaire" and you will be taken to the appropriate page on each site. You may need to register in order to leave your comment. Thank you for your feedback and support!

7) Additional Features

7.1) Templates

To create your own templates for phpQ, you must create new directories and files within the templates directory of your phpQ installation.

  • /template_name/
    This directory will hold all files related to your template and should be located in the phpQ/templates/ directory.

  • /images/
    This directory will hold all images required for your template and should be located in the same template's directory. You can locate your image files anywhere, but relative paths in the index.html file will reference within the phpQ/ directory.

  • index.html
    This is the HTML file that the template references. In the default index.html, all image file paths reference the images/ directory as shown in the directory structure above. The location of the images can be anywhere, but you must use full URL paths when calling the images from anywhere outside of the phpQ/ directory. There are several directives you can insert into the HTML file to include the survey and other data:

    • Template Designation
      This line must be the first line of your HTML code. It defines the name of the template as it will appear in the select menu for each survey. This line will not be displayed once the survey is rendered to the user's screen:

      <!--// TEMPLATE: phpQ Default Template //-->

    • ::CHARSET::
      In order for browsers to properly select a character encoding when using multiple languages, you should include an HTML tag such as the following within the <HEAD> of your template:

      <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=::CHARSET::">

      The value of CHARSET will be defined inside of each individual language file.

    • ::SURVEYNAME::
      phpQ will replace this text with the Survey Name you have defined in the Survey Editor for each specific survey. In the default template, this is placed in the <TITLE> tags.

    • ::CONTENT::
      phpQ will replace this text with the survey questions and answers. This tag is required in order to have the survey questions and answers appear on the page.

    • ::PAGENUMBER::
      Use this tag if you would like text such as "Page 1 of 3" to appear on multi-page surveys. The value of PAGENUMBER will be blank on any single-page survey and will be formatted as specified in each individual language file.

    • ::JSCRIPT::
      This will import any required JavaScript into the template. The only time this is needed is if your results are publicly viewable, so that the survey can popup extra results over the configured limit for textfields and other inputs. You are free to leave this out if you will not be offering public results in your template.

Also included in the distribution is a Blank Template, which you can use if you wish to integrate your survey into an existing page using Server Side Includes or a PHP call. Using this, only your survey question(s) will be displayed and you can design the result page content to look however you want. To perform the server side include call, you would use code such as:

<!--#include virtual="/path/to/phpQ/fillsurvey.php?sid=XX-->

Where 'XX' above should be replaced with the survey ID for the specific survey you are calling. You can also perform an inclusion of this script from within another PHP generated page by using the include function with an absolute URL, such as:

include 'http://www.yoursite.com/path/to/phpQ/fillsurvey.php?sid=XX';

Again, you need to replace the actual survey id as well as the correct URL and path to your phpQ directory.

The Dashed Line template is based on a free CSS code from The Layout Reservoir at BlueRobot.com.

7.2) Languages

Version 2.0 of phpQ introduces an easy and flexible way to translate and have available multiple languages for use in both your surveys and the administration panel. The only official support language available and included with the 2.0 release is English. As more language translations are provided by users such as yourself, you can obtain them at http://www.chumpsoft.com/products/phpq/.

Once you have downloaded a language translation, you can unpack it into your base phpQ/ directory and it should go into the languages/ directory, creating a directory specific to that translation. Each individual translation file includes installation help as well.

Translating phpQ into your language:
The process of creating translations has been greatly simplified. The following is the structure of the english language pack. You can modify all or parts of it as follows:
  • phpQ/

  • language_name/
    The first step to creating a new language pack is to create a directory inside of the phpQ/languages directory. The name should be short and representative of the language (in all lowercase, such as french, german, spanish, etc.). All of the translated files and strings will go inside of this directory.

  • index.php
    This file contains all of the translated strings for your language, and is the only file required to be in your language pack. You will need to copy the English version from phpQ/languages/english/index.php over to your new directory, and edit that file to ensure you do not miss any strings. There are several conventions used inside of this file that you must preserve in order for things to work as expected:

    • Language Designation
      Much like our template system, the first line in your language file serves a dual purpose. The first is to open the PHP tag using <? and the second is to alert phpQ to what language this file represents and what specifically has been translated. It should look something like:

      <?       // LANGUAGE: English: PUBLIC|ADMIN|IMAGES|HELP

      It is very important to maintain the formatting shown above. 'English' is the language name that will be shown inside of the admin for easy identification of this translation. PUBLIC, ADMIN, IMAGES and HELP specify what portions of phpQ have been translated in this language and should be separated by | (pipe) without any spaces in the middle. You may change the text 'English' to specify your language and also remove any of the all caps words that you do not intend to translate. You should not translate the text such as PUBLIC or ADMIN, however.

      • PUBLIC
        In order to have a langauge translation, your file must contain at least PUBLIC. This represents that you have translated the text strings within index.php that have the potential to be shown to your visitors through surveys, confirmation emails, etc.

      • ADMIN
        If you would like to have your administration screens and editors appear in your language, you may also translate the administration portion of the index.php file. There is substantially more text involved in the admin as opposed to publicly viewable, and this text will never be seen by visitors to your site.

      • IMAGES
        Once you have translated the administration text, you can send us the file and we will attempt to make images of this text in your language. This will allow even the images that appear within phpQ to be translated into your own language. If no image files are translated, english ones will appear instead.

      • HELP
        HELP is the least likely to appear in your translation. In order to include this, you must translate all of the files found in the help/ directory of the english language, nearly 70 html files! These files are used as popup screens within the admin if the user clicks the help icon next to an item.

    • CHARSET
      Near the top of the index.php file, you will see:

      $phpQlang['CHARSET'] = 'iso-8859-1';

      This character set will define to the web browser how it should render your pages. You must place the appropriate charset into the value of this variable.

    • $phpQlang['__']
      The rest of the file, you will see a large number of text strings being set into the phpQlang array. It is important that you change the text inside of the quotes that appears after the equal sign. The variable names must not be translated, as phpQ uses these to extract the correct string from your file.

      In some places, you may see something like %s or %d appear. In these cases, this indicates that another string may be placed into your translation at run time. For instance, the following appear in the public section of the language file:

      $phpQlang['PageNumber'] = 'Page %s of %s';
      $phpQlang['SurveyExpired'] = 'The survey <B>%s</B> has expired.';

      In the above examples, when phpQ is run and this string is called upon, the appropriate values will be placed inside of the string. For instance, if you are on Page 2 of 10, a 2 will be substituted for the first '%s' and a 10 for the second. Likewise, the survey name you have defined for the specific survey that is expired would appear in the second string. More information on what will be replaced into each string can be found within the english language translation. If you were translating the second string to Spanish, it might read something like:

      $phpQlang['SurveyExpired'] = 'El cuestionario <B>%s</B> ha expirado.';

  • images/
    In most translations, you will not feel the need to include images. These images would only appear within the admin and therefore are usually unnecessary. However, if you would like a totally language immersive experience inside of phpQ and choose to convert the administrative text, you may submit the language file to us and we will attempt to create images with the correct text for your translation. If you choose not to include languages, do not worry, phpQ is smart enough to find the english ones and use them instead. If your language translation has no images, you should omit this directory and also remove the 'IMAGES' from the first line of your index.php file.

  • help/
    Rarely translated, this directory contains all of the popup help screen text that appears when you click on the '?' images within the admin screens. Most people will not want to expend the time to translate these files as you can probably read english if you have managed to buy our product in the first place. However, we leave the option open to you if you wish to create the help screens in your own language! If your translation has no help files, you should omit this directory and also remove the 'HELP' from the first line of your index.php file.

If you have any further questions about how to translate phpQ into your language or use one of the existing translations, please let us know!

7.3) Populating Hidden Question Types

phpQ 3.0 now includes the ability for you to pass information about your respondents to your survey and have this information appear alongside their responses. It is very easy to do and we will show you how below.

Creating the Hidden Question

When you are creating the hidden question, the most important field to note is the Hidden Variable Name field. This will contain the name you will use to pass in the hidden information. For the purposes of this example, let's assume we are passing in the Customer ID. We will set the Question field to 'Customer ID:' and the Hidden Variable Name to 'cid'.

Passing Hidden Information using a Link

Now, let's assume that you are sending an email out to your customers and you have their customer ID that you can use to customize each email. In order to pass this information through to their survey response, you would make sure the link you show them in the email is like:

http://www.example.com/phpQ/fillsurvey.php?sid=SID&cid=####

However, for each email you would make sure that SID is set to the survey ID (this can be found in the normal linking URL to your survey). You then put an '&' after the normal linking URL and add the 'cid=', which is the Hidden Variable Name followed by an equals sign. The '####' in the URL above should be replaced with the actual customer ID.

Passing Hidden Information using a Form

In some cases, you may wish to pass in the hidden information from a web page without the user seeing that there is additional information in the link. Or you may want to have the user click a button on your page to take the survey. If you have users logged into a web site and can change the page depending on the user who is logged in, this method may work best for you. To link a button to the survey, you can do:

<form action="http://www.example.com/phpQ/fillsurvey.php?sid=SID" method="POST">
<input type="hidden" name="cid" value="####">
<input type="submit" value="Take our Survey!">
</form>

As in the link example, you would need to substitute in your actual survey link in the action="" area and place the individual user's customer ID into the hidden field where '####' is shown.

Viewing the Hidden Information in Survey Results

Once the user submits their survey, the hidden information that was passed in will be displayed at the top of a response when the administrator views an individual survey response. This information will not be shown on the private or public summary of results or to your respondents if you have chosen to allow them to view their own response. Continuing from our example above, if the admin views a survey response, they would see:

Customer ID: ####

Other issues

The location of a hidden question within the survey does not have any relation to how it functions. Even if you place the hidden question on the third page of the survey, it can still only be populated from the start of the survey.

Populating hidden fields is made available as a convenience. It cannot be trusted 100%, as a user can modify either the link or the form to pass in different information than you intended.

You can populate multiple hidden questions in either method above. Using a link, you would simply continue to add on '&name2=value2&name3=value3' to the URL. Using the form, add additional hidden input fields similar to the example.

7.4) Manual Installation

In almost all cases, the Automatic Installation should setup phpQuestionnaire to run on your web site. In the case that it fails, you can also manually install this script. After extracting all files from the distribution package, as described in Getting Started, you will have the following directory structure:

phpQ/
  CHANGELOG
  INSTALL
  LICENSE
  README
  admin/
  confirm.php
  docs/
  error.php
  fillsurvey.php
  inc/
  index.php
  install.php
  languages/
  previewquestion.php
  stats.php
  templates/
  verify.php
  view.php
  viewoption.php

Within each of the directories above, you will find many other files and directories. As long as you move the phpQ base directory around as a unit, it will work as expected.

Creating MySQL Tables for phpQ

Now that you have placed this phpQ directory into your web space, you must also create the tables that it will use in MySQL. To do so, you will need access to your MySQL username, password and database. If you are unfamiliar with this data, please ask your hosting provider to supply it. You must now create the following tables. Using the MySQL client, you can simply copy and paste the following SQL statements. Please note, the automatic installer will create these tables and populate them with some simple data to test your setup.

CREATE TABLE phpQAdmin (
  phpQID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  Version CHAR(10) NOT NULL DEFAULT "3.0",
  Passwd VARCHAR(20) NOT NULL DEFAULT "password",
  Template VARCHAR(50) NOT NULL DEFAULT "default",
  Language VARCHAR(50) NOT NULL DEFAULT "english",
  AdminLanguage VARCHAR(50) NOT NULL DEFAULT "english",
  SummaryLimit INT UNSIGNED NOT NULL DEFAULT 10,
  TextareaLimit INT UNSIGNED NOT NULL DEFAULT 5,
  PopupLimit INT UNSIGNED NOT NULL DEFAULT 5,
  AdvanceInterface ENUM("y","n") NOT NULL DEFAULT "n",
  ListSurvey ENUM("y","n") NOT NULL DEFAULT "y",
  TimeOut BIGINT UNSIGNED NOT NULL DEFAULT "0",
  CookieDomain VARCHAR(255) NOT NULL DEFAULT ""
);

CREATE TABLE phpQSession (
  SessionID VARCHAR(255) NOT NULL DEFAULT "",
  RecentTime BIGINT UNSIGNED NOT NULL DEFAULT 0
);

CREATE TABLE phpQSurvey (
  SID BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
  Name VARCHAR(255) NOT NULL DEFAULT "",
  AddDate DATETIME NOT NULL DEFAULT "0000-00-00",
  SurveyUsers CHAR(3) NOT NULL DEFAULT "000",
  SurveyResults TINYINT NOT NULL DEFAULT 0,
  Width VARCHAR(255) NOT NULL DEFAULT "",
  Indent INT UNSIGNED NOT NULL DEFAULT 20,
  QuestionNumb ENUM("y","n") NOT NULL DEFAULT "y",
  QuestionStyle VARCHAR(255) NOT NULL DEFAULT "",
  AnswerInputStyle VARCHAR(255) NOT NULL DEFAULT "",
  AnswerTextStyle VARCHAR(255) NOT NULL DEFAULT "",
  AnswerStyle VARCHAR(255) NOT NULL DEFAULT "",
  ErrorStyle VARCHAR(255) NOT NULL DEFAULT "",
  VerifyEmail TEXT NOT NULL DEFAULT "",
  EmailFrom VARCHAR(255) NOT NULL DEFAULT "",
  EmailSubject VARCHAR(255) NOT NULL DEFAULT "",
  Template VARCHAR(50) NOT NULL DEFAULT "",
  Language VARCHAR(50) NOT NULL DEFAULT "",
  OnComplete TINYINT NOT NULL DEFAULT 0,
  RedirectURL TEXT NOT NULL DEFAULT "",
  Completed TEXT NOT NULL DEFAULT "",
  Description TEXT NOT NULL DEFAULT "",
  AdminNotes TEXT NOT NULL DEFAULT "",
  Active ENUM("y","n") NOT NULL DEFAULT "n",
  StartDate DATETIME NOT NULL DEFAULT "0000-00-00",
  EndDate DATETIME NOT NULL DEFAULT "0000-00-00",
  AdvanceInterface ENUM("y","n") NOT NULL DEFAULT "n",
  ResultsWidth VARCHAR(255) NOT NULL DEFAULT "",
  ResultsBorder VARCHAR(255) NOT NULL DEFAULT "",
  ResultsAnswer VARCHAR(255) NOT NULL DEFAULT "",
  ResultsStats VARCHAR(255) NOT NULL DEFAULT "",
  ResultsGraph VARCHAR(255) NOT NULL DEFAULT "",
  SubmitImageSrc VARCHAR(255) NOT NULL DEFAULT "",
  SubmitImageWidth INT UNSIGNED NOT NULL DEFAULT 0,
  SubmitImageHeight INT UNSIGNED NOT NULL DEFAULT 0,
  SubmitImageText VARCHAR(255) NOT NULL DEFAULT "",
  ResultImageSrc VARCHAR(255) NOT NULL DEFAULT "",
  ResultImageWidth INT UNSIGNED NOT NULL DEFAULT 0,
  ResultImageHeight INT UNSIGNED NOT NULL DEFAULT 0,
  ResultImageText VARCHAR(255) NOT NULL DEFAULT "",
  NextImageSrc VARCHAR(255) NOT NULL DEFAULT "",
  NextImageWidth INT UNSIGNED NOT NULL DEFAULT 0,
  NextImageHeight INT UNSIGNED NOT NULL DEFAULT 0,
  NextImageText VARCHAR(255) NOT NULL DEFAULT "",
  ResponseNotice TINYINT NOT NULL DEFAULT 0,
  ResponseEmail TEXT NOT NULL DEFAULT ""
);

CREATE TABLE phpQQuestion (
  SID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  QID BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
  SortOrder INT UNSIGNED NOT NULL DEFAULT 0,
  Question TEXT NOT NULL DEFAULT "",
  Type ENUM("radio","checkbox","textfield","textarea","hidden","select","selectmult","pagebreak","htmlcontent","redirect") NOT NULL DEFAULT "radio",
  RedirectTo VARCHAR(50) NOT NULL DEFAULT "",
  RedirectURL TEXT NOT NULL DEFAULT "",
  HiddenName VARCHAR(255) NOT NULL DEFAULT "",
  Mult INT UNSIGNED NOT NULL DEFAULT 1,
  QuestionStyle VARCHAR(255) NOT NULL DEFAULT "",
  Instructions TEXT NOT NULL DEFAULT "",
  Choose VARCHAR(11) NOT NULL DEFAULT "",
  DefaultAnswer TEXT NOT NULL DEFAULT "",
  LargestAID INT UNSIGNED NOT NULL DEFAULT 0,
  ColNumb INT UNSIGNED NOT NULL DEFAULT 1,
  AnswerInputStyle VARCHAR(255) NOT NULL DEFAULT "",
  AnswerTextStyle VARCHAR(255) NOT NULL DEFAULT "",
  AnswerStyle VARCHAR(255) NOT NULL DEFAULT "",
  Attributes TEXT NOT NULL DEFAULT "",
  Required ENUM("y","n") NOT NULL DEFAULT "y",
  Summary ENUM("y","n") NOT NULL DEFAULT "n",
  Results ENUM("y","n") NOT NULL DEFAULT "y"
);

CREATE TABLE phpQAnswerChoice (
  AID BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
  QID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  SID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  Label TEXT NOT NULL DEFAULT "",
  Sort INT UNSIGNED NOT NULL DEFAULT 0,
  TextField ENUM("y","n") DEFAULT "n",
  Selected ENUM("y","n") DEFAULT "n",
  Selectable ENUM("y","n") DEFAULT "y",
  BranchTo BIGINT UNSIGNED NOT NULL DEFAULT 0,
  KEY index_qid (QID),
  KEY index_sid (SID)
);

CREATE TABLE phpQUser (
  UID BIGINT UNSIGNED NOT NULL PRIMARY KEY,
  SID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  IPAddr VARCHAR(100) NOT NULL DEFAULT "",
  BlockDupe VARCHAR(40) NOT NULL DEFAULT "",
  CheckType CHAR(3) NOT NULL DEFAULT "000",
  Email VARCHAR(255) NOT NULL DEFAULT "",
  Confirm VARCHAR(50) NOT NULL DEFAULT "",
  EmailConfirm ENUM("y","n") NOT NULL DEFAULT "n",
  CompleteDate DATETIME NOT NULL DEFAULT "0000-00-00"
);

CREATE TABLE phpQAnswer (
  UID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  SID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  QID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  AID BIGINT UNSIGNED NOT NULL DEFAULT 0,
  Answer TEXT NOT NULL DEFAULT "",
  UNIQUE uniqids (SID, QID, AID, UID),
  INDEX index_uid (UID),
  INDEX index_aid (AID)
);

You must also create the default administrator account for this installation by inserting the following row:

INSERT INTO phpQAdmin VALUES (1, '3.0', 'password', 'default', 'english', 'english', 10, 5, 5, 'n', 'y', 0, '');

Configuring phpQ and MySQL

After setting up the tables used by phpQuestionnaire, you will need to edit the file 'phpQ/inc/mysql.php' that is part of the distribution. Inside of this file, you will see 4 lines that look like:

$host = "localhost";
$user = "";
$password = "";
$database = "phpQ";

You must fill in the proper values for all of these items according to your MySQL setup. If you are uncertain, please contact your web hosting provider for the necessary information.

Removing Installation Files

Since you have chosen a manual installation, you can now also delete the file 'phpQ/install.php'. This is a very important step, as leaving this file in place could allow a hacker to re-install the phpQ files.

Completion

Your phpQuestionnaire program should now be successfully installed. Proceed to Logging in as Administrator to begin using phpQ.

7.5) XML Format

phpQuestionnaire offers you the ability to download your survey results in several formats. Two of these formats use the eXtensible Markup Language. The following is a brief description, using our Document Type Definitions (DTD):

XML Format
This XML document was designed to be easily read by humans. It can, however, become VERY large as more and more results are entered. For something more compact, you should read into our XML Condensed Format shown further below.

The XML Format we use encloses everything in <survey>. This tag then contains a <name> of the survey, an optional <description> and 0 or more <result> tags. Each <result> tag then contains a <time>, <ip> and <email> tag corresponding to the date completed, the user's IP Address and optionally the user's Email Address (if email verification is being used). The <email> tag will also have an attribute of verified set to 'y' or 'n'. The <result> will also contain 0 or more <question> tags which contain an <asked> tag (supplying you the question that was asked) and 0 or more <answer> tags. Each <answer> contains either a <selected> tag (which holds the text of the answer a user selected from a radio button, select field, etc.), an <entered> tag (which contains any text a user entered into a textfield or textarea) or both (such as a checkbox with a textfield).

The following is the DTD for this XML file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE survey [
  <!ELEMENT survey (name,description?,result*)>
  <!ELEMENT name (#PCDATA)>
  <!ELEMENT description (#PCDATA)>
  <!ELEMENT result (time,ip,email?,question*)>
  <!ELEMENT time (#PCDATA)>
  <!ELEMENT ip (#PCDATA)>
  <!ELEMENT email (#PCDATA)>
  <!ELEMENT question (asked,answer*)>
  <!ELEMENT asked (#PCDATA)>
  <!ELEMENT answer (selected?,entered?)+>
  <!ELEMENT selected (#PCDATA)>
  <!ELEMENT entered (#PCDATA)>

  <!ATTLIST survey id CDATA #REQUIRED>
  <!ATTLIST result id CDATA #REQUIRED>
  <!ATTLIST email verified (y|n) #REQUIRED>
  <!ATTLIST question id CDATA #REQUIRED>
  <!ATTLIST question type (checkbox|radio|select|selectmult|textfield|textarea) #REQUIRED>
  <!ATTLIST answer id CDATA #IMPLIED>
]>


XML Condensed Format
The condensed format is normally about one quarter the size of our human readable formatting. It achieves a smaller footprint by refusing to repeat question names and answer values over and over. Instead, the survey configuration is listed in a <config> tag. This tag contains a <name>, optional <description> and 0 or more <question> tags. Each <question> and <answer> contain id's unique within this survey. The <question> tag also contains the question type as an attribute and the <asked> tag with the text of the question asked. Each question contains one or more <answer> tags which contain an id (referenced later) and the text shown for that answer. If this is a textfield or textarea results, the text will be the default text for that field.

Now that the survey has been defined, each response to this survey will be listed in a <r> tag which contains attributes of id, time, ip, email and verified corresponding to the unique user id, time of completion, IP Address and Email Address (if the survey uses verified email) and whether or not that Email Address was verified. Within each <r> result tag are multiple <a> tags containing this user's answer to each question. Each <a> tag contains an id and qid attribute. This defines the question id and corresponding answer id within that question to the selected choice. If the user entered any text for the question (such as a textfield or textarea) the answer will be contained within the <a></a> tags. If this was a textfield or textarea style question, no id attribute will be available for the <a> tag. You can use a given qid and id within an <a> tag to match the corresponding text value of that answer within the <config><question><answer> hierarchy.

The following is the DTD for this XML file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE survey [
  <!ELEMENT survey (config,r*)>
  <!ELEMENT config (name,description?,question*)>
  <!ELEMENT name (#PCDATA)>
  <!ELEMENT description (#PCDATA)>
  <!ELEMENT question (EMPTY|(asked,answer*))*>
  <!ELEMENT asked (#PCDATA)>
  <!ELEMENT answer (#PCDATA)>
  <!ELEMENT r (a*)>
  <!ELEMENT a (#PCDATA|EMPTY)*>

  <!ATTLIST survey id CDATA #REQUIRED>
  <!ATTLIST question id CDATA #REQUIRED>
  <!ATTLIST question type (checkbox|radio|select|selectmult|textfield|textarea|pagebreak) #REQUIRED>
  <!ATTLIST answer id CDATA #IMPLIED>
  <!ATTLIST r id CDATA #REQUIRED>
  <!ATTLIST r time CDATA #REQUIRED>
  <!ATTLIST r ip CDATA #REQUIRED>
  <!ATTLIST r email CDATA #IMPLIED>
  <!ATTLIST r verified (y|n) #IMPLIED>
  <!ATTLIST a qid CDATA #REQUIRED>
  <!ATTLIST a id CDATA #IMPLIED>
]>

If you wish to learn more about XML, you should check out:

7.6) Getting Support

When you purchased phpQuestionnaire, you also purchased the ability to contact us for email based technical support any time in the first year of ownership. You can email us at any time at support@chumpsoft.com.

You can also obtain support on the web. Simply go to http://www.chumpsoft.com and sign into our member's area. This is the same area that you entered in order to download this script.

phpQuestionnaire v3.1 © 2006 chumpsoft, inc.