BF Survey Pro User Guide Survey Pro User... · 2019. 3. 17. · To upgrade from previous versions of BF Survey Pro, you can install over the top and the installation will automatically

BF Survey Pro User Guide

January 2011 v1.0 1 of 41 www.tamlyncreative.com.au/software/




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 ................................................................................................................................... 10

DB Field Type .................................................................................................................................... 10

Max answer length............................................................................................................................ 10

Type ................................................................................................................................................... 10

Published ........................................................................................................................................... 11

Mandatory ........................................................................................................................................ 11

Validation Type ................................................................................................................................. 11

Parent item ....................................................................................................................................... 12

SQL Command ................................................................................................................................... 14

SQL Field ............................................................................................................................................ 14

Options .............................................................................................................................................. 14

Next Question ID ............................................................................................................................... 15

Answer Prefix .................................................................................................................................... 15

Answer Suffix .................................................................................................................................... 15

_OTHER_ Prefix ................................................................................................................................. 16

_OTHER_ Suffix ................................................................................................................................. 16

Creating menu item .............................................................................................................................. 17

Default – multi page survey .............................................................................................................. 18

My Surveys ........................................................................................................................................ 18

All questions on one page ................................................................................................................. 19

SAYG (Save as you go) ....................................................................................................................... 19

Stats .................................................................................................................................................. 19



Menu item parameters ......................................................................................................................... 19

Parameters Basic ............................................................................................................................... 19

Category ........................................................................................................................................ 19

Parameters Component .................................................................................................................... 19

Send Email Notification ................................................................................................................. 21

Email .............................................................................................................................................. 22

Send Author Email ........................................................................................................................ 22

Enable Anonymous Responses ..................................................................................................... 22

Anonymous Text ........................................................................................................................... 23

Yes option text .............................................................................................................................. 23

No option text ............................................................................................................................... 23

Show Name Input.......................................................................................................................... 24

Show Company Input .................................................................................................................... 24

Show Email Input .......................................................................................................................... 24

Name Text ..................................................................................................................................... 25

Company Text ............................................................................................................................... 25

Email Text ...................................................................................................................................... 26

Title ............................................................................................................................................... 26

Introduction text ........................................................................................................................... 26

Thank you text .............................................................................................................................. 28

Submit Button Text ....................................................................................................................... 28

Field validation error ..................................................................................................................... 29

Use CAPTCHA ................................................................................................................................ 29

Redirect URL .................................................................................................................................. 30

Use BF Survey Pro CSS................................................................................................................... 30

Registered Users Only ................................................................................................................... 31

Prevent Multiple Entries (IP Address) ........................................................................................... 32

Prevent Multiple Entries (Email) ................................................................................................... 32

Email Templates .................................................................................................................................... 34

Customising to suit the look of your site .............................................................................................. 35

Troubleshooting Common issues .......................................................................................................... 38

Problem: Text doesn’t show for title, name field, send button etc which are all blank. ................. 38

Problem: “Unknown column” error at the end of your survey. ...................................................... 40



Problem: Row size too large. The maximum row size for the used table type, not counting BLOBs,

is 65535. You have to change some columns to TEXT or BLOBs ...................................................... 40

Problem: Thank you text is not appearing ........................................................................................ 41

Problem: Notification emails are not being sent .............................................................................. 41



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

http://www.tamlyncreative.com.au/software/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

http://www.tamlyncreative.com.au/software/documentation.html

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.




Installation – Upgrade Firstly it is recommended that you do a full site backup before upgrading any extension. I

recommend Akeeba backup http://www.akeebabackup.com/

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



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.



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.



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.



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.



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-email will force the user to enter an email address (please note that it does not

check that the email address is valid, it just checks the format, so potentially someone could still

enter a fake email address such as [email protected]).

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 validate-

checkbox3 (thiis requires BF Validate plugin is installed and published).

mailto:[email protected]



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.



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.



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.



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.



_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.



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.



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.



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.





Send Email Notification

On completion of your survey, an administrator can be sent a notification email which you can

customise in the email template section in BF Survey Pro. To enable the email you must set send

email notification to “Yes”.

“No” or “Use Global” will prevent your survey from sending the email.



Email

This is the email address that the “Admin” email will be sent to.

Send Author Email

On completion of the survey, the user who completed the survey (the author) can be sent the

“author” notification email which you can customise in the email template section. To enable the

email you must set send email notification to “Yes”.

“No” or “Use Global” will prevent your survey from sending the author email.

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 email instead of responding anonymously.

A setting of “Yes” or “Use Global” will cause it to appear.



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



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 email fields as they are all set

individually, so for example if you only wanted the email 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 Email Input

This is used to hide the email 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.



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.



Email Text

This allows you to change the text label next to the email 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



You can insert HTML code in the introduction text

Or even images using HTML code



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.



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/email fields at the beginning of the survey.



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”



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.



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 (Email)

This only works when “Registered Users Only” is also set to “Yes”. Normally when a logged in user

takes the survey, their name and email is automatically populated, at which point this setting forces

the survey to see if that particular user’s email address is already in the answer table. If their email

address already exists, then they have already taken the survey so they will see an error message.



You can adjust this text via your language file

COM_BFSURVEYPRO_ERROR_EMAIL_ALREADY_COMPLETED=Error: Your email address has already

completed this survey.



Email Templates Email templates allow you to personalise the admin and author emails without having to change any

source code.

You need to setup emails for every category (survey).

You can access the email templates via components->BF Survey Pro->Email Template

You will need a different email template for each survey, but you can copy an existing template. You

can assign a template to your survey by selecting the survey category.



There are two types of email templates, admin and author. Admin emails are ones sent to the email

address in your menu item parameters. Author emails are those sent to the person filling out the

survey, and are sent to the email address captured in the email field.

You can insert dynamic data into your emails, 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 email, you just need to put

the text {name}

Category = The survey that this email is assigned to Email type = Is this an admin email or an author email? Subject = The subject of the email. Note this field can contain tags that are replaced with actual data, for example {name} Published = Is this email active? Email Body = The contents of the email. Note this field can contain tags that are replaced with actual data, for example {score} or {email} Show questions and responses = Do you want to show the questions as well as the answer chosen in the email?

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



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.



As you can see, you can change the look and feel to suit the colour scheme of your site.



Troubleshooting Common issues Our support forum is a useful resource if you have having any problems with the software.

www.tamlyncreative.com.au/software/forum

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






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 65535. 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.



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 emails 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 email 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.

Documents

BF Survey Pro User Guide Survey Pro User... · 2019. 3. 17. · To upgrade from previous versions of BF Survey Pro, you can install over the top and the installation will automatically