• Pull project from https://github.com/MaxBo/REPAiR-Web

• Optional: Create and activate a python-environment

• Register repair-package and Install dependencies with

pip install -r requirements-dev.txt

• On Windows: *conda install -c conda-forge gdal=2.1

• you have to add the spatialite directory to your PATH

• in the settings.py the following environment variable has to be specified:

• SPATIALITE_LIBRARY_PATH = 'mod_spatialite'

• the spatialite directory contains the mod_spatialite.dll

• with its dependencies from

• http://www.gaia-gis.it/gaia-sins/windows-bin-amd64/

• the following dlls have to be exchanged from the ones from mingw

• according to this blog

• http://blog.jrg.com.br/2016/04/25/Fixing-spatialite-loading-problem/

• rename libstdc++_64-6.dll to libstdc++_64-6.dll.original

• copy libstdc++-6.dll form mingw and rename to libstdc++_64-6.dll

• copy libgcc_s_seh-1.dll form mingw

• rename libgcc_s_seh_64-1.dll to libgcc_s_seh_64-1.dll.original

• Depending on your IDE you may have to set up the environment variable of the sitename manually (DJANGO_SITENAME=repair), e.g. in WingIDE under Project Properties > Environment

• Create a database based on used models with python manage.py migrate

• Start the server on localhost with python manage.py runserver <port-number>

website is then accessible in browser via localhost:<port-number>

Vagrant can set up the development evironment for you automatically. Essentially, it automates the management of virtual machines, thus you also need to have a virtualization provider (e.g. VirtualBox, VMware) installed. Then the REPAiR-Web server is set up and runs on a virtual machine (guest), completely isolated from your host. Yet, you can edit the source code on your host, with the same tools as normally, the code (actually the whole REPAiR-Web directory) is shared between the host and the guest.

Once Vagrant is up and running, Django is listening at http://localhost:8081 on the host.

Packages

Paths and files (packages not listed)

• see https://en.wikipedia.org/wiki/Representational_state_transfer

• defined in django with the django-rest-framework (see http://www.django-rest-framework.org/)

• provides serialized JSON-representations of resources (or html-views if accessing via browser)

• API to be accessed by the javascripts on client-side (if you want to fill the django-templates directly you may ignore it and use the django-models instead)

• url-entry-point is <website-adress>/api

• the url represents resources inside the database (see next table)

• List-routes of resources always interchange with a detailed Instance-route when progressing deeper (e.g. /api/casestudies/ shows you all casestudies and their attributes incl. the id, /api/casestudies/1 shows you the details of the casestudy with id 1)

• deeper routes always have a relation to it’s predecessing subroutes (e.g. /api/casestudies/1/activities show all activities of casestudy with id 1)

• same resource-types may have different routes depending the relations they want to show with it’s route (e.g. /api/casestudies/<id>/activities and /api/casestudies/<id>/activities

• the routes are defined in /repair/rest_urls.py

• the modularization is achieved by using django-require (post-processor for optimizing with RequireJS)

• paths and variables for django-require are set up in repair.settings, require-path is set to /repair/static/js/

• organized as apps (analog to django-apps)

• entry points for the apps are located in /repair/static/js/

• <app-name>.js is loaded in django-template via {% require_module ‘<app-name>’ %}

• require-config.js defines all required javascript-modules and maps them to custom names; will load them on demand; all entry points have to require this file in order to be able to use the defined modules which are defined there

• Backbone.js is used to organize data retrieved from the Rest-API and dynamically making views on the data and to interact with them (btw. Backbone takes heavy use of jQuery … meh :( )

Paths and files

• a model that represents a single resource (a.k.a instance) in the Rest-API

• collections hold an amount of models of the same type, represent lists of resources in the Rest-API

• models and collections have to contain the API-url they are retrieved from / send to (stored in one place in the app-config for a better overview)

• models/collections can be allocated via the new-Operator and then be fetched / deleted / posted from / to the Rest-API (see http://backbonejs.org/#Model respectively http://backbonejs.org/#Collection )

• used client-side for dynamically creating and removing views on data

• they always require the html-element to render them in and should receive a model/collection whose data they shall render and modify on demand (that’s the whole point of using them: click some data to view and change it)

• they use the Underscore-template-engine, which is working similar to the django-template-engine but with slightly different syntax (see http://underscorejs.org/#template )

• for localization/overview purposes you should put the templates directly into the django-template of the according app:

<script type="text/template" id="...">

…

</script>

• access the template via it’s id and get the inner html in order to pass it to the Underscore-template-engine

• views should always be closed before replacing them, otherwise you get ‘ghost-views’ (define it yourself inside the view, see /repair/static/js/app/views/admin-edit-flows-view.js for an example)

Don’t push directly into the master branch!

1. Checkout to new branch.

2. Write a test.

3. Write new Code and label strings for translation.

4. Commit and push to your branch.

5. Create pull-request on Github.

6. Wait for CircleCi to test the code.

   1. If build was successfull:

      1. Merge your branch into master.

   2. Else:

      1. Fix the error, restart at 4., …

7. Server automatically pulls master branch.

8. Website is updated and you can start at 1. again.

Have a look at Workflow.pdf for further information.

-   We use a Github-webhook to keep our website up-to-date. That means:
    Changes (push and pull requests) to the master-branch trigger a
    webhook-event, that is sent from github to
    <http://geodesignhub.h2020repair.bk.tudelft.nl/api/payload>. This event
    calls a function that automatically pulls the current master branch, so
    that our website is always up-to-date with the remote master branch.

-   We use Continuous Integration to test the code before it is merged to
    our master branch. This helps to detect errors before our website is
    updated with new code. Every time someone pushes new commits to any
    branch of our remote repository, CircleCi creates a build environment
    and runs our tests on their servers. This takes about 1-2 minutes. You
    can review the current build status here:
    <https://circleci.com/gh/MaxBo>. The github repository settings require
    a successful CircleCi-build in order to merge them to the master branch.
    This means: **No one (except MaxBo) can directly push any commits to our
    master branch.** If you want to commit something, create a new branch,
    commit and push to that branch and create a pull request. CircleCi
    automatically tests that branch and if all tests run successfully you
    can merge the new code from your branch to the master branch. For more
    information look at the Workflow section.

-   Django tests are directly written into the apps directory. For example:
    The tests for the study_area section are written into
    *../repair/apps/study_area/tests.py*.

-   Basic structure:

from django.test import TestCase

class TestTestCase(TestCase):

def test_test(self):

self.assertEqual("this", "that")

• To run the tests:

  • open terminal

  • cd to your directory

  • and type “manage.py test”

**When you edit any code: Please label all strings that need to be
translated later on!**

• In html-files:

  • Import: {% load i18n %}

  • Label: {% trans "MyString" %}

• In Python-files:

  • Import: from django.utils.translation import ugettext as _

  • Label: _("MyString")

• All labelled strings are detected automatically and collected in a .po-file. This file is used for translations.

• cd to .../repair$

• Type "makemessages -d djangojs -l de -e html,js,py". This looks up all .html, .js and .py files and generates the file locale/de/LC_MESSAGES/djangojs.po.

• Before:

#: templates/base.html:5

msgid "Hello, this is built with Django Internationalization"

msgstr ""

• After:

#: templates/base.html:5

msgid "Hello, this is built with Django Internationalization"

msgstr "Hola, esto está construido con la Internacionalización de Django"