add ProjectModifyPluginMixin hook, update docs (#1090)

CHANGELOG.rst

@@ -29,6 +29,7 @@ Added
     - ``SODARAppSettingFormMixin`` form helper mixin (#1545)
     - Old owner "remove role" option in ``RoleAssignmentOwnerTransferForm`` (#836)
     - Project deletion (#1090)
+    - ``ProjectModifyPluginMixin.perform_project_delete()`` method (#1090)
 
 Changed
 -------

docs/source/app_projectroles_usage.rst

@@ -60,7 +60,7 @@ the general view of your site is split into the following elements:
 
 .. figure:: _static/app_projectroles/sodar_home.png
     :align: center
-    :scale: 50%
+    :scale: 55%
 
     Home view
 
@@ -102,7 +102,7 @@ app-specific controls is usually displayed.
 
 .. figure:: _static/app_projectroles/sodar_project_detail.png
     :align: center
-    :scale: 50%
+    :scale: 60%
 
     Project detail view
 
@@ -147,7 +147,7 @@ may be modified later.
 
 .. figure:: _static/app_projectroles/sodar_category_create.png
     :align: center
-    :scale: 50%
+    :scale: 60%
 
     Category/project creation form
 
@@ -176,7 +176,7 @@ target category or superuser status.
 
 .. figure:: _static/app_projectroles/sodar_project_update.png
     :align: center
-    :scale: 50%
+    :scale: 60%
 
     Category/project updating form
 
@@ -254,23 +254,56 @@ management command:
 Project Archiving
 -----------------
 
-From the project update menu, it is possible to archive a project. This will set
+In the project update view it is possible to archive a project. Clicking the
+:guilabel:`Archive` button and confirming this action in the next view will set
 data modification from project access to read-only. User roles can still be
 granted, but contributors can no longer edit data in project apps.
 
-The project update menu will still be available for owners and delegates for
+The project update view will still be available for owners and delegates for
 updating basic project metadata. Superusers will be able to edit project data
 regardless of its archiving status.
 
 To undo archiving, the project can be unarchived from the same button on top of
-the project update form.
+the project update view, now labeled :guilabel:`Unarchive`.
 
 .. figure:: _static/app_projectroles/sodar_archive.png
     :align: center
     :scale: 65%
 
     Archived project and unarchive button in project update view
 
+Project Deletion
+----------------
+
+The option to permanently delete a project is also available for owners and
+delegates in the project update view. The :guilabel:`Delete` button is found
+next to the project archiving button.
+
+Deletion is disabled for categories which have nested child categories or child
+projects. In such cases, the children must be individually deleted first. This
+is done deliberately to decrease the chance of accidental deletion of multiple
+projects.
+
+If remote access for a project has been granted on target sites, access needs to
+be revoked before the project can be deleted. Similarly, a project on a target
+site can only be deleted if its access has been revoked on the source site. For
+more information, see :ref:`app_projectroles_usage_remote`.
+
+.. figure:: _static/app_projectroles/sodar_project_delete.png
+    :align: center
+    :scale: 65%
+
+    Project deletion confirmation form
+
+Clicking the :guilabel:`Delete` button will take you to a form for confirming
+the deletion. You will have to write the host name of the SODAR Core site to
+confirm the action.
+
+.. danger::
+
+    Deletion will permanently wipe out all data associated with a category or
+    project. This operation can not be undone!
+
 
 Member Management
 =================
@@ -281,7 +314,7 @@ category (owner or delegate) or superuser status.
 
 .. figure:: _static/app_projectroles/sodar_role_list.png
     :align: center
-    :scale: 50%
+    :scale: 55%
 
     Project member list view
 
@@ -424,7 +457,7 @@ based site.
 
 .. figure:: _static/app_projectroles/sodar_remote_sites.png
     :align: center
-    :scale: 50%
+    :scale: 60%
 
     Remote site list in source mode
 

docs/source/dev_project_app.rst

@@ -878,6 +878,31 @@ additional actions to be taken.
     the project archive status, your app logic should handle it instead.
 
 
+.. _dev_project_app_delete:
+
+Project Deletion
+================
+
+If your apps only save data in Django models containing a ``Project`` foreign
+key with cascading deletion, no extra steps are needed to support project
+deletion.
+
+If your app contains project-specific data which is e.g. stored in an external
+system or in ways which will not be cascade-deleted along with the Django
+``Project`` model object, you need to implement project deletion in the project
+modify API. To do this, inherit ``ProjectModifyPluginMixin`` in your app's
+plugin and implement the ``perform_project_delete()`` method to clean up data.
+
+Project deletion can not be undone, so there is no revert method available for
+this action.
+
+.. note::
+
+    While categories are not expected to store data, the project deletion API
+    method is called for the deletion of both categories or projects, in case
+    speficic logic is needed for both project types.
+
+
 Removing a Project App
 ======================
 

docs/source/major_changes.rst

@@ -53,6 +53,14 @@ prohibit modifying all data on the site. Rules, logic and/or UI of your apps'
 views may have to be changed to support this functionality. For more
 information, see :ref:`dev_resources_read_only`.
 
+Project Deletion
+----------------
+
+This release enables the deletion of categories and projects. See the
+:ref:`project app development documentation <dev_project_app_delete>` for more
+information on how to support this feature in your apps.
+
+
 AppSettingAPI Definition Getter Return Data
 -------------------------------------------
 

projectroles/plugins.py

@@ -224,10 +224,7 @@ def revert_project_setting_update(
         """
         pass
 
-    def perform_project_archive(
-        self,
-        project,
-    ):
+    def perform_project_archive(self, project):
         """
         Perform additional actions to finalize project archiving or unarchiving.
         The state being applied can be derived from the project.archive attr.
@@ -236,10 +233,7 @@ def perform_project_archive(
         """
         pass
 
-    def revert_project_archive(
-        self,
-        project,
-    ):
+    def revert_project_archive(self, project):
         """
         Revert project archiving or unarchiving if errors have occurred in other
         apps. The state being originally set can be derived from the
@@ -249,6 +243,16 @@ def revert_project_archive(
         """
         pass
 
+    def perform_project_delete(self, project):
+        """
+        Perform additional actions to finalize project deletion.
+
+        NOTE: This operation can not be undone so there is no revert method.
+
+        :param project: Project object (Project)
+        """
+        pass
+
 
 # Plugin Points ----------------------------------------------------------------
 

projectroles/templates/projectroles/project_confirm_delete.html

@@ -29,7 +29,7 @@ <h3>Confirm Deletion of {% get_display_name object.type True %}</h3>
            name="delete_host_confirm"
            autocomplete="off"
            required="true"
-           placeholder="Type the host name of this server (e.g. &quot;site.example.org&quot;) to confirm deletion." />
+           placeholder="Type the host name of this server (e.g. &quot;site.example.com&quot;) to confirm deletion." />
     <div class="btn-group pull-right">
       <a role="button" class="btn btn-secondary"
           href="{% url 'projectroles:update' project=object.sodar_uuid %}">

projectroles/views.py

@@ -1557,6 +1557,11 @@ def handle_delete(self, project, request):
         :param request: HttpRequest object
         """
         app_alerts = get_backend_api('appalerts_backend')
+        # Call project modify API plugin
+        if getattr(settings, 'PROJECTROLES_ENABLE_MODIFY_API', False):
+            self.call_project_modify_api(
+                'perform_project_delete', None, [project]
+            )
         # Create timeline event
         self._create_timeline_event(project, request)
         # Create app alerts
@@ -1827,6 +1832,7 @@ class ProjectDeleteView(
     ProjectContextMixin,
     ProjectDeleteMixin,
     ProjectDeleteAccessMixin,
+    ProjectModifyPluginViewMixin,
     DeleteView,
 ):
     """Project deletion view"""