About

Build Status

Lots of websites have polls, usually as a little side bar. But most of those polls are based on plurality voting, an inferior voting method. Approval_frame is a replacement for those polls, using approval voting, which is suitable for embedding in other webpages via an iframe tag. The project, taken as a whole, will serve these approval-based webpolls, or the approval_polls package contained within it can be added to other Django-based servers to be used locally.

Dependencies

Option 1 : Manually install the following

  1. Python (2.7)
  2. Django (1.8.1)
  3. django-registrations-redux package (1.1).
  4. dj-static (0.0.6)
  5. pytz (2015.7)
  6. python-openid (2.2.5)
  7. requests-oauthlib (0.6.0)
  8. python-social-auth (0.2.13)
  9. mailchimp (2.0.9)
  10. django-extensions (1.7.9)

Option 2 (Recommend) : Use virtualenv and pip

To learn more about why virtualenv and pip should be used, refer - A non-magical introduction to Pip and Virtualenv for Python beginners

  1. Install Python 2.7 from the link in step 1 above.
  2. Install pip globally sudo apt-get install python-pip.
  3. Install virtualenv globally sudo pip install virtualenv.
  4. Enter the directory that contains this readme file.
  5. Create a new virtual environment virtualenv env.
  6. Activate the virtual environment source env/bin/activate
  7. Install the dependencies pip install -r requirements.txt

When you're done working on the project, you can quit the virtualenv by running deactivate.

Steps (assumes a linux system)

  1. Install git. If you're new to git then the Pro Git book is useful.

  2. Clone this repository. git clone https://github.com/electionscience/approval_frame.git.

  3. Go into the approval_frame directory. cd approval_frame.

  4. For the registration procedure to work correctly, in development (since we do not want your Email ID and password to be committed to Github), create a new file approval_frame/local_settings.py and add in the following email configuration.

    EMAIL_USE_TLS = True
    EMAIL_HOST = 'hostname of the smtp server'   # eg. 'smtp.gmail.com' for Gmail.
    EMAIL_PORT = 587                             # 587 for smtp
    EMAIL_HOST_USER = 'username or email'        # eg. myaddress@gmail.com 
    EMAIL_HOST_PASSWORD = 'password'             # Your password string
                                               # or 16 character app password (2 step auth)

    approval_frame/local_settings.py already exists in .gitignore.

  5. Also, in development, set the DEBUG variable to True in the approval_frame/local_settings.py

    DEBUG = True
  6. Before you run the Django server for the first time, you'll need to create the database tables:

    python manage.py syncdb

    This will ask you to create a superuser account, which is necessary if you want to use the Django admin interface. But also, you'll need a user account in order to create polls in the system, and it's easiest to do that here. (If you don't create an account here, you'll have to mess around copying urls from from the server output to fake confirming an email address in order to create a user account later... so just do it now.)

    If you would like to setup social authentication for your app while in development, please refer to the following document: Configure Social Authentication

    For the newsletter subscription functionality to work in production and development, please add the following in approval_frame/settings.py and approval_frame/local_settings.py respectively.

    MAILCHIMP_API_KEY = '************************************'

    The API key is protected and can be obtained by mailing the current project lead(s).

  7. Start the Django server:

    python manage.py runserver

  8. Change the domain name of the site example.com to yourdomainname in the admin panel so that the activation emails have the correct url.

  9. Finally, see how it looks. In your favorte browser, go to the link:

    <your domain name>:<port>/approval_polls

    If you're running the server locally then this would be

    http://localhost:8000/approval_polls

    There won't be any polls yet, but you can login with the superuser account you created. Then you should be able to create polls, vote in them, and see the results.

    NOTE: If you want Django to run on a public IP, make sure you update the ALLOWED_HOSTS variable to include the required IP address in your local_settings.py. Be careful to ensure that in production, 'localhost' is not included in this variable.

Contributing

  1. If you're new to Python, Google's Python tutorial gives a basic introduction to the language. There are several other tutorials available on the web.
  2. If you're new to Django, the tutorial on Django's documentation page is very comprehensive. In fact, through a happy coincidence, it uses a poll application as an example. This project is heavily based on that tutorial.
  3. If you're new to git, as mentioned above, the Pro Git book is very useful.
  4. In order to contribute, please follow the fork-and-pull-request model as documented here. Also, do check out the coding style guidelines outlined in the next section.

All contributions are welcome.

Coding Style

As far as possible, we choose to adopt the coding style standards as set by the Django project (outlined here). Given below are recommendations for linting different types of files:

Paying close attention to standards and consistency will definitely help improve code readability and ensure focus on building/fixing issues, rather than being distracted by dissimilarities in code.

Testing the code

  1. Whenever new code is written and features are added, there is a possibility that existing functionality may break. So just to be on the safer side, it is good to make sure that all is well - by running:

    python manage.py test

  2. Apart from adding new test cases to cover new functionality, it is always a good practice to keep a check of the code coverage with the tool coverage to make sure that the code is still well tested. Read more about this here !

Deploying in production

This section is only applicable to you in case you are deploying this app in production, not while developing. In production, it is strongly recommended that DEBUG be set to False. With this, Django does not serve static files out of the box. More information on this here.

  1. Run the following command to collect static files from all installed apps and place them in the 'staticfiles' directory (as given by the STATIC_ROOT variable).

    python manage.py collectstatic

  2. Since Django does not serve static files in production by default, we make use of a simple WSGI middleware library dj-static, that provides a Django static file server. Our polls app has been configured to run in production and serve static files once dj-static has been installed.

  3. Also, do make sure that the ALLOWED_HOSTS variable contains the required production domain name/IP address as outlined in the deployment checklist.

Discuss

Have a question? Want to discuss something? Head over to the forum at https://groups.google.com/forum/#!forum/ces-software.