How to Integrate a new Module

Start your Django app by running the following command inside the top-level heliport module (i.e. $REPO_ROOT/heliport):

heliport-cli startapp your_app_name

This will create a new app directory on the same level as the existing ones.

After you changed the database schema update the database:

Note

In some environments your_app_name might not be required as by default migrations for all apps are made.

heliport-cli makemigrations your_app_name
heliport-cli migrate

Update the following settings in settings.py:

  • Add your_app_name to the HELIPORT_SYSTEM_APPS list

  • Add your modules to a phase in HELIPORT_GRAPH, or to HELIPORT_PROJECT_NAVBAR_ITEMS (the navbar in the top right) or HELIPORT_PROJECT_DROPDOWN_ITEMS (the drop-down menu in that navbar)

    • Refer to a module by its “module_id” (see “Export an Interface” below)

  • If your modules have any dependencies, add them to HELIPORT_DEPENDENCIES

    • Refer to a module by its “module_id”

    • A module is only available to be added to a project if all dependencies are already in the project

Add path("", include("heliport.your_app_name.urls")), to the URL patterns in heliport_config/urls.py. If your app exposes an API, also import the router in this file and register it in the api_routers list.

Export an Interface to HELIPORT

Create a file called “interface.py” in the folder of your app

  • from heliport.core.app_interaction import Module

  • Create one or more classes that inherit from Module with the following fields:

    • Property name: The name shown in project graph

    • Property module_id: The name used in settings.py to refer to this module

    • Property icon: The CSS classes for a Font Awesome icon. This icon is used when showing the app inside the navbar or the project drop-down menu.

    • Function get_url(project): The link to your initial view of the app for a project

    • Function is_configured(project): Return True if module should be shown in the project graph (e.g. check if the user created at least one object in your module for that project). Modules in the navbar or project drop-down menu are always shown.

  • To make objects in your app searchable with the global search add a function get_search_url() with no arguments returning the url to a view that renders a html div containing search results given a query parameter q=multi word search string

  • To make objects of your app appear in the metadata schema of a project add a function serialize_project(project) returning a dict that gets merged with the metadata returned by other apps

  • To register a view for creating a HELIPORT Project add a function get_project_create_urls() with no arguments, returning a dict mapping the name of your Project creation method (Arbitrary String) to a URL in your app where the user can create a new HELIPORT project

  • Add from . import interface to __init__.py of your app

Use HELIPORT infrastructure inside your app

  • Use the heliport base.html in your templates:

    • Begin your template with {% extends "core/base/base.html" %}

    • Implement

      {% block content %}
<!-- your content -->
{% endblock %}

    • If you have scripts use

      {% block script %}
<script>
  // your scripts
</script>
{% endblock %}

  • To create a custom model in models.py; addable to a project

    • from heliport.core.models import DigitalObject

    • Inherit from DigitalObject in your model

    • To register a handle for your model call its register_handle(request) method with the request of the current view (note that before calling the category property has to be set to a string, the object has to be saved)

  • To use HELIPORT views

    • from heliport.core.mixins import HeliportObjectMixin, HeliportProjectMixin

    • If you want a view for a HELIPORT project use HeliportProjectMixin, make sure your url parameter is called “project”

    • If you want a view for a model inheriting from DigitalObject, use HeliportObjectMixin

    • If you make HeliportObjectMixin or HeliportProjectMixin the first parent of your view class, authorization of the user to access the project is ensured

    • Both mixins include “project” in the context for rendering

  • To let HELIPORT generate a view and template for you

    • from heliport.core.views import HeliportObjectListView

    • Create a View inheriting from HeliportObjectListView

    • Set the model property to the class of the model that inherits from DigitalObject

    • Create two urls and specify them in your view:

      • Set the list_url attribute to a string that is valid when passed to djangos reverse() function with kwarg “project”

      • Set the update_url attribute to a string that is valid when passed to djangos reverse() function with kwargs “project” and “pk”

    • for more features:

      • Look for examples in other apps

      • Look at the implementation of HeliportObjectListView

  • To allow the user to invoke actions defined in other apps

    • Get a list of actions by calling obj.actions(user, project)

      • obj is a DigitalObject or a model inheriting from it. obj can also be something inheriting from GeneralDigitalObject.

      • user is the HeliportUser instance of the current user. You can get this from a Django request: request.user.heliportuser

      • project is the current Project

      • user and project can be omitted if not applicable. But in most cases a current user and project exists.

    • To generate a button for an action use the following attributes:

      • action.name - The text you can display on your button

      • action.link - The url where you can link to when someone clicks the button

    • See docs for digital_object_actions.py for more information, e.g. how to create you own actions.

    • To be able to retrieve rendered HTML partials from the API, heliport.core.renderers.HeliportPartialRenderer can be used. Check heliport.core.views.api.MaintenanceMessageView for an example.