The functionality of the Airavata Django Portal can be extended by adding custom Django apps that can provide completely custom user interfaces while leveraging the Airavata Django Portal REST API. This page documents how to get started with creating a custom Django app that works with the Airavata Django Portal and how to make use of functionality provided.
Creating a custom Django app requires creating an installable Python package with metadata describing that it is a Django app meant to be automatically installed into the Airavata Django Portal when it is loaded into the virtual environment.
We‘ll use a project code generation tool called Cookiecutter to generate all of the necessary files and configuration. These steps will show how to use Cookiecutter. Then we’ll take a tour of the generated code.
pip install -U cookiecutter
cookiecutter https://github.com/machristie/cookiecutter-airavata-django-app.git
You‘ll need to answer some questions. The project name is the most important one. You can name it whatever you want. For these instructions I’ll name it Custom Django App. For the rest of the questions, you can simply accept the defaults:
project_name [My Custom Django App]: Custom Django App project_slug [custom_django_app]: project_short_description [Custom Django app with everything needed to be installed in the airavata-django-portal]: app_config_class_name [CustomDjangoAppConfig]: version [0.1.0]:
custom_django_app
.(venv) $ cd custom_django_app/ (venv) $ find . . ./pyproject.toml ./MANIFEST.in ./README.md ./setup.py ./.gitignore ./setup.cfg ./custom_django_app ./custom_django_app/models.py ./custom_django_app/__init__.py ./custom_django_app/apps.py ./custom_django_app/admin.py ./custom_django_app/static ./custom_django_app/static/custom_django_app ./custom_django_app/static/custom_django_app/README.md ./custom_django_app/output_views ./custom_django_app/output_views/__init__.py ./custom_django_app/templates ./custom_django_app/templates/custom_django_app ./custom_django_app/templates/custom_django_app/home.html ./custom_django_app/tests.py ./custom_django_app/urls.py ./custom_django_app/views.py
pip
to install it.pip install -e .
$ git init
Now we'll take a tour of the generated files.
In the root directory are several Python project files: pyproject.toml, MANIFEST.in, setup.py, and setup.cfg. setup.cfg is the most important of these since it defines Python package name, version, description, dependencies, etc. In the custom Django app module directory (custom_django_app in the example above) are where you will find the generate Django Python and HTML code. Here are some things you may need to update as you develop your custom Django app:
This file defines the custom Django app‘s AppConfig class. This the main metadata for this custom Django app. Besides the normal metadata that the Django framework expects, this also defines a display name (verbose_name
) and an icon (fa_icon_class
) to use for this custom app. See AppConfig settings for details on available properties here. Note that app_order
isn’t supported for custom Django apps. Only name
, label
and verbose_name
are required. See Django project documentation on AppConfig for description of these properties. Additionally, custom Django apps can specify the following properties:
label
property is used as the URL prefix, but by setting url_prefix
you can override that. (Example: SimCCS)This is where you define your Django views. Views are functions or classes that take as input an HTTP request and generate an HTTP response. See part 1 of the Django tutorial for more information.
In the generated views.py file there is simple view function called home
that simply renders the home.html
template. There is also some commented out code that shows how to, for example,
Also note that if you want to require authentication for your view, just add the @login_required
decorator.
HTML templates are added to the templates/
folder. The standard convention in Django is to create a directory in the templates/
folder with the name of the Python module and put your template in there, as a way to namespace the names of an app's templates.From the Django docs:
It’s possible – and preferable – to organize templates in subdirectories inside each directory containing templates. The convention is to make a subdirectory for each Django app, with subdirectories within those subdirectories as needed.
The generated home.html
file uses a couple of Django template features. First is the use of named blocks that extend a base template. By extending the base.html
template, your custom Django app will fit into the over Airavata Django Portal. There's a block for adding the main content, called content
, and there is a block for JavaScript code called scripts
and a block for CSS called css
. Also, the home.html template references a context variable, {{ project_name }}
, a variable that is placed in the context by the home
view function defined in views.py. To learn more about Django templates, see the Django tutorial, part 3.
home.html
also has some commented out example code showing how to use the JavaScript SDK. The JavaScript SDK allows you to write frontend code that interacts with the Airavata API via the Airavata Django Portal REST API.
To map your view function to URLs, you add a URL pattern to urls.py
. The generated urls.py
already has a mapping for the home
view function. As you add additional view functions, you'll want to add a mapping to a URL pattern here.
Put static folders into the static/custom_django_app
(or whatever you named your django app) subdirectory. You can then reference a URL to one of these static file in a template by using the static
template tag, like so:
<script src="{% static 'custom_django_app/some_script.js' %}"></script>
See the README.md in the static/
subdirectory for more information.
This is the folder where you can define output view providers. An output view provider is a Python class that creates a visualization of an output file by generating an image or other appropriate data from the output file.
Now when you log into the Django portal at http://localhost:8000 you should see the custom app in the dropdown menu in the top of the page (the one that defaults to Workspace when you login).
To use the airavata-api.js
JavaScript library to call the Django portal REST API (which in turn calls the Airavata API), you can include it in your templates in the scripts
block:
{% block scripts %} <script src="{% static 'django_airavata_api/dist/airavata-api.js' %}"></script> <script> const { models, services, session, utils } = AiravataAPI; // Your code here ... </script> {% endblock scripts %}
For more information on the AiravataAPI library:
There are now several examples of custom Django apps that can be learned from: