Introduction

Feedback provides easy to use, customisable feedback forms for your website visitors to provide you with their comments, suggestions and bug reports. Feedback comes with a special widget which can easily be inserted on every page of your website to allow your website visitors easy access to your feedback forms.

The widget is written in Javascript, but works without Javascript too. The feedback forms are written in PHP and send you an email upon form completion.

Updates

Version 1.1

Licence Details

Feedback uses the jQuery javascript library and fancybox, both licensed under the MIT license. Icons are from famfamfam. It also uses SyntaxHighlighter, licensed under the Lesser General Public License for the documentation. SyntaxHighligher source code is included, the full LGPL is included in the SyntaxHighlighter folder.

Table of Contents

Demo
Features
Requirements
Quick Start
Overview of included files
FAQ
Summary

Demo

You should be able to see a demo to the right side of the page. Why don't you try:

Moving the widget to the left of the screen
Moving it back to the right of the screen
Speeding up the animation
Slowing down the animation
Back to normal speed
See a demo of FeedBack running in WordPress!

Features

Feedback Widget
Feedback Forms

Requirements

Quick Start

Installing the files

It's best to upload the entire feedback folder into the root folder of your website and use absolute file paths. That way you won't experience any 404 errors if you use the feedback widget in any sub directories. Of course you can delete the /docs directory when uploading.

Editing the necessary files

config.php

Located in the 'includes' folder, config.php holds the mail values for emailing feedback when submitted. There are 2 lines that you will need to change: You should replace the values in quotes with your own email address details. See the other available config values that can be changed.

That's all it should take to setup the PHP side if things, if you navigate to feedback.php on the path you uploaded the feedback folder to, you should get a page asking you to select the most appropriate feedback type. Now - setting up the feedback widget on your pages!

Setting up the widget

Editing jquery.feedback.js

Located in the widget folder, jquery.feedback.js holds the HTML that gets dynamically inserted into your pages. You will need to change the absolute path of the links, look for these lines: and change 'http://www.yourwebsite.com/path/to/feedback/' to the path where you uploaded feedback in the first step. Whilst you're here you could also change the actual text that gets hyperlinked if you don't like the default.

Adding the widget to your pages

Now you can add the widget to your pages. Between your 'head' tags in the HTML header you will need to add a few lines of code (hopefully you have a template file otherwise you might have to edit quite a few of your own files if you want the widget to appear on every page).

Firstly, load jQuery which is the Javascript library the widget uses. I recommend you use the Google CDN servers to load jQuery, so add this line: Then load fancybox, which is included and is freely licensed under the MIT license(changing the path as required): Then include the feedback stylesheet and javascript (changing the path as required): After loading all the above files include the following: This sets up the feedback widget to work off the feedback-container id (see below) and also sets up the fancy box popups that will display the feedback forms.

Finally anywhere between the main body tags of your page(s), but towards the bottom as a general rule, include the following (changing the path/to/feedback): The feedback-container div id doesn't need to be called that name, but whatever you do call it, be sure to enter the same name in line 3 of the of the javascript code above. The feedback widget will insert the HTML you modified earlier in jquery.feedback.js between the feedback-container div tags. This means that website visitors who do not have javascript enable will see the HTML currently displayed on line 2. In this case it still displays the feedback widget (on the right but you could just as easily change it to the left by modifying the class on line 2 to 'feedback-left') and when clicked, goes straight to the feedback main page.

And that's it! As a reference, here is the completed code, which would display the feedback widget in an empty page: Like I've already mentioned, you need to change the paths to the absolute paths of the feedback directory.

Overview of included files

If you're planning on modifying any of the code of the Feedback widget or forms (or even if you're not!) I thought it might be helpful to provide a short description of the functionality of each file so you can get an idea of the project structure and where you should make changes.

File Description
feedback.php Contains the bulk of the PHP code to handle form submissions. Performs server side validation on posted data and then calls the basicMailer methods to send you the submitted data. If posted data fails validation, or there is no posted data, loads the specific feedback type template file based on the 'action' parameter in the URL. If a blank action parameter is supplied, loads 'main.php' template file, if invalid action parameter is supplied, loads incorrectAction.php template file.
feedback.css Contains all the CSS styling code for any of the form related pages.
includes/class.basisCaptcha.php Generates a basic mathematical text only/HTML captcha.
includes/class.basicMailer.php Contains email sending functions and email body generating function for fetching form data and putting it in a format ready for sending via email.
includes/class.util.php Any misc app wide functions. Contains template loading code.
includes/class.validation.php A few basic validation functions in a static class..
includes/config.php Contains a static config class to set any app wide variables (e.g mail settings). Also loads all PHP files required to run the feedback app and starts sessions. Generally this file is loaded at the start of every main PHP page.
includes/templates/bug.php All the HTML for the display of the bug feedback type.
includes/templates/comment.php All the HTML for the display of the comment feedback type.
includes/templates/header.php Contains the page markup that will display at the top of every feedback page (but not the HTML <head> data). Don't remove the 'main' div id tag or rename it unless you also changed the jQuery references in htmlHeader.php
includes/templates/htmlFooter.php Contains any HTML you want to display at the bottom of every feedback page and closes open body and html tags.
includes/templates/htmlHeader.php Contains all data held in HTML <head> tags. Includes jQuery code to process form using AJAX when Javascript is available. Change the references to '#main' here if you've changed the main div id in header.php.
includes/templates/incorrectAction.php Loads when an incorrect action parameter is passed in the URL.
includes/templates/main.php Loads a basic index page. Will typically be seen only by those who do not have javascript enabled, when they click the feedback widget.
includes/templates/success.php This template gets loaded when a form is successfully submitted.
includes/templates/suggestion.php All the HTML for the display of the suggestion feedback type.
includes/templates/validationError.php This template gets loaded when any validation errors occur.
fancybox/ Fancybox documentation can be found here.
widget/feedback.png Image file with transparent background which appears on feedback widget 'tab' section.
widget/feedback_widget.css All the CSS styling code associated with the feedback widget.
widget/jquery.feedback.js The plugin file for the feedback widget. Modify the feedback widget's HTML in here for now (this will be simplified in the future!).

FAQ

How do I add an additional bug report category?
The bug report categories use the HTML select input. In the bug.php file, you can additional options like so: These need to be between the select HTML tags.
How do I modify the feedback widget's HTML?
The HTML is stored within the feedback plugin file: jquery.feedback.js. The following can be modified using standard HTML to change the widget HTML: The lines you are most likely going to want to edit are 5-7, which are the links to feedback.php. You should make these absolute paths so that the feedback widget will work on any pages you have in sub directories. It's important to remember that you will need to escape any single quotes in this text (e.g. as in line 3). If you're adding additional lines also remember to finish each line with a '+' and to enclose each line of HTML in single quotes.
How do I modify the feedback widget appearance?
The feedback_widget.css file contains all the CSS styling code for the widget.

To modify the colours, in the #feedback id and #feedback:hover you will see: You can change these hex values to any colours. The #feedback:hover colour is only applied when the mouse is over the feedback widget.

These lines control the border, font and image styles, and should hopefully be fairly self explanatory: If you wish to modify the widget size, particularly the width, things get a little more tricky - please see changing the widget size.
What are the feedback widget properties and how do i change them?
Feedback widget properties:

Property Description
duration The length of time of the slide out animation in milliseconds.
Default: 500
easing The easing effect of the animation. Mainly for those using this jQuery plugin.
Default: 'swing'
position Positions the feedback widget on the left or right of the page. Use either 'left' or 'right'.
Default: 'left'
inWidth The position of the widget when it's not fully displayed. You will need to change this if you have changed the CSS width value of the feedback widget. Changing the widget size.
Default: '-160px'
outWidth The position of the widget when it's fully displayed. You will need to change this if you have changed the CSS width value of the feedback widget. Changing the widget size.
Default: '-0px'


These all have default values so require no setup unless you want to change them. In the files where you are loading your feedback widget, you can modify any of the values like so,

Replace: with:
How can i change the size of the feedback widget?
In the feedback_widget.css CSS file, the #feedback id contains the width and height of the feedback widget: You shouldn't have any problems changing the height, but changing the width will affect the sliding animation (see below).

If you do change the width you also need to change the position, so on these lines: modify the 'left:' and 'right:' properties. Note although the feedback widget's width is 180, the position is set to only -160 so that there is the initial overlap displaying the 'feedback' tab section. So if you change the width to 200 the position left/right should be -180.

When you change the width the animation will break. To fix this when you're loading the feedback widget in your HTML header you will need override the default inWidth and outWidth properties. In the following example code assume I've changed the feedback widget's width to 280 (see how when the feedback widget is 'collapsed' there is the 20px overlap):
What are the config values and where do i change them?
The config values are stored in includes/config.php.

Property Description
mailTo List of emails to send feedback to. Separate each email with commas, e.g. 'bob@bob.com,john@bob.com'. This value needs to be changed when you setup feedback.
mailFrom The email address to recipients will see that sent the email. Ideally should match domain name to reduce likelihood of spam classification. This value needs to be changed when you setup feedback.
mailSubject The subject of the email.
Default: 'New feedback on your website'
mailGreeting The initial line(s) of text in the email. You can use '@feedback@' (no quotes) which will get replaced with the type of feedback.
Default: ''Hi, some new feedback has been sent from your website. The feedback falls in to the following category: @feedback@. The feedback is as follows:\n\n'
How do I add an additional form fields?

Example 1 - Adding a location drop down

Let's say that as well as optionally collecting the user's name and email address, you want to optionally let them specify their location. Easy! Firstly in includes/templates/comment.php, includes/templates/suggestion.php or includes/templates/bug.php, you need to add some HTML. These are the template files for each feedback submission type and hold all the form HTML.

Find: And add after it: You can add as many locations as you like of course.

Now you need to edit feedback.php. Look for these lines: and after them add: The above line takes the posted data from the 'location' select box we just created in HTML. It's best practice to use 'strip_tags' function on all user posted data, even from select boxes to prevent HTML injection and other nasties.

As we're going to leave it as optional text, there is no strict requirement to validate it, so all you need to do now is find: and modify it to look like this (added line 8):

Example 2 - Adding a feedback score

Now let's say you want to add a additional field to the comment form, allowing your website visitors to score your website from 1 (bad) to 10 (great) and then get this additional feedback in your feedback emails.

Firstly edit includes/templates/comment.php. This file is mostly HTML so should be fairly easy to edit. Below this code: Add these lines: A couple of things to note here. Firstly we set the value attribute of the input using PHP. This means if the form hasn't been submitted the value will be blank, however if the form has been submitted, and say, there are some validation errors, the value the user entered will remain after the page reload. Also I am overwriting the width value of the '.textentry' class which is normally '100%', the reason for this is that only a 1 or 2 digit number needs to be entered so there is no need to have the input that wide.

Now in feedback.php looks for these lines: Add this line after line 2: Next you should validate the user input, say we want to ensure the user has entered a value before sending an email, we also need to check that value is between '1' and '10'.

So after: add: Basically this make sure a score value has been posted and it's not an empty post, then it checks to see if the score value is less than 1 or greater than 10. If either of the statements are true, the '$errors' array gets an additional element with the error message.

Finally you need to do add the '$score' variable to the list of elements that get passed, via the details array, to you in an email. Where you see this: add this on a new line, after line 6: Now all your feedback emails should have the user's website score value.
Does FeedBack work with WordPress blogs - if so, how?
Yes! I successfully got FeedBack to work with the default WordPress blog. See the demo!. Here's how I got it working with the default theme:

DISCLAIMER: I'm no WordPress expert and I can't guarantee this method will work with the theme your using, nor that this is the 'right' way of doing things.

Summary

Hopefully these examples have given you an idea of how you can modify feedback.
However - feel free to contact me if you need additional help.