Getting Started

Introduction

Django Public Project (DPP) can be best described as a special kind of Content Management System (CMS), tailored to the peculiarities of big projects, which often tend to becoming fairely complex and intrasparent when they evolve. Below is a screenshot of the front-end view of the example project:

_images/example_project_dashboard.png

Use Cases

With DPP it is possible to build up an in-depth information website around a big project which can be used...

  • ... by administration to inform the public about the progress of an ongoing project and so increase acceptance for it.
  • ... by civic groups to monitor the progress of a project.
  • ... by parliament for an enquiry around a project where certain problems occured.

Features

DPP comes with an administration interface, where various high-level information around a project can be inserted and maintained. Which important stakeholders are involved in the project? What are important events? How is the project structured? All this information is then presented as a front-end website visible for end-users.

Notable features of the software are:

  • Extensive admin interface
  • Beautifully layouted front-end website
  • Tags and external links for all project objects
  • Full-text search
  • Document manangement with integrated PDF viewer
  • Advanced commenting system for end-users
  • Languages available: EN/DE
_images/example_project_admin.png

Technology

DPP is build with Python/Django and comes as a Django app providing all the data models necessary together with the templates for the front end layout. This app can be integrated in a Django project representing the concrete project to be targeted.

Warning

This software currently is in beta status. It can be used in a productive environment, but please follow closely the Release Notes if you want to make an update of the software and have an eye on changes in Django model declarations, software dependencies or config settings.

Installation

Requirements

For installing DPP you need the following Python/Django libraries, probably best installed in an own virtualenv environment:

  • Python 2.7+ (earlier versions untested)
  • Django 1.5 (1.6+ not yet supported)
  • PDFMiner (Version 20110515 to avoid dependency errors!)
  • Pillow 2.5.2+ (Replacing PIL, for Django ImageField type)
  • Tastypie 0.9+ (for API access)
  • South 0.7.6+ (to keep track with DB changes)

For PDF conversion to jpg files for having an IE compatible PDF viewer, you need to have the ImageMagick library with the convert command installed in your shell environment:

Note

There are some fabric tasks which can help you set up an environment for DPP located in an own GitHub repository which can be found here: https://github.com/holgerd77/django-public-project-fabric-tasks/

Installation with Pip

DPP is on the Python Package Index and you can install the software with all dependencies with:

pip install django-public-project

Manual Installation

If you want to have the latest version of DPP, you can install the sources manually with PIP (or directly clone the GitHub repository):

pip install -e git+https://github.com/holgerd77/django-public-project.git@master#egg=django-public-project

Then install the requirements above. There is a requirements.txt file in the main directory of the repository you can use:

pip install -r requirements.txt

Project Creation

Create your Django project:

django-admin.py startproject myprojectwatch

Add the Django apps installed to your settings.py file (of course you also need the admin app which is essential for DPP):

INSTALLED_APPS = (
    ...
    'public_project', # Since DPP changes some admin templates, app has to be placed before admin
    'django.contrib.admin',
    'tastypie',
    'south',
)

Sync your database respectively use migrations for DPP:

python manage.py syncdb (due to database dependencies, don't create a superuser yet)
python manage.py migrate
python manage.py createsuperuser

Configuration

DPP is not really an app which you would install beside many other Django apps and integrate it in a more complex website. It is more a content management system already coming with an url structure and a given layout capsuled in a single app. So DPP takes control of more things than the normal Django app.

URL structure

The urlpatterns for your project are completely coming from DPP, with an exception of the admin url, which should be adoptable for security reasons. So your minimal urls.py should look similar to this, importing the main url patterns from public_project.urls:

from django.conf import settings
from django.conf.urls import patterns, include, url

from django.contrib import admin
admin.autodiscover()

from public_project.urls import urlpatterns

urlpatterns += patterns('',
    url(r'^admin/', include(admin.site.urls)),
)

# Necessary for being able to use image upload in DEBUG mode
if settings.DEBUG:
    urlpatterns += patterns('',
        (r'^media/(?P<path>.*)$', 'django.views.static.serve', {
        'document_root': settings.MEDIA_ROOT})
    )

Now you should be able to enter both the admin view and an emtpy front-end dashboard site when you start a dev server. The site itself is not yet ready for prime time at this moment.

_images/example_project_admin.png

Basic settings

Since I’m not sure, if there are still some static references to static or media files somewhere in the code, you should use the following STATIC_URL and MEDIA_URL settings:

MEDIA_URL = '/media/'
STATIC_URL = '/static/'

For being able to get email notifications about comments and document relations, you need to configure the Django email settings properly:

EMAIL_FROM = 'admin@yourmailaccount.com'
EMAIL_HOST = 'smtp.yoursmtpserver.com'
EMAIL_HOST_USER =  'YOURUSERNAME'
EMAIL_HOST_PASSWORD = 'YOURSECUREPASSWORD'

DPP uses the request template context processor in its views and adds its own context processors, add them to the settings.py file:

from django.conf import global_settings
...

TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + (
    "django.core.context_processors.request",
    "public_project.context_processors.uploaded_images_list",
)

Language Selection

At the moment DPP supports the following languages:

  • English (en) (experimental and not yet used in production, probably you have to correct some stuff)
  • German (de)

The language is chosen depending on the LANGUAGE_CODE param in the settings.py module, e.g.:

LANGUAGE_CODE = 'de-de'

Document upload/viewer

The document viewer in DPP is based on the Mozilla pdf.js library (included in DPP) when using modern browsers like Google Chrome, Firefox or Safari.

For being able to view on site pdf documents with the Microsoft Internet Explorer there exists a basic alternative pdf viewer. For this viewer, single pages are converted to png files and are stored on disk and you need to have the ImageMagick library installed and make sure that the convert command from this library can be used from within your project path.

Since this approach can take a lot of disk space for large documents and root access to the server is needed, you have to activate IE compatible pdf viewer usage with the following setting in your settings.py file:

DPP_IE_COMPATIBLE_PDF_VIEWER = True

If this setting is set to false (default) a warning message will be shown on the document page for IE users, prompting them to use an alternative browser.

If this setting is set to true, documents are saved as the original pdf file and a corresponding document_x folder containing the pngs in your media folder. Please test-upload a pdf document and see if these files are generated. Then test the url with the pdf viewer for this document in both the MSIE and another browser.

Note

The conversion process of a pdf document takes place in the background and may take a while for large documents.

Site Domain

For urls in comment emails to work properly, you have to edit the Site object, which Django should have created in the Sites section in the Django admin.

Provide your fully qualified domain name there (e.g. ‘yourproject.yourdomain.com’), without trailing ‘http://‘.

JSON API

Since v.0.4 DPP comes with a public API, which let developers access the public data of the system, leaving out internal comments and user comments. The API supports no authentication mechanism yet and will be accessible by everyone without limitation. To activate the API, add the following to your settings.py file:

DPP_PUBLIC_API = True

For the API to work you have got to have Tastypie 0.9.15+ installed:

pip install django-tastypie

And add tastypie to your INSTALLED_APPS.

When the API is working there will be an extra link in the footer leading to to API overview page:

http://yourproject.org/api/

Note

The API is still in an experimental/early stage, many features are missing and usage params will probably change in the future.

Where to go from here?

The main set-up process for your project website is now finished and the site is ready to be filled with some data.

Congratulations! :-)

Start by adding/changing some configuration parameters and introductory texts in the SiteConfig and SiteCategory menu.

In the next chapter you will learn how to use the admin interface and how to build up an information website around your project.