Installation
Install GDAPS in your Python virtual environment. If you want to create plugins, install cookiecutter too.
pip install gdaps cookiecutter
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 will be used in various places. Must be a valid python identifier.
Note
PROJECT_NAME
is roughly what Django means with ROOT_URLCONF[0]
, but GDAPS requires it to be set 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:
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.