BF Survey Pro User Guide

Transcription

1 BF Survey Pro User Guide January 2011 v1.0 1 of 41

2 Table of Contents Introduction... 5 Support... 5 Documentation... 5 Installation New Install... 5 Installation Upgrade... 6 Setting up categories... 6 Setting up questions... 8 Category... 8 Question... 8 Suppress Question... 8 Help Text... 9 DB Field Name DB Field Type Max answer length Type Published Mandatory Validation Type Parent item SQL Command SQL Field Options Next Question ID Answer Prefix Answer Suffix _OTHER_ Prefix _OTHER_ Suffix Creating menu item Default multi page survey My Surveys All questions on one page SAYG (Save as you go) Stats January 2011 v1.0 2 of 41

3 Menu item parameters Parameters Basic Category Parameters Component Send Notification Send Author Enable Anonymous Responses Anonymous Text Yes option text No option text Show Name Input Show Company Input Show Input Name Text Company Text Text Title Introduction text Thank you text Submit Button Text Field validation error Use CAPTCHA Redirect URL Use BF Survey Pro CSS Registered Users Only Prevent Multiple Entries (IP Address) Prevent Multiple Entries ( ) Templates Customising to suit the look of your site Troubleshooting Common issues Problem: Text doesn t show for title, name field, send button etc which are all blank Problem: Unknown column error at the end of your survey January 2011 v1.0 3 of 41

4 Problem: Row size too large. The maximum row size for the used table type, not counting BLOBs, is You have to change some columns to TEXT or BLOBs Problem: Thank you text is not appearing Problem: Notification s are not being sent January 2011 v1.0 4 of 41

5 Introduction BF Survey Pro is a Joomla 1.5 extension that allows you to easily add surveys to your website. Support If you have a problem with BF Survey Pro, please post on our support forum We also encourage you to post comments about what you like and dislike about our products to enable us to improve our products for future versions. Documentation The latest documentation can be found at Installation New Install BF Survey Pro is installed the same way that most extensions are, via the back end. Extensions->Install/Uninstall Browse for the install package then click Upload File & Install You should see Install Component Success message. January 2011 v1.0 5 of 41

6 Installation Upgrade Firstly it is recommended that you do a full site backup before upgrading any extension. I recommend Akeeba backup To upgrade from previous versions of BF Survey Pro, you can install over the top and the installation will automatically upgrade any database tables and files and you will not loose any data. This is because the install process now uses the upgrade method. Upgrade process is the same as above installation new install, however once installed you may need to open then save any existing menu items to update any new parameters added in the new version. Warning: DO NOT UNINSTALL previous version as you will loose your data. Setting up categories Each survey is a set of questions grouped together in the same category, so the first step to setting up your survey is to create a category Components->BF Survey Pro->Categories January 2011 v1.0 6 of 41

7 New Just fill in the title and click save. The other standard Joomla category fields are not used by BF Survey Pro. You should see your category there now. The example one is part of the default install of BF Survey Pro which includes an example survey, and this can be deleted if you don t need it. January 2011 v1.0 7 of 41

8 Setting up questions To add questions to your survey, go to Components->BF Survey Pro->Questions Press New button to create a new question Select the category for your question (effectively which survey will this appear in) All the fields with asterix next to them are mandatory and must be fill in before you can save the question. The below sections go into detail about each of the fields on the question form. Category This determines which survey the question will appear in. Question The question field is the actual text of the question you are adding. Suppress Question Setting suppress question to yes will hide the question text and just show the options, which can be useful if you want to add more fields to the beginning of your survey, or also if you want to join several questions together and make them appear as one. If you want to add additional fields at the beginning of your survey, just create a normal text question for the first question of the survey, then set Suppress Question to Yes. Answer prefix is used for the text before the field. Max answer length of 55 will make the field the same size as existing ones. January 2011 v1.0 8 of 41

9 Help Text The help text field is optional and allows you to display text between the question and the options. You can insert any HTML you like here including images, and as this is displayed using the on content prepare, you can also insert any plugin you would normally add in an article, for example you can use all videos to display video or audio. January 2011 v1.0 9 of 41

10 DB Field Name The DB Field Name field is the actual field that will be created in the MySQL table to store the answers to this question. As this is a MySQL field, you cannot use spaces or special characters such as backslash (\), asterix (*) etc. You can use any alphanumeric characters and underscores. To avoid problems with exporting to excel, it is best to start and finish your field with an alphabetic character. DB Field Type The DB Field Type is the type of field that will be created in the MySQL table. If in doubt, just leave this with the default Text, which can store just about anything. If you want to ensure your database is as efficient as possible, you should select the appropriate data type. For example, if your options are yes and no, you will only ever store a maximum of 3 characters so varchar(3) is going to be more efficient than Text. Unless your database is really big or under a large load, you probably wont notice any performance benefit. Another example is when you only want a numeric input, you might select INT as the field data type. Max answer length Note: this field is hidden for some question types. The max answer length is used when you want to restrict the number of characters the user can input, for example for text field if you wanted to limit the response to 255 characters. If in doubt, just leave the default 255. Depending on the db field type, the field created in the database can be influenced by this value, for example if you had an int with max answer length of 4, the field created would be int(4), which allows you to make the database table slightly more efficient. For some db field types such this has no influence, for example date fields will ignore this value. Type Type is the actual question type you would like. If you want the user to only select one option, then radio question type is usually the best. If you want a short free text entry, choose text question type. Checkbox is used when you want the user to select one or more options. Textarea is for multiple lines of text input. Date is a date selection. DropDown is a drop down list where you can select only one option. Summation is where you want to distribute points against two or more options. Rating is multiple columns of radio buttons for each option. January 2011 v of 41

11 Published Only publish questions will appear on the front end, so normally you would set this to yes. Mandatory Mandatory is where you want to force the user to enter something or select something. Any question that is not mandatory could potentially be left blank by the user. Please note: the mootools form validation built into Joomla core does not validate checkbox or radio question types, so you need to install our free extension BF Validate which extends the validation types available for your site. Validation Type The validation type determines how the form validation will work for this question. If mandatory is set to no, then this setting is ignored so it doesn t matter what is set. When mandatory is set to yes, the validation type can be set, and the options available will be different depending on the question type. For example, text fields have required validate-numeric, whereas checkbox will have required validate-checkbox. For text fields, the default of required will just ensure that the field is not left blank, whereas required validate- will force the user to enter an address (please note that it does not check that the address is valid, it just checks the format, so potentially someone could still enter a fake address such as test@example.com). For checkbox question type, you can choose the exact number of options you want selected, for example if you want the user to select exactly three options, you could set required validatecheckbox3 (thiis requires BF Validate plugin is installed and published). January 2011 v of 41

12 For some question types there is only one validation type available, so it will just say default. Parent item The parent item can be used to control how many questions are on each page. For example, you may want three questions on the first page, five on the second, and four on the next. This can be achieved using the parent child grouping which is the parent item field on the question. The parent item allows you to group multiple questions together for the multipage views. Any question that is set to top will appear first on a page, and any other questions with that question as the parent will also appear on the same page. For example, both these questions will appear on the same page, as the second one has the parent item set to the first question. January 2011 v of 41

13 Notice how the child items are indented slightly in a similar way to Joomla sub menu items. You can only have one level of parent and child, you can t have child items of child items. Also the parent and the child item must be in the same category. Each parent item can have as many child questions as you like. The parent child grouping has no impact on the all questions on one page view, it only works for the default multipage view and the save as you go view which is also multiple pages. It should be noted that when you are using conditional branching (next question id), the last question on the page will determine the next question. Any conditional branching in other questions on the same page will be ignored. If your next question id refers to a child item, as the parent is skipped, the child will appear on the page by itself. All subsequent child items in that group will appear one question per page, until the next parent question is displayed, which will have its child questions on the page too. When you add a child question from a different category, it inherits the category from the parent. If you change the category of the parent question, all child questions will also have their category changed. There are only two levels, parent and children. You cannot have children of children. A parent question with children cannot be changed to be a child of a different parent question. You must first remove all the children questions. January 2011 v of 41

14 In regards to ordering, the first child question will have order of 1, the second child question will have order of 2 etc. This is independent of the ordering of parent items. SQL Command Note: this field is hidden for some question types Instead of using the option fields to specify up to 20 options for your question, you can use the SQL command to look up the options from your own custom table. SQL Field Note: this field is hidden for some question types Used in conjunction with the SQL command field, this specifies which column in your MySQL table the options are stored in. Options The options are the choices available for the question. For radio and checkbox question types, you can use _OTHER_ as the option which will create a text input field. January 2011 v of 41

15 Next Question ID This allows you to add conditional branching to your survey where you can essentially skip questions based on the answer chosen. The question id is shown in the first column on the questions view. Note: you should only jump forwards in your survey, don t jump back and forth. A next question ID of -1 will terminate the survey if that option is chosen, and the user will be shown the thank you text at the end. Answer Prefix This is text that is shown before every option or input field. Answer Suffix This is text that is show after every option. January 2011 v of 41

16 _OTHER_ Prefix When _OTHER_ is used to display a text field within a radio or checkbox question, the _OTHER_ prefix allows you to add text before the text field. _OTHER_ Suffix When _OTHER_ is used to display a text field within a radio or checkbox question, the _OTHER_ prefix allows you to add text after the text field. January 2011 v of 41

17 Ordering From the question view, you can change the order of the questions using the order column. You can use the up and down arrows to move individual questions, or you can type in the order numbers in the fields then click the save button in the header. Creating menu item Once you have added your questions, you can add a survey menu item to add the survey to your site. From the menu manager, select the menu you want your survey to appear in. Click the new button There are several menu types available for BF Survey Pro. January 2011 v of 41

18 Default multi page survey This survey type offers the most flexibility, as you can have a different number of questions on each page of the survey, which is achieved by grouping questions using the parent item. The default multi page survey temporarily stores the responses in session variables, and waits till the very end (when the thank you message is displayed) to save the responses into the database. By default the session lifetime set in your global configuration is 15 minutes, so be aware that if you have a long survey which takes more than 15 mins to complete then you may need to increase the session lifetime on your site or perhaps use the save as you go (SAYG) view instead. It is possible to increase the session lifetime for BF Survey Pro only instead of changing the global setting, however it requires a minor code change, if you are interested in this please refer to our support forum. My Surveys The My Surveys view allows registered users to view and edit their survey responses. This view also has a setting in parameters basic on the right hand side of your menu item where you can set read only to Yes or No. If set to Yes, the users will only be able to view their survey responses, they will not be able to edit or change them in any way. January 2011 v of 41

19 All questions on one page This view allows you to show all the questions on the same page, and it is used for single page surveys. There are some limitations when using the one page view, for example there is no CAPTCHA support as the current version of Bigo CAPTCHA requires form submission to check the input, and there is no conditional branching. SAYG (Save as you go) This is similar to the default multipage view, however instead of waiting till the end of the survey to write the responses to the database, it saves them after each page (whenever you click the next button). This can be useful for long surveys where users don t finish it, so that you can at least capture partially completed surveys. Stats The stats view graphically shows the responses to your survey. Menu item parameters When you add a menu item for BF Survey Pro, there are a number of settings you can change to customise your survey. Parameters Basic Category On the right hand side in the parameters basic section, you need to select the survey category so that your site knows which survey this menu item is for. Note that this does not apply to the My Surveys view which shows responses to all surveys regardless of the category. Parameters Component This is located on the right hand side of your survey menu item, and can be expanded by clicking on it. January 2011 v of 41

20 January 2011 v of 41

21 Send Notification On completion of your survey, an administrator can be sent a notification which you can customise in the template section in BF Survey Pro. To enable the you must set send notification to Yes. No or Use Global will prevent your survey from sending the . January 2011 v of 41

22 This is the address that the Admin will be sent to. Send Author On completion of the survey, the user who completed the survey (the author) can be sent the author notification which you can customise in the template section. To enable the you must set send notification to Yes. No or Use Global will prevent your survey from sending the author . Enable Anonymous Responses If set to No the I prefer to respond anonymously: question is hidden, so you can force the user to enter their name and instead of responding anonymously. A setting of Yes or Use Global will cause it to appear. January 2011 v of 41

23 Anonymous Text This allows you to change the wording for the anonymous question. Here is an example of changing the wording Yes option text This allows you to change the wording of the Yes option in the anonymous question For example No option text Same as above but for the No option January 2011 v of 41

24 For example Show Name Input This is used to hide the name input field at the start of the survey if you don t want it. A setting of No will cause the field to be hidden. A setting of Yes or Use Global will cause it to appear. Please note that if the name field is hidden, the anonymous question is also hidden. Also note that you can hide one or all the name, company and fields as they are all set individually, so for example if you only wanted the field, you could hide both name and company. Show Company Input This is used to hide the company input field at the beginning of the survey. A setting of No will cause the field to be hidden. A setting of Yes or Use Global will cause it to appear. Show Input This is used to hide the input field at the beginning of the survey. A setting of No will cause the field to be hidden. A setting of Yes or Use Global will cause it to appear. January 2011 v of 41

25 Name Text The name text field can be used to change the text next to the name input field. For example: Company Text The company text field can be used to change the text that is displayed next to the company input field. Please note that this field could potentially be used to capture any text information, it does not need to be the persons company name. January 2011 v of 41

26 Text This allows you to change the text label next to the input field. Title This allows you to change the title at the top of your survey. For example Introduction text This is the text that is shown just after the survey title, and can be changed to whatever you like. For example January 2011 v of 41

27 You can insert HTML code in the introduction text Or even images using HTML code January 2011 v of 41

28 Thank you text This is the text that is displayed in the message queue at the completion of the survey. As this is displayed using the message queue, this can only be plain text and cannot include any HTML. Common problem: thank you text does not appear If the thank you text does not appear (you just get a blank page), then this is usually caused by your site template missing the message queue, which can be fixed by adding the following line of code just above the main content area in the index.php of your site template <jdoc:include type="message" /> /templates/rhuk_milkyway/index.php (where rhuk_milkway is your template name). Submit Button Text This is the text label of the submit button at the bottom of your survey. January 2011 v of 41

29 Field validation error This is the text that appears in the javascript alert box that pops up when the validation fails. You can type this text in any language. Use CAPTCHA For sites that have problems with spam, you can turn on a CAPTCHA which makes it more difficult for automated scripts to complete the survey. This requires you install and publish Bigo CAPTCHA plugin which is free. As Bigo CAPTCHA requires form submission to test the value, this does not work for the onepage view, however you can use CAPTCHA for the default mutli page view and the Save As You Go (SAYG) view. Bigo CAPTCHA plugin must be installed and enabled. CAPTCHA will appear after the name/company/ fields at the beginning of the survey. January 2011 v of 41

30 Text underneath CAPTCHA can be changed via your language file COM_BFSURVEYPRO_INPUT_WORD_FROM_IMAGE=(Input Word from the image) Redirect URL Instead of just showing the thank you text at the end of the survey, you can use the redirect URL to take you to a specific page on your site. You can even use an external URL, in which case the thank you text will not display as your browser will take you to another completely different website. Use BF Survey Pro CSS If you don t want the CSS file /components/com_bfsurvey_pro/css/style.css loading, set this to No, otherwise just leave it at Use Global or Yes January 2011 v of 41

31 You d only use this setting if you are planning on manually defining your CSS styles elsewhere such as in your site template. Registered Users Only Changing this parameter to Yes will cause your survey to only be available to those that have an account on your Joomla site. Anyone that is not currently logged in that click on the survey menu link will get a message You must log in. The exact text can be adjusted in your language file. January 2011 v of 41

32 COM_BFSURVEYPRO_ERROR_YOU_MUST_LOG_IN=You must log in before you can use this system. Prevent Multiple Entries (IP Address) This setting only works when registered users is also set to Yes. When a user takes the survey, it will check the answer table to see if their IP address already exists, in which case they have already taken the survey so it will prevent them from taking it again. The text can be changed in your language file. COM_BFSURVEYPRO_ERROR_IP_ALREADY_COMPLETED=Your IP address has already completed this survey. Prevent Multiple Entries ( ) This only works when Registered Users Only is also set to Yes. Normally when a logged in user takes the survey, their name and is automatically populated, at which point this setting forces the survey to see if that particular user s address is already in the answer table. If their address already exists, then they have already taken the survey so they will see an error message. January 2011 v of 41

33 You can adjust this text via your language file COM_BFSURVEYPRO_ERROR_ _ALREADY_COMPLETED=Error: Your address has already completed this survey. January 2011 v of 41

34 Templates templates allow you to personalise the admin and author s without having to change any source code. You need to setup s for every category (survey). You can access the templates via components->bf Survey Pro-> Template You will need a different template for each survey, but you can copy an existing template. You can assign a template to your survey by selecting the survey category. January 2011 v of 41

35 There are two types of templates, admin and author. Admin s are ones sent to the address in your menu item parameters. Author s are those sent to the person filling out the survey, and are sent to the address captured in the field. You can insert dynamic data into your s, using the fields show in the help. For example, if you want to insert the name entered in the name field of the survey into your , you just need to put the text {name} Category = The survey that this is assigned to type = Is this an admin or an author ? Subject = The subject of the . Note this field can contain tags that are replaced with actual data, for example {name} Published = Is this active? Body = The contents of the . Note this field can contain tags that are replaced with actual data, for example {score} or { } Show questions and responses = Do you want to show the questions as well as the answer chosen in the ? Customising to suit the look of your site In components->bf Survey Pro, there is a button Edit CSS that allows you to change the look of the survey. components->bf Survey Pro Select style.css and click the edit button on the right January 2011 v of 41

36 There are a number of css styles you can change to customise your surveys. Changes here will effect all surveys on your site. As an example, lets change the background colour of the question. Now if we look at the survey, you will see that the background colour of the question has changed. January 2011 v of 41

37 As you can see, you can change the look and feel to suit the colour scheme of your site. January 2011 v of 41

38 Troubleshooting Common issues Our support forum is a useful resource if you have having any problems with the software. Here are a few common issues and their solutions: Problem: Text doesn t show for title, name field, send button etc which are all blank. Solution: This indicates that the menu item parameters are not loading correctly, and often occurs when you are accessing the survey via a url link. The solution is to append &Itemid=xx (where xx is your menu item id) to the url so that the software knows where to load the menu item parameters from. Please note the capital I in Itemid and that it is case sensitive. Eg. When you access via this url, you don t see survey title etc index.php?option=com_bfsurvey_pro&view=bfsurveypro&catid=34 When you add the Itemid it shows correctly index.php?option=com_bfsurvey_pro&view=bfsurveypro&catid=34&itemid=53 January 2011 v of 41

39 January 2011 v of 41

40 Problem: Unknown column error at the end of your survey. Solution: This indicates that your answer table has not been fully built yet. To fix, go to the question view components->bf Survey Pro->Questions Set display at bottom to ALL, then refresh your browser a couple of times. Look at the bottom of the page for SQL errors. If there are no errors, try your survey again and it should work. Problem: Row size too large. The maximum row size for the used table type, not counting BLOBs, is You have to change some columns to TEXT or BLOBs Solution: The error indicates that there is not enough space in the mysql table to add the field. You can potentially change all your varchar(255) fields to TEXT, you don't have to limit this to only text and textarea question types. There is nothing a varchar(255) field type can do that a TEXT cannot. January 2011 v of 41

41 Problem: Thank you text is not appearing Solution: If the thank you text does not appear (you just get a blank page), then this is usually caused by your site template missing the message queue, which can be fixed by adding the following line of code just above the main content area in the index.php of your site template <jdoc:include type="message" /> /templates/rhuk_milkyway/index.php (where rhuk_milkway is your template name). Problem: Notification s are not being sent Solution: BF Survey Pro uses the standard Joomla mail functions, so the first thing to check is your mail settings in your global configuration. You can test that these are working by doing the following: tools->read messages settings mail me on new message=yes tools->write message send a message to your joomla account. If works from messages, then it should work for BF Survey Pro, as it's essentially just using the JUtility::sendMail function from the Joomla core. January 2011 v of 41