Skip to content

Latest commit

 

History

History
300 lines (222 loc) · 10.1 KB

README.md

File metadata and controls

300 lines (222 loc) · 10.1 KB
Raw

Build Status Coverage Status PyPI version Code style: black PRs Welcome

Django survey

A django survey app that can export results as CSV or PDF using your native language.

django-survey-and-report on pypi. Based on and compatible with django-survey. You will be able to migrate your data from an ancient version of django-survey, but it has been ported to python 3, and you can export results as CSV or PDF using your native language.

Professional support for django-survey-and-report is available as part of the Tidelift Subscription

Table of contents

Language available

The software is developed in english. Other available languages are :

Getting started

Add django-survey-and-report to your requirements and get it with pip.

echo 'django-survey-and-report' >> requirements.txt
pip install -r requirements.txt

Add bootstrapform and survey in the INSTALLED_APPS in your settings :

INSTALLED_APPS = [
	# Your own installed apps here
]

from pathlib import Path

CSV_DIRECTORY = Path("csv") # Define the directory where csv are exported
TEX_DIRECTORY = Path("tex") # Define the directory where tex files and pdf are exported

INSTALLED_APPS += [
	'bootstrapform',
	'survey'
]

Add a URL entry to your project’s urls.py, for example:

from django.conf import settings
from django.conf.urls import include

try:
    from django.conf.urls import url
except ImportError:
    # Django 4.0 replaced url by something else
    # See https://stackoverflow.com/a/70319607/2519059
    from django.urls import re_path as url

urlpatterns = [
    # Your own url pattern here
]

if 'survey' in settings.INSTALLED_APPS:
    urlpatterns += [
        url(r'^survey/', include('survey.urls'))
    ]

Note: you can use whatever you wish as the URL prefix.

You can also change some options:

# Permit to open the csv in Excel without problem with separator
# Using this trick : https://superuser.com/a/686415/567417
EXCEL_COMPATIBLE_CSV = True

# The separator for questions (Default to ",")
CHOICES_SEPARATOR = "|"

# What is shown in export when the user do not answer (Default to "Left blank")
USER_DID_NOT_ANSWER = "NAA"

# Path to the Tex configuration file (default to an internal file that should be sufficient)
from pathlib import Path
TEX_CONFIGURATION_FILE = Path("tex", "tex.conf")

# Default color for exported pdf pie (default to "red!50")
SURVEY_DEFAULT_PIE_COLOR = "blue!50"

To uninstall django-survey-and-report, simply comment out or remove the 'survey' line in your INSTALLED_APPS.

If you want to use the pdf rendering you need to install xelatex. If you're using the Sankey's diagram generation you will also have to install python-tk (for python 2.7) or python3-tk (for python 3.x).

Making a survey

Using the admin interface you can create surveys, add questions, give questions categories, and mark them as required or not. You can define choices for answers using comma separated words.

Creating of a question

The front-end survey view then automatically populates based on the questions that have been defined and published in the admin interface. We use bootstrap3 to render them.

Answering a survey

Submitted responses can be viewed via the admin backend, in an exported csv or in a pdf generated with latex.

Generating a pdf report from the survey's result

There is a default configuration for PDF generation, but you might want to change TEX_CONFIGURATION_FILE for better results (in particular for language other than english).

You can manage the way the report is created in a yaml file, globally, survey by survey, or question by question. In order to render pdf you will need to install xelatex. You will also need python3-tk for sankey's diagram.

The results are generated for the server only when needed, but you can force it as a developer with:

python manage.py exportresult -h

Following is an example of a configuration file. you can generate one with:

python manage.py generatetexconf -h

Basic example

generic:
  document_option: 11pt
"Test survëy":
  document_class: report
  questions:
    "Lorem ipsum dolor sit amët, <strong> consectetur </strong> adipiscing elit.":
      chart:
        type: polar
        text: pin
    "Dolor sit amët, consectetur<strong>  adipiscing</strong>  elit.":
      chart:
        type: cloud
        text: inside

The pdf is then generated using the very good pgf-pie library.

The generated pdf for the polar and pin options

The generated pdf for the cloud and inside options

Sankey diagram

If you installed python3-tk, you can also show the relation between two questions using a sankey diagram :

"Lorem ipsum dolor sit amët, <strong> consectetur </strong> adipiscing elit.":
  chart:
    type: sankey
    question: "Dolor sit amët, consectetur<strong>  adipiscing</strong>  elit."

You get this as a result:

The generated pdf for the sankey example

Advanced example

You can also limit the answers shown by cardinality, filter them, group them together and choose the color for each answer or group of answers.

If you use this configuration for the previous question:

"Test survëy":
  "Dolor sit amët, consectetur<strong>  adipiscing</strong>  elit.":
    multiple_charts:
      "Sub Sub Section with radius=3":
        color:
          Yës: blue!50
          No: red!50
          Whatever: red!50!blue!50
        radius: 3
      "Sub Sub Section with text=pin":
        group_together:
          Nah:
            - No
            - Whatever
          K.:
            - Yës
        color:
          Nah: blue!33!red!66
          K.: blue!50
        text: pin
    chart:
      radius: 1
      type: cloud
      text: inside

You get this as a result:

The generated pdf for the multiple charts example

Implementing a custom treatment

If you want to make your own treatment you can use your own class, for example.

Configuration:

"Test survëy":
  questions:
    "Ipsum dolor sit amët, <strong> consectetur </strong>  adipiscing elit.":
      chart:
        type: survey.tests.exporter.tex.CustomQuestion2TexChild

Code in survey.tests.exporter.tex.CustomQuestion2TexChild:

from survey.exporter.tex.question2tex_chart import Question2TexChart


class CustomQuestion2TexChild(Question2TexChart):

    def get_results(self):
        self.type = "polar"
        return """        2/There were no answer at all,
        3/But we have a custom treatment to show some,
        2/You can make minor changes too !"""

Result:

The generated pdf for the custom example

For a full example of a configuration file look at example_conf.yaml in doc, you can also generate your configuration file with python manage.py generatetexconf -h, it will create the default skeleton for every survey and question.

To guide you during the python development, you can read:

Do not hesitate to make a pull request with your new exporter if it can be of interest for others I'll integrate it.

Credits

Based on jessykate's django-survey, and contribution by jibaku, joshualoving, and ijasperyang in forks of jessykate's project.

We use anazalea's pySankey for sankey's diagram during reporting.