X-Cart:Survey

Overview

X-Survey is intended for creation of customer surveys and polls to be conducted among the visitors of an X-Cart-based store in order to obtain customer feedback about the goods provided by the store, the store website usability and design, the quality of service and various other aspects of the store operation.

The key features of X-Survey add-on module include:

• Easy to use online surveys and website polls available either on separate web pages or in X-Cart's menu boxes.
• Wide range of question types (single choice, multiple choice and text fields for open-ended questions).
• Automatic and manual sending of survey invitation e-mails.
• Control over the availability of specific surveys (Surveys can be publicly available, password protected, or available only via a direct link).
• Unlimited questions and answers.
• Detailed survey statistics (Printable version available).
• Multilingual support.

X-Survey add-on module is a very flexible survey software solution for X-Cart which can be used to create a variety of surveys and polls with any number of questions and answer options for each question. It is extremely easy to use, allowing even the most non-technically minded user to create, administer and collect the results of on-line surveys.

The range of question types supported by the module is wide enough to meet the needs of most users who will use it to create surveys: X-Survey makes it possible to create questions that respondents will answer by selecting a single answer option, by selecting multiple options, or by providing their own textual answer.

The store administrator controls access of store visitors to specific surveys and decides whether a survey should be available to all visitors of the store website (both registered and unregistered users), just registered users or only a limited group of persons to whom an invitation has been sent with a direct link to the survey page. The survey invitation message is fully customizable and can be mailed to e-mail addresses entered by hand, imported from a CSV file, selected from the profiles of registered customers or borrowed from an existing list of the store's newsletter subscribers. Yet another exciting option for the store administrator is to setup X-Survey in such a way that the application will automatically send survey invitations to the customers who purchased a specific product or placed an order for a specified amount.

Depending on the module settings, surveys can be displayed in X-Cart's menu boxes or on separate pages within your store. A list of surveys available to the customer can be found in the 'Surveys' section of the Customer zone (accessible via the Surveys link in the Special menu box).

A survey is entered into the database after a customer answers some or all of its questions and submits the survey form. Precautions can be taken against multiple responses by same individuals: in addition to the limitation according to which any survey can be completed only once per user session, it is possible to set an IP blocked time period during which re-submitting of a survey from the same IP will be prohibited.

X-Survey gathers statistics on the survey forms being submitted, so the store administrator can easily access the overall statistics on any specific survey as well as statistics on specific survey questions. A printable version of the statistical data of any survey can be easily obtained. It is also possible to view individual survey forms submitted by survey respondents.

Installing X-Survey

For successful installation and work of the module you need an already installed X-Cart 4.3.0.

The process of installing the module X-Survey is the same for X-Cart Gold and X-Cart Pro.

To install the module, take the following steps:

1. Download the module distributive from the File area. The package you need is contained in the archive file x-survey-x.y.z.tgz, where x, y, z are your X-Cart version numbers.
2. Decompress the distribution package archive to a local directory on your system using your favorite compression program (any archiver with support for TAR files).
3. Upload the resulting files to the server directory where your X-Cart is installed.

Note: Please make sure you keep the directory structure during unpacking and uploading, otherwise some necessary files can be overwritten!

1. Point your browser at the location of your store with the addition of /install-xsurvey.php to launch the Installation Wizard.

For example, if your domain name is www.example.com and your X-Cart-based store is installed in the directory /xcart off your web root, you should enter http://www.example.com/xcart/install-xsurvey.php into your browser address line.

5. Follow the Wizard's instructions to install the add-on module at your site:

1. Step 1: License agreement.

This step provides a Software License Agreement for you to accept and requires you to enter your Auth code.

Please read the Software License Agreement. If you agree to all of the terms of this agreement, select the 'I accept the License Agreement' check box.

Note: By selecting the 'I accept the License Agreement' check box, you are consenting to be bound by this agreement. If you do not agree to the terms of the agreement, do not install the software.

Use the field 'Auth code' to enter your Auth code. Auth code is a special authentication code that protects your X-Cart installation. Such a code was issued to you when you first installed your X-Cart-based store. If you do not remember your Auth code, you can look it up in X-Cart's file include/install.php or in the 'Summary' section of your store's Admin zone ("Your AUTH code for re-installing skins and installing modules is: XXXXXXXX").

Click the Next button.

b) Step 2: Installing and configuring the module.

The installation script will create a directory skin1/modules/Survey and copy the module files to that directory. It will also make changes to the database by creating the necessary database tables.

Click Next to proceed.

c) Step 3: Installation complete.

This is the final step of X-Survey installation. It notifies you that the module has been successfully installed and provides a link to the administration back-end of the store where you can enable and configure the module.

Uninstalling X-Survey

To uninstall X-Survey, do the following:

1 Launch the Installation Wizard (Point your browser at the location of your store with the addition of /install-xsurvey.php)

1. At the first step of the Installation Wizard (Step 1: License agreement), select the 'Un-install the module' radio button.

Click the Next button.

3. The Installation Wizard will remove the module files and deactivate the module (Step 2: Uninstalling the module).

Click Next to proceed.

4. Step 3: Uninstallation complete is the final step of the uninstallation process. It notifies you that the module has been successfully uninstalled.

After uninstalling X-Survey, be sure to remove the module distribution package from your web directory.

Enabling and Configuring X-Survey

Enabling X-Survey

After X-Survey add-on module is installed, you need to log into the Admin area of your store and enable it:

1. Go to the 'Modules' section of the store's administration back-end (Administration menu->Modules).
2. In the list of modules and add-ons, find the name 'Survey' and select the check box opposite it.
3. Click the Update button at the bottom of the list.

When the module is enabled, the following elements are added to the user interface of the Admin zone:

• Surveys item in the Management menu;
• Survey options section in General settings->Modules options.

Configuring X-Survey

After activation, the add-on module needs to be configured:

1 Go to the section 'General settings->Modules options/Survey options':

2. Adjust X-Survey options:

• Number of respondents to send a survey invitation to in one pass.

If you are planning to conduct surveys on relatively large groups of users and to inform the prospective respondents of new surveys using survey invitations, you should give some thought to how you are going to mass mail your survey invitations without putting too much load on the server. The problem is that the process of sending email invitations usually takes up a considerable amount of server time and resources. A large number of invitations being sent all at once can result in significant server load reducing performance for all users. A possible way of solving the problem might be to send emails in batches. The option 'Number of respondents to send a survey invitation to in one pass' allows you to adjust the size of batches to be mailed. For example, setting the value of this option to 50 means that whenever the procedure of sending email invitations is launched either from crontab or as a result of creation of a user session, X-Cart's Mail sender will send fifty invitations to the first fifty email addresses from the mailing list and stop. Next time it will send another fifty invitations to the next fifty respondent email addresses. Thus invitations will be sent intermittently in portions of a limited size until the entire queue of email invitations is sent.

• Sending of survey invitations depends on the creation of user sessions.

This option allows you to define whether sending survey invitations should be triggered by the creation of a user session in the database. When anyone enters the store (and accordingly a user session is created), a portion of email invitations gets sent. If the option is not selected, the store admin can use crontab or other scheduling services to organize sending the survey invitations.

• If a user is added to a survey respondents list as a result of a certain event, send the survey invitation to this user immediately.

This option determines the way in which email addresses should be handled if added to the mailing list of a survey as a result of a certain event. If the option is disabled, an address simply gets added to the mailing list; if it is enabled, an address gets added to the mailing list and an invitation is sent to it.

• IP blocked time period (days).

This option allows you to adjust the time period during which a survey respondent is not allowed to complete the survey again from the same IP address. The value of this option should be a whole or fractional number representing the number of days during which re-submitting of a survey from the same IP will be prohibited.

• Display only one survey in the menu boxes column at a time.

This option should be adjusted if you are intending to use more than one surveys simultaneously. If this option is enabled, a single survey is displayed in the menu boxes column at any one time. If it is disabled, the menu boxes column shows all the surveys that can be displayed according to their current availability status.

• Delay after an event before the invitation is sent (hours).

This option allows you to distribute load on the server more evenly by adjusting the minimum delay between an event that causes an email address to be added to the mailing list of a survey and the mailing of the corresponding survey invitation. The value of this option should be a number representing the length of the delay in hours. Adjustment of this option leads to that, when the process of mailing of survey invitations is launched, X-Cart's Mail sender sends invitations only to those email addresses that were added to the mailing list no later than the specified amount of time ago. For example, if, according to crontab, mailings of survey invitations are scheduled for 6:00 pm and 10:00 pm, and you set the option 'Delay after an event before the invitation is sent' to 7 hours, at 6:00 pm invitations will be sent to addresses added before 11:00 am, at 10:00 pm - to addresses added before 3:00 pm. Note that, if the number of addresses added to the mailing list before 11:00 am is greater than the size of the batch determined by the option 'Number of respondents to send a survey invitation to in one pass', at 10:00 pm the Mail sender will first send out the invitations postponed from the 6:00 pm mailing, and then it will continue to mail the invitations meant for the addresses added from 11:00 am to 3:00 pm.

• Email addresses per page.

This option defines the number of email addresses to be displayed on one page.

• Completed survey forms per page.

This option defines the number of completed survey forms to be displayed on one page.

• Click Save button.

After the necessary module options are adjusted, it is time to move on and explore the 'Surveys' section of the administration back-end (Please refer to the chapter #'Surveys' Section Overview).

'Surveys' Section Overview

Surveys can be created and managed using the 'Surveys' section of the administration back-end. You can access it by clicking the link Surveys in the Management menu. The section opens displaying a dialog box titled 'Surveys':

This dialog box is a place from which you will access all the surveys in your store. As long as there are no surveys, the surveys list will be empty. Then, as you create surveys, their names will be added to the surveys list like this:

The surveys list is presented in the form of a table. The table columns provide the following information regarding each of the surveys:

• SURVEY - Survey name. The link allows you to view and edit the survey's details.
• INVITATIONS - Number of survey invitations created and number of invitations sent. The link allows you to edit the survey's mailing list.
• COMPLETED - Number of survey forms submitted by respondents who participated in the survey. The link allows you to access the survey's statistics.
• RECENTLY COMPLETED - Date and time of the most recent completion of the survey. The link allows you to access a list of recently submitted survey forms.
• STATUS - Status of the survey (Public, Registered only, Hidden, Disabled).
• ORDERBY - Position of the survey in the surveys list.

The buttons in the lower part of the dialog box allow you to perform various operations on the surveys list:

• create new surveys,
• delete selected surveys,
• change survey statuses and order of the surveys in the surveys list,
• clone existing surveys,
• send survey invitations.

For information on the above listed operations, see the chapters #Managing Surveys and #Sending Survey Invitations.

Please note that the 'Surveys' section menu (at the top of the page) provides quick links to the sections which may be of interest to you as you set up your surveys:

• Create survey allows you to create a new survey;
• Surveys brings you back to the surveys list;
• General settings/Survey options provides access to the page of X-Survey configuration settings.

Creating a Survey

Creation of a survey includes 3 easy steps:

1. Adding a new empty survey.
2. Defining the structure of the survey.
3. Defining the survey details.

This chapter provides instructions for completing each of the above steps.

Adding a new empty survey

To add a new empty survey:

1. Go to the 'Surveys' section of the administration back-end (Management menu->Surveys).
2. Do one of the following:

* Click the button Add new at the bottom of the 'Surveys' dialog box.

or

* Click the link Create survey in the 'Surveys' section menu.

The result of any of these actions is creation of a new empty survey titled [Unnamed survey # N]. [Unnamed survey # N] is a name automatically assigned to the survey by X-Cart. It is probably a good idea to change this name to something more comprehensible, but do not worry about it for now - you will be able to change it at a later time.

Defining the survey structure

After a new empty survey has been added, you need to fill it with questions. You also need to provide possible answers for each of the questions from which the survey respondents will be able to choose or to provide appropriate space where they will be able to write their own answers. Questions and answers can be provided using the 'Structure' section of the survey editing dialog box. Please note that after a new empty survey gets created, the dialog box for survey editing will be opened exactly at the section where you can add questions and answers. Other times you will have to follow the steps described below:

1. In the surveys list, find the survey for which you wish to add questions/answers and click on its name. This opens the dialog box for editing the survey information.

2. Click the link Structure at the top of the dialog box. This opens the 'Structure' section of the dialog.

3. Click the Add new question... button. This opens the section where you can add questions and answers.

4. From the 'Language' drop-down box, select the language in which you will add survey questions and answers. 5. Add the desired number of questions providing a list of answers for each of them.

To add a question with answers:

1. Into the field 'Question text', enter the question. 2. Use the drop-down box 'How you expect respondents to answer the question' to specify whether the respondents will be supposed to answer the question by selecting a single option, selecting one or more options, or providing their own textual answer. 3. (Optional) Into the field 'Number of columns in which answers should be displayed', enter the desired number of columns. 4. (Optional) Use the field 'OrderBy' to specify the position of the question in the survey questionnaire. 5. (Optional) Use the field 'Mandatory' to select whether this question should be mandatory for respondents or not. 6. If the nature of your question presupposes that respondents will be supposed to choose their answer(s) from a list of options, compose the options to be put on the answer list for the question. In the 'Answer list' section, click on the [+] icon to add as many empty rows as the number of answer options you are going to provide; for each option, type the option description into the ANSWER TEXT field, specify whether or not this option should include a text box by adjusting the TEXT BOX field and, if necessary, specify the position of the option in the answer list using the ORDERBY field.

A text box provides a means to include a blank space as part of an answer option so survey respondents can use it to type in their own answers. For example, if the question is 'What do you think the Main page background color should be?', and you wish to set up the answer list for it like this:

- Green

- Blue

- Red

- Other color (please specify):___________ ,

the options 'Green', 'Blue' and 'Red' should be created by entering Green, Blue and Red as ANSWER TEXT and setting the value of the TEXT BOX field to No, while the option 'Other color (please specify):___________' should be created by entering Other color (please specify): into the field ANSWER TEXT and selecting Yes from the TEXT BOX field:

7. Click the Apply button. 8. If necessary, create translations of the survey content into other languages (Use the 'Language' drop-down box to select a language, then replace the existing field values by values in the selected language and click Apply).

The question gets added to the survey's list of questions (You can view it at any time in the 'Structure' section of the survey editing dialog box).

Defining the survey details

After you have created a survey and composed some questions for it, you might want to provide some essential information as to the survey's availability, design and distribution - the survey details. This can be done using the 'Details' section of the survey editing dialog box (accessible by clicking the link Details at the top of the dialog box).

The 'Details' section includes two major subsections: 'Survey details' and 'Additional options'.

In the 'Survey details' subsection, you need to complete the following fields:

• Survey name - Name of the survey.
• Survey type - Type of the survey characterizing it from the point of view of availability and distribution:
  • Public - Available to all visitors of the store website.
  • Registered only - Available to registered users who are logged in.
  • Hidden - Hidden from general use (No links to the survey are provided on the shop website, the survey is accessible only via a direct URL or can be activated by events).
  • Disabled - Inactive.

It is recommended you first set the survey type to Disabled and keep it that way up until the moment the survey is fully prepared for publishing.

• Survey valid from [Date1] through [Date2] - Period during which the survey needs to be conducted.
• OrderBy - Position of the survey in the surveys list.

In addition to that, you need to define whether the survey results should be made available to the respondent after the survey form is submitted (the checkbox 'Allow respondents to see the survey results') and whether the survey should be displayed in the menu boxes column or just in the surveys list on the special 'Surveys' page (the checkbox 'Display the survey on the front page in the menu boxes column').

In the 'Additional options' subsection, you can adjust the survey's header and footer and create a message that will be displayed to the survey respondent after he or she completes and successfully submits the survey form.

If the survey needs to exist in more than one languages, be sure to provide a survey name, a header, a footer and a survey completed message for it in each of the languages (Use the 'Languages' drop-down box to switch between the languages).

As soon as the survey structure and details are defined, the survey is almost ready for publishing; however, before making the survey available to your clients, it is a good idea to make sure the survey looks and functions correctly. The Preview link at the top of the survey editing dialog box allows you to view your survey as if you were its respondent.

Your further actions depend on how you wish to distribute your survey. If you are going to invite respondents for the survey by email, you now need to configure the survey's mailing list - to provide X-Cart with a list of email addresses to which invitations will be sent or to configure X-Cart to create a mailing list automatically (Instructions for creating a mailing list are available in the chapter #Managing a Survey's Mailing List of this user manual). If, however, you do not wish to send out any survey invitations by email, all you need to do is just activate the survey by assigning to it a proper availability status. The current status of the survey can be easily checked and corrected using a link in the upper right-hand corner of the survey editing dialog box (next to Preview):

• Inactive means that the survey is disabled (which happens to surveys whose survey type is Disabled or whose validity period has expired or has not begun yet);
• Active means that the survey is enabled (which corresponds to the survey types Public, Registered only or Hidden);
• Warnings means that the survey is enabled, but misconfigured (for example, contains questions without answers).

After a survey has been created and configured, you can edit, clone or delete it. Refer to the chapter #Managing Surveys for information on survey operations.