1) Getting Started
Once you have purchased a copy of phpQuestionnaire Junior, 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:
Download the file phpQJr_vX.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 'phpQJr'. 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 phpQJr_vX.tar.gz. Once you have retrieved this file, you should place it in a directory on your web server and enter the following commands:
tar xvf phpQJr_vX.tar
It will unpack into a directory named 'phpQJr'. 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:
- When unpacking the files, they will all be placed in appropriate locations within a base directory of 'phpQJr/'. Move or Upload this directory onto your web server into a location accessible from your browser.
- If phpQ Jr. is being hosted on a Unix based machine, you must change the permissions of the file 'phpQJr/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 phpQJr/ directory of your installation. Issue the following command:
chmod 766 inc/mysql.php
At the end of the installation we will ask you to change permissions on this file again.
- Load up the installation page by opening your web browser and going to the following URL:
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 Jr. program.
- You will now see a page in your web browser that looks like:
|Figure 1.1-01 - Automatic Installation|
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
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 Junior 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 'phpQJr'. In either case, please enter the name of your MySQL database into this box.
You may now click the 'Install' button and phpQuestionnaire Junior will automatically install the script (setting up the database), alerting you to any errors it may encounter.
- Upon successful installation, you will see the following screen:
|Figure 1.1-02 - Automatic Installation : Success|
- If all of the items say success, phpQ Jr. 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. In UNIX, issue the following command, much like you did before:
chmod 644 inc/mysql.php
- It is crucial that you also remove the install.php file once you have successfully setup phpQ Jr. You need to delete the file 'phpQJr/install.php' possibly using the following command (if you are still in the phpQJr/ directory of your installation):
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 Jr. without your authorization.
- 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.2 - Manual Installation.
1.2) Logging in as Administrator
When logging into the phpQuestionnaire Junior administration section, you will be presented with a screen that looks like:
|Figure 1.2-01 - Admin Login|
For the first time...
If you have just installed phpQ Jr. 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 Junior 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 Jr. administration. For further information, see Changing Administrator Password.
Again and again...
To access the phpQ Jr. Administration panel in the future, simply point your web browser to:
You obviously must modify the above URL to contain your actual domain name and the path to where you have installed the phpQ Jr. program on your web server.
1.3) Administration Panel Sections
After logging in to the administration panel, you will find 6 tabs at the top (the current section will be highlighted):
This link will return you to the Poll Overview that offers quick access to editing, previewing or viewing the results of any specific poll or group. This is the page that you see when you first login.
- Poll Editor
This link directs you to a form for modifying an existing poll or adding a new one. From here you can also activate or deactivate any poll as well as export or import polls.
- Group Manager
This section allows you to group polls together that you can then display randomly, on a timed basis, linked together in a chain, etc.
From this area you will be able to access the results pertaining to any poll you have created.
This area of the administration allows you to alter the way the phpQ Jr. admin panel works. For instance, what polls or groups to display, what template should be used by default, etc.
- Log Off
Click this tab when you are done using the phpQuestionnaire Junior administration panel. Alternatively, quitting out of your web browser will end your session as well.
2) Poll and Group Overview
|Figure 2-01 - Poll and Group Overview|
The Poll and Group Overview page displays each poll and group that has been created. To the left of the poll you will find an image that describes the state of the poll. The following images may appear next to each poll (only active and expired will appear next to a group):
A link to an individual poll's results is provided to the right of the poll's name. This link will also inform you of how many responses to that poll currently exist. Quick links to edit or preview the poll are also available. If a description has been entered for a poll, it is displayed beneath the poll listing.
This image appears any time the public is allowed to take your poll. This means that it has been manually activated and if a starting or ending date has been specified, it is within those bounds.
This image appears when a poll has been manually activated, but the public is not yet allowed to take the poll as it has not reached the starting date.
If a poll 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 poll, but you may wish to manually deactivate it.
This image will appear if your poll is active, but you have used time restrictions to determine when the poll should be available. In this case, it is too early in the day for the poll to be displayed.
This image will appear if your poll is active, but you have used time restrictions to determine when the poll should be available. In this case, it is too late in the day for the poll to be displayed.
This image will appear if you have manually deactivated a poll. No users will be allowed to complete the poll in this state.
You will notice that an image appears beneath the admin panel section tabs. 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 commonly state that no updates or announcements exist for the current version.
3) Poll Editor
The poll editor is where all modification and configuration of a specific poll is to be done. This is also where you should go if you wish to add a new poll, remove a poll or edit questions. At the top of the Poll Editor you will see a selection box allowing you to select the specific poll you wish to manage. It will appear something like:
|Figure 3-01 - Poll Editor|
Once a specific poll has been selected, the page will automatically refresh and you will see:
|Figure 3-02 - Poll Editor: Poll Selected|
You now have access to the following actions which can be performed on this poll:
- 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 poll you have created.
- Preview - Clicking on this button will popup a new window that allows you to preview your poll. You cannot submit any results, this function is just for viewing the final appearance of your poll.
- Activate or Deactivate - When your poll is created, it defaults to a Deactivated state. This allows you to fully complete and preview the poll without users being able to access it. Once your poll is finalized and ready to go live, you should activate the poll by clicking the Activate button. Any starting and ending dates or times will still be enforced on an active poll. You can stop any submissions on the poll by clicking the Deactivate button on an active poll.
- Export - You can export a poll, along with all questions, into a single file which will allow you to swap this file with another user of phpQ Jr. That person can then import the poll using the form at the bottom of the Poll Editor. Poll Results will not be included in this export. If you wish to back those up, you should check out the Configuration tab.
Below each poll you will find three informational fields that help you link and manage your poll:
- Link to Poll - This provides a copy-and-paste URL that you can use to link to your poll from any page on your domain. If you are linking from outside of your domain name, you will need to make this a full URL by adding http://www.yourdomain.com to the front of the provided URL.
If a poll 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 poll, but you may wish to manually deactivate it.
- Link to Results -This provides a copy-and-paste URL that you can use to link to your poll results from any page on your domain. If you are linking from outside of your domain name, you will need to make this a full URL by adding http://www.yourdomain.com to the front of the provided URL. This URL will only be active if you have chosen to allow Public Results.
- In Group - If the poll does not yet belong to a group, a link to add the poll to a group will appear. This link will take you to the Group Manager. If the poll already belongs to one or more groups, there will be links to the Group Manager to edit each of the groups this poll belongs to.
3.1) Adding or Modifying a Poll
The next portion of the Poll Editor contains the form used for adding and modifying polls within phpQuestionnaire Junior.
If a poll has been selected within the Poll Editor, the setup for that poll will be placed into the "Add/Modify a Poll" 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 poll with the values you have entered, while clicking Modify will simply update the existing poll with the new configuration.
|Figure 3.1-01 - Poll Editor: Add/Modify a Poll|
- Poll Name
This field is used within the phpQ Jr. admin interface to refer to the specific poll that you are creating or modifying.
This value can also be substituted into poll templates using the marker ::POLLNAME::. In the default phpQ Jr. template, this value appears in the title bar of the user's browser.
- Poll Info
This field contains text that will be displayed on the Poll Overview page which lists all of your active and inactive polls. It is only there if you wish to provide a brief summary of the purpose or contents of this poll.
- Poll Template
The Poll Template field allows you to select the template that you wish for this poll to appear in. You can download more templates for phpQ at http://www.chumpsoft.com/products/phpqjr/.
The program checks in your phpQJr/templates directory in order to determine what templates are available for use in your polls. Removing the files from this directory will cause phpQ Jr. to stop functioning properly.
The values you can use inside of your template that phpQ Jr. will recognize are:
- ::POLLNAME:: - phpQ Jr. will replace this text with the Poll Name. In the default template, this is placed in the <TITLE> tags.
- ::CONTENT:: - phpQ Jr. will replace this text with the poll questions and answers when called for. This may be empty in the case of a single poll that is displaying statistics instead of content. This tag is required in order to have the poll questions and answers appear on the page.
- ::STATS:: - phpQ Jr. will replace this text with the poll statistics when called for. This may be empty in the case of a single poll that is displaying the questions or if public results are turned off. This tag is required in order to have results appear on the page.
- ::ERROR:: - If there is an error in the user submission or poll operation, it will appear where this text is located.
- Poll Tally
The Poll Tally field shows the running count of how many users have completed your poll. You can easily modify this number to provide any total you wish for your polls. By default, when modifying a poll, you will not alter this field. If you wish to manually change this field from the actual number of responses, you must change the textfield and click the checkbox next to 'Update'. This ensures the count will only be changed by you if you wish.
- Display Between
In some cases, you may wish for a particular poll to only be shown during a certain time period of each day. To accomplish that, simply set the hours to restrict the times of the day when your poll will be available. Used in a group of polls, you can set up your polls to change each hour of the day if you wish.
This field defaults to 00:00:00 - 23:59:59 so that your poll will be shown during all times of the day. To restrict this, simply change the selects to the desired times when you poll should be active.
- Starting Date
- Ending Date
phpQ Jr. provides a way in which you can set up polls with specific starting and ending dates. If you are not using starting and ending dates, you must manually activate and de-activate the poll when you wish for it to be available or taken down. The starting and ending dates allow you to activate the poll and have phpQ Jr. 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 to expire the poll at the end of a day.
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 poll, but have a pre-defined end time, you only have to set the Ending Date.
- Starting Date - By setting these fields to a valid date and time, phpQ Jr. will not allow anyone to fill out the poll 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 poll after that specific time.
Starting and Ending dates can also be used within a group in order to setup a daily or weekly poll of sorts. Simply create multiple polls with correct starting and ending dates/times so that as one poll expires the next comes to life. Then reference that group from within your site and you can have polls that change over time. Read the manual for more information on this.
- User Restrictions
Restrictions can be used to attempt to limit the number of votes to one per user per poll. They are also effective in stopping accidental duplicate votes. They aren't, however, 100% effective and a determined user will still be able to make multiple poll votes. You are allowed to select either or both of the following options. Selecting none of them will allow any user to vote on the poll as many times as they wish:
- Unique IP Address - You can use a user's IP address as one method of blocking multiple poll responses 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 poll if two different users are on the same IP address, and in other cases a user could simply change computers to vote on the poll twice. In any case, it does provide protection against accidental duplicate votes or someone who is not determined to vote more than once.
- Cookies - Using this restriction, phpQ Jr. will attempt to place a cookie in the user's browser each time they complete a poll. If phpQ Jr. detects they have already completed the poll, they will not be allowed to make another vote. In order for this to work, the user must have cookies enabled. You can also set how long you wish for the cookie to last. For instance, if you wanted to allow a user to vote once per day, you would set it to expire after 1 day.
- Public Results
Setting this field to 'Yes' will allow your users to see the results of the poll. You can also run private polls where only the administrator can know the results by setting this field to 'No'.
- Public Textfield
Setting this value to 'Yes' will allow your users to see any entered text that users may place in 'other' fields of your poll. You can also run polls where only the administrator can see the textfield results by setting this field to 'No'. If Public Results is set to No, this field will become irrelevant, as no results will be displayed publicly.
If you choose to set this field to 'Yes', the textfield results will be linked with the text "See More" and will popup in a new window. You can control the size of this window (so it fits well with your template and text) using the Width and Height parameters shown here. You can also control the number of textfield responses on each page using the Limit field. If there is overflow, links to additional pages will be presented to the user.
- Show In Menu
Setting this field to 'Yes' will allow your users to view this poll's name, description and links in the menu of available polls. The file that displays this menu can be seen from the index.php file in your base phpQJr/ directory. If you wish to hide this poll from that page, and have it only accessible from where you choose to link it, change this field to 'No'.
- Submit Buttons Style
- Result Buttons Style
phpQ Jr. allows you to completely customize the 'Submit' and 'View Results' buttons, changing the text, width and height of the button or even turning it into an image! The Result button will only appear if you have selected to have Public Results. If you wish to have public results, but omit a button from the poll to the results, set all of the fields empty in your Result Button Style.
- Text - Changing this field will change the text shown on the poll's submit or results button. If you decide to make this an Image button, the Text will be used as the image's alternative text.
- Width - This field controls the width of your button, either using CSS for a text-based button or as the width parameter of the image tag if you choose an image-based button.
- Height - This field controls the height of your button, either using CSS for a text-based button or as the height parameter of the image tag if you choose an image-based button.
- Image - You can use images for your buttons by placing a URL to the desired image in this field. Choosing an image will cause the Text, Width and Height tags to be used as parameters in the image tag.
- Completion Notice
This field is the message that will be displayed to the user once they have successfully completed this poll. It will be displayed with the results from the poll, if you have selected Public Results. You are free to use any HTML you wish and it will be shown in the ::CONTENT:: area of the Poll Template as entered.
- Redirect URL
This field can be used if you wish to send a user to a specific URL once they have completed the poll. The default results page for a poll will be to show the stats (if they are public) along with the completion notice. You can bypass this, and send them to another page by entering the full URL (beginning with http://) into this field.
3.2) Import Poll
|Figure 3.2-01 - Poll Editor: Import Poll|
phpQuestionnaire Junior allows you to import a poll that has been previously created. This is great if you have colleagues or friends using a separate phpQ Jr. installation and you wish to share your polls with others. If you have obtained a poll export from someone else, or from the chumpsoft web site, simply click on the "Browse..." button to locate this file on your hard drive. Once you have selected the file, click "Import Poll".
You can also simply plug in a URL from which to fetch the poll. This URL must contain the location of a poll swap data file. Once entered, simply click the "Retrieve Poll" button and the poll will be made available for you to edit, add to or simply display to your users!
If you ever have a poll you would like to make available to other phpQ Jr. users, all you have to do is use the Poll Editor to select the desired poll and then click the button "Export". This will present you with a file that you can give to others, or email to firstname.lastname@example.org for us to share on our web site.
4) Question Editor
After creating a Poll with the Poll 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 poll. At the top of the page will be the name of the poll and a list of questions for this poll. An example list of questions is shown below in 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 poll.
If you wish to edit a particular question, select that question and click this button. It will load the question's current information in the form below and allow you to make modifications.
Clicking this button will delete the currently selected question from the poll. This cannot be un-done.
- Save Order
Using the up and down arrows on the right of the question list, you can re-order the questions in your poll. After doing so, if you wish to save your changes, click the Save Order button.
This button will pop up a window and display the selected question in your poll using the current settings. You will not be able to submit the poll.
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 poll. 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.
The first step in creating a new question for your poll is to select the question type. When you are adding a new question, you must select the type from the following:
|Figure 4.1-01 - Question Editor: Select Question Type|
Once you have selected the type, or if you have chosen to edit an existing question, you will be prompted with the complete Add/Modify Question form. 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.
|Figure 4.1-02 - Question Editor: Radio Button|
The value of this field is what the user will be asked when completing this question in the poll. You are free to type either text or HTML into this field and it will be displayed on the poll exactly as you have entered it.
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 poll.
Due to the format of results in the database and the differences in the number of answers that can be selected with each type, you cannot modify the type of a question after it has been created, except to add it as a new question.
- 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. 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.
- 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 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.
- Answer Choices
This field contains a listing of all of the current answers as well as the ability to add to, change the order of, modify or delete the answers. The following will guide you through the functionality of this field:
The largest input area in this 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 poll, 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 Textfield checkbox (this option is only available for Radio Buttons and Check Boxes). The user of the poll will then have the option of filling in a custom text response when that specific answer is selected.
You can select a specific Bar Color for any of your answer choices. This will be the color used for the bar graph on this specific answer within the results for your poll. In this way, you can have different answers have different colored results bars. You should enter the 6 hex digits for the number corresponding to the RGB values.
By changing the Tally field for a specific question, you can edit the number of responses that particular answer has received in the poll. In most cases you will want to leave it the same, unless you wish to start the poll off with a certain number of votes. Tallies can also be changed from the admin Results page.
When adding an answer, you will also have the option of making it a pre-selected choice for the user taking the poll. This option appears as a checkbox next to the word Default Choice and is available for all question types. If you check that field, the answer will already be selected or checked when the user takes the poll. 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 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 the default choice and unselectable. In this case, when the user takes the poll, 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.
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 Answer button.
To remove an answer from the Answer Choices simply select the answer you wish to remove and then click on the Delete Answer button. Doing so will remove the answer from the current question.
- Question Style
- Answer Style
In these fields you may enter any CSS style definition that you wish to have applied to the question or answer text. If you wanted to have your question appear in a green, Verdana font of size 12px, you would enter:
font-family: verdana; font-size: 12px; color: green;
The question text would appear as:
What is your question text?
The style definitions will be placed inside of the <TD> that surrounds each question. Also, the Answer Style definitions will be applied inside of <SELECT> elements, allowing you to edit text in those.
To find out more about CSS styles, go to Zvon.org CSS1 Reference.
- Textfield Style
In this field you may enter any CSS style definition that you wish to have applied to all text field answer inputs with the current question. If you wanted your 'Other:' text field 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.
To find out more about CSS styles, go to Zvon.org CSS1 Reference.
- Number of Columns
This field appears 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.
This field allows you to select a template that you wish for this question to be formatted with. This is separate from the overall Poll Template, which governs the look of your entire poll. In nearly all cases, you will just want to use the default question templates corresponding to the question type. In some cases, you may want to layout your questions in a rather unusual way. In order to do this, you should read the User Manual which explains question templates in detail.
You can download more question templates for phpQ Jr. at http://www.chumpsoft.com/products/phpqjr/.
The program checks in your phpQJr/templates/qtype/ directory in order to determine what templates are available for use in your polls. Removing the files from this directory will cause phpQ Jr. to stop functioning properly.
5) Group Manager
phpQuestionnaire Junior allows you to group polls together and use these groups to display the polls in various ways. You can set them up to display the polls in a random order or display a different poll according to the time of day. You can create poll chains or have a poll of the week. If you wish to modify an existing poll, select it from the list:
|Figure 5-01 - Group Manager|
The following options will appear:
Clicking on this button will popup a new window that allows you to preview the group. This really just shows you either the first poll in the group or a random one.
When your group is created, it defaults to a Deactivated state. This allows you to fully complete and test the group without users being able to access it. Once your grouping is finalized and ready to go live, you should activate it by clicking the Activate button. Any restrictions, such as starting and ending dates, for individual polls will still be enforced on an active group.
- Link To Group
This link provides a copy-and-paste URL that you can use to link to your group of polls from any page on your domain. If you are linking from outside of your domain name, you will need to make this a full URL by adding http://www.yourdomain.com to the front of the provided URL.
5.1) Adding or Modifying a Group
|Figure 5.1-01 - Add/Modify a Group|
Beneath the Choose a Group section is the Add/Modify Group form from which you can create and edit your groups. If a group has been selected, the form will contain that groups information, but if no group is selected the form will be empty. By clicking the Add button at the bottom, you will add a new group with the information currently in the form. When a group is selected, the Modify button will appear. Clicking this will save the selected group with the information in the form. If there is already information in the form and you wish to start from an empty form, you can click the Clear Form button to remove any information in the form. Details on what the fields are and how to use them are listed below:
- Group Name
This field is used within the phpQ Jr. admin interface to refer to the specific group that you are creating or modifying. It may also be displayed on the menu page of phpQ Jr. if you choose for this group to be displayed in the menu of active polls.
- Group Info
This field contains text that will be displayed on the Poll Overview page which lists all of your active and inactive polls. It is only there if you wish to provide a brief summary of the purpose or contents of this group.
- Polls In Group
This area is where you define the polls that any specific group will contain. If you choose to show multiple polls after each other, the order will be determined by the order the polls appear in this select box. You can change this order by using the Up and Down arrows to the right of the box, once you have selected a poll from the list.
To add a poll to your group, simply select it from the Select Box that says '-- Select a Poll to Add --'. Once you have selected a poll, it will be added to the list and this box will return to the unselected position. To remove a poll from the list, select it from the Polls in Group list and click the 'Remove Poll From Group' button.
Once you have selected the polls you wish to appear in this group and have corrected the order (which only matters if you have Randomization turned off), you may Add or Modify the group to save your changes.
- Show In Menu
Setting this field to 'Yes' will allow your users to view this group's name, description and links in the menu of available polls. It will appear alongside other polls, just as if it was a poll. The link, however, will lead to the group of polls, which can be displayed randomly, on a time basis, etc.
The file that displays this menu can be seen from the index.php file in your base phpQJr/ directory. If you wish to hide this group from the menu, and have it only accessible from where you link it, change this field to 'No'.
One way in which groups can be used in phpQ Jr. is by setting up multiple polls and allowing the user to step through them one at a time, taking each poll and seeing the results on the next page, along with the next poll. You can also use groups to simply show one from a series of polls on your main page each time. In either of these cases, you may wish to make the order of appearance random. By setting the Randomize field to 'Yes' your group will always start in a random spot within your list. Should you choose to have your group cycle to the next poll, the next one will be randomly selected from the list of polls the user has not taken.
5.2) Ideas for Usage of Poll Groups
chumpsoft attempts to stay innovative with all of our products, and the way in which we have done so with our polling software is through the use of poll groups. These groups allow you to combine polls and offer them to your visitors in a variety of ways, several of which have been detailed below:
5.2.1) Create a chain of polls
The way in which our template system has been laid out allows you to specify a single file that can be used for the poll, the results or both. Utilizing this, the default method of any group of polls is to simply forward on to the next poll once a user has completed the first one. After completing the first poll, the user will be taken to the next poll and shown the results from their previous poll (if public) along with the next poll in the group, until they have completed all of the polls. These polls can be in a forced order or shown randomly, depending on whether you have set the randomization option within the group editor.
This chaining of polls is simply the default method of displaying a group of polls.
5.2.2) Rotate in a new poll each week
Many sites like to setup a weekly poll, but it can be a hassle to have to go in and manually change it constantly. Poll groups allow you to setup the polls for separate weeks far in advance, and just let the script handle the appropriate timing for display of each poll.
In order to set this type of system up, create several polls using the poll editor, to specify the weekly Starting and Ending Dates for each poll, so there is no overlap. You would then create a group of these three polls using the group manager to add them into the polls in group. When linking to your "weekly poll" you would then want to use the "Link to Group" for that specific group, as shown on the group manager section of the admin. Your polls will then automatically change weekly, and users will be shown the correct poll or results based on when they visit your web site. You can always link to past polls using the individual poll results links, allowing the user to see the results without the ability to vote after that week is up.
5.2.3) Show a different poll based on the time of day
This feature can work in much the same way as the weekly poll described above. Instead, simply define the appropriate time ranges for each poll on the poll editor in the Display Between parameter so that each poll will be displayed during separate times of the day. Then link to the specific group of polls from your web site and have them displayed.
6) Poll Results
Using this tab, you can view the results of any poll you have created. Once you select a poll from the list, the results are displayed below:
|Figure 6-01 - Poll Results|
The question is shown at the top, followed by each answer. To the right of each answer is the number of votes that answer received and, in parentheses, the percentage of total votes that the answer received. Beneath each answer is a bar that represents the number of votes this answer received in relation to the other answers. Together, the bars for each answer give you a visual indication of how many votes each answer received. If there are multiple questions in the selected poll, the results for each question are displayed below in the order they appear in the Question Editor.
Clicking the "Configuration" tab at the top of the phpQ Jr. Administration Panel allows you to setup various defaults and customizations for the phpQ Jr. program. This is also where you should go to change your password. The administration screen looks like:
|Figure 7-01 - Administration Configuration|
Clicking Modify Options will implement any changes you have made to the following options:
7.1) Set Administration Variables
- Menu Template:
This field allows you to select the template that you wish to be used on the public poll list page in phpQJr/index.php. When this file is accessed, it will generate a list of the currently active polls or groups if you have allowed Show in Menu on the individual poll or group.
You can download more templates for phpQ Jr. as they become available at http://www.chumpsoft.com/products/phpqjr/.
The program checks in your phpQJr/templates/ directory in order to determine what templates are available for use in your polling program. Removing the files from this directory will cause phpQ to stop functioning properly.
- Cookie Domain:
This allows you to set a specific domain name for phpQ Jr. to use when setting cookies. This can be extremely important to prevent a loophole in cookie restrictions for users taking a poll.
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 poll 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.
- 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 helps to insure that if an administrator leaves his computer with the phpQ Jr. admin open, he will be logged out after a certain amount of time.
Setting this value to less than 60 will cause the Admin Timeout to be set at a day. Note that you will have to login to the phpQ Jr. admin every time you open your web browser, as the login is not stored once you close your browser.
- Display Polls:
This option allows you to select how you want polls displayed on the main page of phpQ Jr.'s administration panel. You can choose from the following options:
- All Polls - Selecting this option will show all polls that have been created on the main page. If you created lots of polls, often placing them in groups, this can cause the main page to be rather cluttered with polls.
- Not in Groups - Choosing this option will only display those polls on your administration overview that are not part of a group. You can always access the polls within a group by going to the poll editor and selecting it from the list.
- None - This will cause the main page of your admin to not show any of the individual polls.
- Display Groups:
This option in the phpQ Jr. configuration panel allows you to select how you want groups displayed on the main page of phpQ Jr.'s administration panel. You can choose from the following options:
- All Groups - Selecting this option will show all poll groups that have been created on the main page. This is the default option and especially useful if you selected "Not in Groups" when setting the Display Polls option.
- None - This will cause the main page of your admin to not show any of the poll groups.
7.2) Change Administrator Password
If you wish to change the phpQ Jr. admin password, you will need to enter the following three fields and click the Change Password button:
You do not need to fill in any of these three fields to Modify Options within the phpQ Jr. Configuration.
- Current Password
This is the current phpQ Jr. 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 the phpQ Jr. 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.
7.3) Backup Database
phpQuestionnaire Junior allows you to backup and restore your phpQ Jr. 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 Jr. allows you to backup the entire database or a single poll and all results to one file. When clicking on the "Download Data" button, you will be prompted to save a file with a .qjr extension to your machine.
When backing up a single poll, your phpQ Jr. configuration information will be omitted. A backup of the entire database, however, will store all of your phpQ Jr. configuration in the downloadable file allowing you to Restore your installation exactly as it appears at that moment.
You can also use the poll backup feature to share a poll and all associated results with a friend who also uses phpQ Jr. However, if you would prefer to share the poll and questions without the results, you should look into the Export and Import features on the Poll Editor page.
7.4) Restore Database
phpQ Junior allows you to backup and restore your 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. There are several options in restoring a database and they are described in detail below:
- Restore Data File:
This field is for restoring your database from a data file located on your hard drive. Simply click the "Browse..." button in the "Restore Data File" row and find your phpQ Jr. backup ('backup_YYYY-MM-DD.qjr' 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.
If your file exceeds the maximum file upload size (normally 2 MB) you may want to look into restoring from a URL.
- Restore From URL:
This field allows you to restore your database from a data file located at a URL. Simply enter the URL (starting with http://) to your phpQ Jr. backup file (normally 'backup_YYYY-MM-DD.qjr' if you have downloaded all data) in the "Restore From URL" row. Then select your Restore Behavior and click the "Retrieve Database" button to have the specified backup restored into the database.
If your file is stored on your hard drive, you may want to look into restoring from a data file.
- Restore Behavior:
The Restore Behavior applies to both Restore Data File and Restore From URL. There are two options:
- Restore Data: SAVING ALL Current phpQ Jr. Data
This is the default option and ensures that you will lose no data that is currently in your phpQ Jr. database. When using this option, no data will be imported to the phpQJr_ADMIN table (which covers all phpQ Jr. Configuration variables and your password). Only individual polls, questions, and results will be restored. Furthermore, if any clashing poll 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 polls.
- Restore Data: ERASING ALL Current phpQ Jr. Data
WARNING! This action cannot be undone. ALL DATA currently in phpQ Jr. 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 Jr. tables in your database, erasing all data and then insert all of your backup data. This function has the advantage of maintaining all poll, 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.
7.5) Block IP Address
phpQ Jr. allows you to ban any IP address or range of IP addresses. From the configuration screen you can add and remove blocked IP addresses, controlling whether or not users from those machines will be able to vote in your polls. This is one effective means of controlling problematic users.
To add a new IP address, type it into the textfield and click the 'Block IP' button. You can also use '*' in the IP address to signify any number. So if you would like to ban any IP address starting with '192.168.1.' you would enter:
and then click the 'Block IP' button. You can obviously type in exact IP addresses as well. Once you have decided you no longer need to block an IP address, you may remove it from the block list by selecting it from the list and clicking 'Unblock IP'.
7.6) Rate this Script
We hope that you are extremely satisfied with the phpQuestionnaire Junior 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 Jr. To do so, simply follow the links that say "Comment on phpQuestionnaire Junior" 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!
In order to allow for as much flexibility as possible, for both novice and advanced users, phpQ Jr. combines CSS and templates to give you total control over the look at feel of your polls. There are two types of templates, those for the poll and those for question types, and you are free to add to or modify any of them. We detail the process for each option below.
8.1.1) Poll Templates
To create your own poll templates for phpQ, you must create new directories and files within the templates directory of your phpQ installation.
All polls can be integrated into an existing page using server side includes or a PHP call. One of our templates, in particular, has been designed to have no frills and is called the "Blank Template". It will simply use the CSS formatting you have defined within your poll and contain nothing else. To perform the server side include call, you would use code such as:
This directory will hold all files related to your template and should be located in the phpQ/templates/ directory.
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 phpQJr/ directory.
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 poll 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 poll. This line will not be displayed once the poll is rendered to the user's screen:
<!--// TEMPLATE: phpQ Jr. Default Template //-->
phpQ Jr. will replace this text with the Poll Name you have defined in the Poll Editor for each specific poll. In the default template, this is placed in the <TITLE> tags.
phpQ Jr. will replace this text with the poll questions and answers. It will also be used to display the completion notice for any given poll. This may be empty in the case of a single poll that is displaying statistics instead of content. This tag is required in order to have the poll questions and answers appear on the page.
phpQ Jr. will replace this text with the poll statistics when called for. This may be empty in the case of a single poll that is displaying the questions or if public results are turned off. This tag is required in order to have results appear on the page.
If there is an error in the user submission or poll operation, it will appear where this text is located.
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:
Again, you need to replace the actual survey id as well as the correct URL and path to your phpQ directory.
8.1.2) Question Templates
In most cases, the default question templates for radio button, check boxes and select boxes will be the one you will want to use. For radio buttons and check boxes they can handle multiple columns and will work just as you would expect in most cases, while allowing you complete CSS control. However, phpQ Jr. includes the ability for you to create question templates, which gives you control over where error messages, questions and their answers will appear. Like the poll templates discussed above, the directory structure for these question templates looks like:
Each HTML file named like this in your qtype templates folder will be a question template. The file must start with 'qmod_' and end with a unique name and the .html ending. Within each of these files, you can place the HTML you wish to have used as the template for each question. The following markers can also be used:
This displays any error message that may appear for the specific poll question, for instance if it was required and they failed to fill it out, etc.
This will display the Question as defined in the Question Editor.
If included in your template, this will display all of your choices. For select templates, this is the only option. For radio and checkbox templates, using this option will allow you to use the Number of Columns feature within the Question Editor. However, for radio and checkbox templates, you may also number your choices, described below.
If you are designing a radio or checkbox template, you can leave out the ::CHOICES:: marker and instead define an exact number of choices. For instance, in our distribution, we include a sample template that shows an 11-choice S-Curve template for checkboxes and radio buttons. It is done by including the tags: ::CHOICE1::, ::CHOICE2::, and so on. These are more restrictive in that they will only work properly with the correct number of answer choices. It is therefore more common to define a question template using the ::CHOICES:: field which will display all choices in a line, regardless of number.
8.2) Manual Installation
In almost all cases, the Automatic Installation should setup phpQuestionnaire Junior 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:
Within each of the directories above, you will find many other files and directories. As long as you move the phpQJr base directory around as a unit, it will work as expected.
Creating MySQL Tables for phpQ Jr.
Now that you have placed this phpQJr/ 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 phpQJr_ADMIN (
password VARCHAR(20) NOT NULL,
poll_list TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
group_list TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
template VARCHAR(255) NOT NULL DEFAULT \"default\",
timeout BIGINT(20) UNSIGNED NOT NULL DEFAULT 60,
cookie_domain VARCHAR(255) NOT NULL
CREATE TABLE phpQJr_SESSION (
session_id VARCHAR(255) NOT NULL,
recent_time BIGINT(20) UNSIGNED NOT NULL DEFAULT 0
CREATE TABLE phpQJr_BLOCK (
ip_id INT(10) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
ip_address VARCHAR(255) NOT NULL
CREATE TABLE phpQJr_GROUP (
group_id INT(10) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
group_name VARCHAR(255) NOT NULL,
group_info VARCHAR(255) NOT NULL,
create_date DATETIME NOT NULL,
active TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
show_menu TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
randomize TINYINT(1) UNSIGNED NOT NULL DEFAULT 0
CREATE TABLE phpQJr_GROUP_POLL (
group_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
poll_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
sort_order SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
PRIMARY KEY(group_id, poll_id)
CREATE TABLE phpQJr_POLL (
poll_id INT(10) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
poll_name VARCHAR(255) NOT NULL,
poll_info VARCHAR(255) NOT NULL,
create_date DATETIME NOT NULL,
active TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
template VARCHAR(255) NOT NULL,
tally INT(10) UNSIGNED NOT NULL DEFAULT 0,
start_time TIME NOT NULL DEFAULT '00:00:00',
end_time TIME NOT NULL DEFAULT '23:59:59',
ip_check TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
cookie_check TINYINT(1) UNSIGNED NOT NULL DEFAULT 0,
cookie_time INT(10) UNSIGNED NOT NULL DEFAULT 365,
public_results TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
public_textfield TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
popup_width MEDIUMINT(1) UNSIGNED NOT NULL DEFAULT 600,
popup_height MEDIUMINT(1) UNSIGNED NOT NULL DEFAULT 400,
popup_limit MEDIUMINT(1) UNSIGNED NOT NULL DEFAULT 10,
show_menu TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
submit_image VARCHAR(255) NOT NULL,
submit_width SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
submit_height SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
submit_alt VARCHAR(255) NOT NULL,
result_image VARCHAR(255) NOT NULL,
result_width SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
result_height SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
result_alt VARCHAR(255) NOT NULL,
result_display TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
completion_notice TEXT NOT NULL,
redirect_url VARCHAR(255) NOT NULL
CREATE TABLE phpQJr_QUESTION (
poll_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
question_id INT(10) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
question_type VARCHAR(50) NOT NULL DEFAULT 'radio',
question_asked VARCHAR(255) NOT NULL,
sort_order SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0
question_style VARCHAR(255) NOT NULL,
answer_style VARCHAR(255) NOT NULL,
textfield_style VARCHAR(255) NOT NULL,
column_size MEDIUMINT(4) UNSIGNED NOT NULL DEFAULT 0,
template VARCHAR(255) NOT NULL
CREATE TABLE phpQJr_ANSWER (
question_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
answer_id INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
value VARCHAR(255) NOT NULL,
sort_order SMALLINT(5) UNSIGNED NOT NULL DEFAULT 0,
default_choice TINYINT(2) UNSIGNED NOT NULL DEFAULT 0,
other_selectable TINYINT(2) UNSIGNED NOT NULL DEFAULT 0,
bar_color VARCHAR(50) NOT NULL,
tally INT(10) UNSIGNED NOT NULL,
UNIQUE qs_index (question_id, sort_order)
CREATE TABLE phpQJr_ANSWERTEXT (
user_id INT(10) UNSIGNED NOT NULL DEFAULT 0 PRIMARY KEY AUTO_INCREMENT,
poll_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
question_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
answer_id INT(10) UNSIGNED NOT NULL DEFAULT 0,
ip_address VARCHAR(255) NOT NULL,
other_date DATETIME NOT NULL,
other_text VARCHAR(255) NOT NULL,
You must also create the default administrator account for this installation by inserting the following row:
INSERT INTO phpQJr_ADMIN (password,poll_list,group_list,template,timeout,cookie_domain) VALUES ('password','1','1','default','3600','');
Configuring phpQ and MySQL
After setting up the tables used by phpQuestionnaire Junior, you will need to edit the file 'phpQJr/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 = "phpQJr";
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 'phpQJr/install.php'. This is a very important step, as leaving this file in place could allow a hacker to re-install the phpQ Jr. files.
Your phpQuestionnaire program should now be successfully installed. Proceed to Logging in as Administrator to begin using phpQ.
8.3) Getting Support
When you purchased phpQuestionnaire Junior, 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 email@example.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.