Skip to main content

A simple Django app that enables user feedback.

Project description

https://img.shields.io/pypi/v/django-tellme.svg https://img.shields.io/github/license/ludrao/django-tellme.svg

tellme

tellme is a simple Django app that provides an easy and simple feedback button, form and admin view.

Features

  • Take a screenshot of the current page.

  • The user can then highlight or black out portions of that screenshot

  • The user have to provide textual comments, (effectively giving his feedback)

  • Some additional information collected with the feedback
    • various browser information (versions, user agent, etc.)

    • user information if the user is logged in (and your site uses Django auth system)

    • the url the user provides feedback on

  • Optionally, send an email to the site admin when a feedback is posted

  • Supports localization (currently supported languages are English and French, translation contrib are welcomed!)

  • Customizable UI by redefining templates

The javascript part of this app is using feedback.js from https://github.com/ivoviz/feedback. feedback.js itself use html2canvas.js (https://github.com/niklasvh/html2canvas) to make page screenshot that is sent with the feedback comments.

Dependencies

This application depends on
  • python 3 (might work on python 2, but untested)

  • django >= 1.8

  • jquery must be enabled in your pages

Quick start

  1. Install the app in your environment:

pip install django-tellme
  1. Add “tellme” to your INSTALLED_APPS setting like this:

INSTALLED_APPS = [
    ...
    'tellme',
]
  1. Include the tellme URLconf in your project urls.py like this:

url(r'^tellme/', include("tellme.urls", namespace="tellme")),
  1. Run python manage.py migrate to create the tellme model in the database.

  2. Add a feedback button in your pages so that user can provide feedback

For example using bootstrap CSS this code would overlay a button, vertically aligned on the middle of the page, right-aligned.

In your html/template file, import the form CSS:

<link href="{% static 'tellme/feedback.css' %}" rel="stylesheet">

In your html/template file, inside the <body> section:

<button type="button" id="feedback-btn" class="btn btn-info vertical-right-aligned">
    Feedback <span class="glyphicon glyphicon-bullhorn" aria-hidden="true"></span>
</button>

Note: the CSS class vertical-right-aligned is not from bootstrap, it is defined as:

.vertical-right-aligned {
    transform: rotate(-90deg);
    transform-origin: 100% 100%;
    position: fixed;
    right: 0;
    top: 50%;
    z-index: 100;
}

In your html/template file, in the page footer, connect that button to the feedback plugin:

{%  include 'tellme/js_inc.html' %}

Look into this template file, it includes a few things that can be overridden (using the Django template {% extend %} mechanism), or simply redefined it in your page. What js_inc.html contains by default:

  • Load jquery plugin

  • Add CSRF automatically to all AJAX post request

  • Enable the JS feedback plugin using customizable template for each feedback step

  1. Start your site, and click the feedback button. This will pop up the feedback form. Follow the instruction, and click on Send when finished.

  2. Visit http://127.0.0.1:8000/admin/ to review user feedback.

How to customize the JS feedback popup UI

Each step of the feedback popup is an HTML UI element that can be redefined. In order to define your custom UI, you simply have to ‘overload’ the template by creating, in your own app template directory, a file with the same name as the original tellme template. The feedback popup contains 4 steps + an error screen, that can be redefined. Look for the following files:

  • tellme/tpl-description.html

  • tellme/tpl-highlighter.html

  • tellme/tpl-overview.html

  • tellme/tpl-submit-error.html

  • tellme/tpl-submit-success.html

As an easy way to start you can copy one of the above file in your template directory and modify it incrementally. Please note that you need to keep the same directory structure (i.e. tellme/tpl-xxx.html), and that your app has to be listed first in the INSTALLED_APPS list so that it takes this modified template file instead of the original tellme template file.

Email notifications

This app can send you an email every time a feedback is posted. Currently the email is plaintext and does not contain the screenshot. However it does contain a link to the admin site with the full details of that feedback.

To enable email notification, just add this line in your site settings.py:

TELLME_FEEDBACK_EMAIL = 'admin@tellme.com'

Important Notes

Version History

version 0.3

special thanks to llann for i18n initial support

  • Added internationalization support, defaulting to English localization.

  • Added French localization

  • Added an “include” template to simplify usage

  • Used minified version of js libraries

  • Provided a template structure so that the UI can be customized

Improving this app - TODO

This app was developed in rush for a simple yet complete, non intrusive, feedback tool. It does lack a lot of cool features. If you like to contribute, please do not hesitate!

  • Provide a customization mechanism for the email body, make it text+html.

  • Add continuous integration testing

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-tellme-0.3.tar.gz (87.2 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page