= Documentation for System Administrators
:!toc:
:stylesheet: ../static/css/custom.css
:icons: font
:stem: latexmath
:last-update-label!:
:favicon: static/img/ddl_favicon_black.svg

== Getting Started

NOTE: Extend section with general steps to set up Django.

Install the Django DDM package:

[source, python]
----
pip install django-ddm
----

Add the necessary entries to INSTALLED_APPS in your settings.py:

[source, python]
----
# settings.py

INSTALLED_APPS = [
    # ...,
    'ddm',
    'ckeditor',
    'ckeditor_uploader',
    'webpack_loader',
    'rest_framework',
    'rest_framework.authtoken',
]
----


Add the following configuration for webpack-loader to your settings.py:

[source, python]
----
# settings.py

WEBPACK_LOADER = {
    'DEFAULT': {
        'CACHE': True,
        'BUNDLE_DIR_NAME': 'ddm/vue/',
        'STATS_FILE': os.path.join(STATIC_ROOT, 'ddm/vue/webpack-stats.json'),
        'POLL_INTERVAL': 0.1,
        'IGNORE': [r'.+\.hot-update.js', r'.+\.map'],
    }
}
----

Include the DDM urls in your projects urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    # ...
    path('ddm/', include('ddm.urls')),
]
----

Configure login and logout endpoints for DDM in urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    ...
    path('ddm/', include('ddm.urls')),
    path('login/', auth_views.LoginView.as_view(template_name='ddm/admin/auth/login.html'), name='ddm-login'),  # You can choose whatever path and template you like
    path('logout/', auth_views.LogoutView.as_view(), name='ddm-logout'),  # You can choose whatever path and template you like
]
----

[CAUTION]
====
If you use DDM on a Django site together with https://wagtail.org/[wagtail] and you
have internationalization enabled for your wagtail urls, we recommend to use the
`prefix_default_language=False` for the i18n_patterns:

[source, python]
----
# urls.py

urlpatterns += i18n_patterns(
    path('', include(wagtail_urls)),
    prefix_default_language=False
)
----

Not doing this will cause ddm.tests.test_apis.test_participant_deletion_with_regular_login to fail.
In practice, the participant API still seems to work properly despite the test failing, however,
unexpected behaviour cannot be ruled out at this point. This will be fixed in a future version.
====

Add the DDM context processor to your template context processors.
This will enable the version indicator of the currently used DDM distribution
below the header in the admin interface.

[source, python]
----
# settings.py

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # ...
                'ddm.context_processors.add_ddm_version'  # Add this.
            ],
        },
    },
]
----


Configure CKEditor settings in your settings.py to allow your users to upload
images and gifs in instructions and question texts:

[source, python]
----
# settings.py

CKEDITOR_RESTRICT_BY_USER = True  # Files uploaded by one user can only be accessed by this particular user
CKEDITOR_UPLOAD_PATH = 'uploads/'
----

Furthermore, add the following to your urls.py:

[source, python]
----
# urls.py

urlpatterns = [
    ...
    path('ckeditor/', include('ckeditor_uploader.urls')),
]
----

DDM uses a custom CKEditor toolbar for instruction and question text definitions
that can optionally be customized (xref:topics/customize_ckeditor_configs.adoc[find out more])


Add time zone support to your settings.py:

[source, python]
----
# settings.py

USE_TZ = True
----

Optionally, an e-mail address restriction can be defined in settings.py. Only users whose e-mail address matches the defined regex pattern will be allowed to set up data donation projects:

[source, python]
----
# settings.py

DDM_SETTINGS = {
    'EMAIL_PERMISSION_CHECK':  r'.*(\.|@)somedomain\.com$',
},
----

Run `python manage.py migrate` to create the ddm models in your database.

Run `python manage.py test ddm` to check that DDM is setup and works correctly.


== Optional Settings

=== Default Header Images

You can provide default images to be included in the header of the participation views.
These images will be displayed by default, but can be overwritten on a project-basis
by researchers in the project settings.

To enable default images, provide the paths to the images that you want to display
in the left and/or right part of the public header in your settings.py as follows:

[source, python]
----
# settings.py

DDM_DEFAULT_HEADER_IMG_LEFT = '/path/to/logo_left.png'
DDM_DEFAULT_HEADER_IMG_RIGHT = '/path/to/logo_right.png'
----
