Installation

Install GDAPS in your Python virtual environment:

pip install gdaps

Create a Django application as usual: django-admin startproject myproject.

First, set a variable named PROJECT_NAME.

PROJECT_NAME = "myproject"

This is a (machine) name for your project. Django itself does not provide such a name. It ill be used in various places, e.g. when creating frontends for plugins. Must be a valid python identifier.

Note

PROJECT_NAME is roughly what Django means with ROOT_URLCONF[0], but it’s better to set it explicitly.

Now add “gdaps” to the INSTALLED_APPS section, and add a special line below it:

from gdaps.pluginmanager import PluginManager

INSTALLED_APPS = [
    # ... standard Django apps and GDAPS
    "gdaps",
]
# The following line is important: It loads all plugins from setuptools
# entry points and from the directory named 'myproject.plugins':
INSTALLED_APPS += PluginManager.find_plugins(PROJECT_NAME + ".plugins")

You can use whatever you want for your plugin path, but we recommend that you use “<PROJECT_NAME>.plugins” here to make things easier. Basically, this is all you really need so far, for a minimal working GDAPS-enabled Django application. See Usage for how to use GDAPS.

URL handling

Now add the URL path for GDAPS, so it can add plugins’ URLs automatically to the global urlpattern.

# urls.py
from gdaps.pluginmanager import PluginManager

urlpatterns = PluginManager.urlpatterns() + [
    # ... add your fixed URL patterns here, like "admin/", etc.
]

This way each plugin can have an urlpatterns variable in urls.py, and all are merged together. However, by now, the plugin order is not determined, so urlpatterns too are not in a deterministically determined order. This could lead to problems, depending on your application design, so keep that in mind when designing plugins.

Logging

Django does not write loggings to the command line automatically. GDAPS uses various levels of logging. It is recommended that you create a LOGGING section in settings.py for GDAPS:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "gdaps": {"handlers": ["console"], "level": "INFO", "propagate": True},
    },
}

This will output all GDAPS log messages to the console.

Frontend support

If you want to add frontend support to your project, you need to add gdaps.frontend (before gdaps!), and webpack_loader to Django.

Frontend engines are packed in plugin eggs. You can easily install them using pip, e.g.

pip install gdaps-frontend-vue

Then you have to tell Django which engine to use:

GDAPS = {
    "FRONTEND_ENGINE": "vue",
}

Further configuration may be necessary depending on your frontend plugin. Available plugins ATM:

  • Vue

  • PySide (currently only stub)

There are some keys in this section to configure:

FRONTEND_DIR

This is the directory for the frontend, relative to DJANGO_ROOT.

Default: frontend

FRONTEND_ENGINE

The engine which is used for setting up a frontend. ATM it can only be “vue”. In future, maybe other engines are supported (Angular, React, etc.). PRs welcome.

FRONTEND_PKG_MANAGER

This is the package manager used to init/install packages. It depends on your frontend which are available.

PROJECT_TITLE

A title for your project. If left empty, PROJECT_NAME is taken (without hyphens/underlines and capitalized).

Default: PROJECT_NAME, without underlines and capitalized.

ADMIN

True if your app should add the GDAPS specific parts to the Django admin panel. You can e.g. see the installed plugins there.

Default: True

Final step

Now you can initialize the frontend with

./manage.py initfrontend

This creates a basic boilerplate frontend, depending on which engine is installed.