This repository contains a Django application for the D-PLACE Project.

For development purposes, the Vagrant+Ansible configuration is recommended. It automates the build of an Ubuntu Linux VM with D-PLACE installed and ready for testing/development.

Additionally, the Ansible playbook creates OS and database users for D-PLACE, installs all software dependencies, and populates the database from the working group's data sets. You can use ansible by itself to provision D-PLACE on a host, or study the playbooks as a recipe.

The rest of the information on this page assumes you are not using the Vagrant+Ansible configuration.

D-PLACE requires Postgres with the PostGIS extension installed. Both versions 9.2 and 9.3 have been used for development.

D-PLACE also requires the following software:

• Git
• Python (2.7 preferred)
• python-psycopg2 (for connecting to Postgres)
• Postgres with PostGIS
• the Postgres unaccent extension.

D-PLACE has been developed on Mac OS X 10.9 as well as Ubuntu Server 12.04.

If you plan to do development, you should fork the GitHub repo first, and work with that.

git clone git@github.com:D-PLACE/dplace.git (or your fork)

For best results, install python dependencies for D-PLACE in a virtualenv

The python dependencies are specified in the requirements.txt file.

Activate your virtualenv source /env/bin/activate and install dependencies with pip install -r requirements.txt

D-PLACE uses a few JavaScript libraries, which are stored in dplace_app/static. Though all the required JavaScript libraries are contained in the source repository, they can be managed/updated with Bower. The bower.json file specifies dependencies and versions.

With dependencies installed and a clone of the source repository in place, the next step is to create a settings.py file:

	cp dplace/settings.template dplace/settings.py
	<edit> settings.py

Be sure to update the following sections:

1. ADMINS: Name and email address of site administrator(s)
2. DATABASES: Connection info and credentials for PostgreSQL host
3. TEMPLATE_DIRS: Absolute local path to dplace_app/templates
4. STATICFILES_DIRS: Absolute local path to dplace_app/static
5. DATASETS: Names of datasets to install.

To install the database, run

python manage.py migrate

This requires valid database credentials in settings.py, and activation of your virtualenv if enabled.

D-PLACE is mainly built with Django and AngularJS. Django is used to model/query data stored in the relational GIS database, and AngularJS is used to build a JavaScript-based browser application that provides an interface to the data. The Django REST Framework is used to build a JSON API between Django and AngularJS.

The Django REST Framework is a powerful framework for building RESTful web services in Django. API endpoints are created as Django views, and can either be class-based or function views. In either case, the framework provides a lot of the functionality. API views are created in dplace_app/api_views.py and connected to URLs in dplace_app/urls.py

Most of the Models are exposed as simple ReadOnlyModelViewSets, which means the REST framework creates methods to list all objects and get individual objects.

In order to convert data between JSON (or XML) and Python model objects, the REST framework uses Seriializers. These are classes located in dplace_app/serializers.py, and they describe what fields and related objects to include when serializing an object to JSON. Serializers can also represent arbitrary (non-model-backed) objects like search queries or results.

Most of the D-PLACE user interface is a single-page application written in JavaScript and HTML, powered by AngularJS and Bootstrap.

AngularJS is a JavaScript web framework with features like 2-way data-binding and native support for RESTful JSON APIs.

The front-end application code is primarily in dplace_app/static, except for the entry-point template at dplace_app/templates/angular.html. This template is served by Django and includes all necessary JavaScript and CSS files for the AngularJS app.

As a best practice, avoid putting AngularJS code into Django templates. This could result in collisions between Angular's template language and Django's. The angular.html template should only be used to include JavaScript files and other resources that must be present at startup.

D-PLACE data is collected/curated by the Working Group, and periodic CSV exports have been stored in a private Github repository.

To load the data, run the load_all_datasets.sh script. This scripts clones the repository, and runs dplace_app/load.py with appropriate parameters for each of the CSV files we import. The python files in dplace_app/load/ are tailored to each CSV file format.

The Vagrant+Ansible configuration will perform the first data load, but this step can be repeated to load new data.

D-PLACE uses Django's built-in testing framework, tests can be run with

python manage.py test

Test scripts located in dplace_app/tests and should be kept up-to-date with new functionality. The tests cover model and API functionality, but not yet the AngularJS layer.

To run the built-in django web server, run

    python manage.py runserver 0.0.0.0:8000

which will make the app available at http://localhost:8000.

The Django project advises not to use the built-in webserver for production deployments. While they don't provide a bundled production-ready server, they do have deployment documentation.

Though Django supports placing the STATIC_ROOT anywhere on the server (Templates should be using {% static %} instead of hard-coding URLs), many of the AngularJS files reference resources with an absolute path like /static/partials/search/..., which could break.

For code changes, please fork the repository and submit a pull request. For bugs or feature requests, please create a GitHub issue.