docs: markdown migration (#894)

Author: lukasvinclav

docs/actions/action-form-example.md

@@ -0,0 +1,109 @@
+---
+title: Action with form example
+description: Actions containing custom form example.
+order: 5
+---
+
+# Action with form example
+
+Below is an example of an action that will display a form after clicking on the action button on the detail object page.
+
+```python
+# admin.py
+
+from django import forms
+from django.contrib.auth.models import User
+from django.http import HttpRequest
+from django.shortcuts import render
+from django.urls import reverse_lazy
+from django.utils.translation import gettext_lazy as _
+
+from unfold.admin import ModelAdmin
+from unfold.decorators import action
+from unfold.widgets import UnfoldAdminTextInputWidget, UnfoldAdminSplitDateTimeWidget
+
+
+class SomeForm(forms.Form):
+    # It is important to set a widget coming from Unfold
+    date_start = forms.SplitDateTimeField(label=_("Start"), widget=UnfoldAdminSplitDateTimeWidget)
+    date_end = forms.SplitDateTimeField(label=_("End"), widget=UnfoldAdminSplitDateTimeWidget)
+    note = forms.CharField(label=_("Note"), widget=UnfoldAdminTextInputWidget)
+
+    # Loads date widget required JS files
+    class Media:
+        js = [
+            "admin/js/vendor/jquery/jquery.js",
+            "admin/js/jquery.init.js",
+            "admin/js/calendar.js",
+            "admin/js/admin/DateTimeShortcuts.js",
+            "admin/js/core.js",
+        ]
+
+
+@register(User)
+class UserAdmin(ModelAdmin):
+    actions_detail = ["change_detail_action"]
+
+    @action(description=_("Change detail action"), url_path="change-detail-action")
+    def change_detail_action(self, request: HttpRequest, object_id: int) -> str:
+        # Check if object already exists, otherwise returs 404
+        obj = get_object_or_404(User, pk=object_id)
+        form = SomeForm(request.POST or None)
+
+        if request.method == "POST" and form.is_valid():
+            # Process form data
+            # form.cleaned_data["note"]
+            # form.cleaned_data["date_from"]
+            # form.cleaned_data["date_to"]
+
+            messages.success(request, _("Change detail action has been successful."))
+
+            return redirect(
+                reverse_lazy("admin:app_model_change", args=[object_id])
+            )
+
+        return render(
+            request,
+            "some/action.html",
+            {
+                "form": form,
+                "object": obj,
+                "title": _("Change detail action for {}").format(obj),
+                **self.admin_site.each_context(request),
+            },
+        )
+```
+
+Template displaying the form. Please note that breadcrumbs are empty in this case but if you want, you can configure your own breadcrumbs path.
+
+```html
+{% extends "admin/base_site.html" %}
+
+{% load i18n unfold %}
+
+{% block breadcrumbs %}{% endblock %}
+
+{% block extrahead %}
+    {{ block.super }}
+    <script src="{% url 'admin:jsi18n' %}"></script>
+    {{ form.media }}
+{% endblock %}
+
+{% block content %}
+    <form action="" method="post" novalidate>
+        <div class="aligned border border-gray-200 mb-8 rounded-md pt-3 px-3 shadow-sm dark:border-gray-800">
+            {% csrf_token %}
+
+            {% for field in form %}
+                {% include "unfold/helpers/field.html" with field=field %}
+            {% endfor %}
+        </div>
+
+        <div class="flex justify-end">
+            {% component "unfold/components/button.html" with submit=1 %}
+                {% trans "Submit form" %}
+            {% endcomponent %}
+        </div>
+    </form>
+{% endblock %}
+```

docs/actions/changeform-submitline.md

@@ -0,0 +1,40 @@
+---
+title: Changeform submitline actions
+description: Changeform submitline actions for detail view.
+order: 4
+---
+
+# Changeform submitline actions
+
+Submit row actions work a bit differently when compared to other custom Unfold actions. These actions first invoke form save (same as if you hit `Save` button) and then lets you perform additional logic on already saved instance.
+
+```python
+# admin.py
+
+from django.contrib.admin import register
+from django.contrib.auth.models import User
+from django.utils.translation import gettext_lazy as _
+from django.http import HttpRequest
+from unfold.admin import ModelAdmin
+from unfold.decorators import action
+
+
+@register(User)
+class UserAdmin(ModelAdmin):
+    actions_submit_line = ["changeform_submitline_action"]
+
+    @action(
+        description=_("Changeform submitline action"),
+        permissions=["changeform_submitline_action"]
+    )
+    def changeform_submitline_action(self, request: HttpRequest, obj: User):
+        """
+        If instance is modified in any way, it also needs to be saved, since this handler is invoked after instance is saved.
+        """
+
+        obj.is_active = True
+        obj.save()
+
+    def has_changeform_submitline_action_permission(self, request: HttpRequest, object_id: Union[str, int]):
+        pass
+```

docs/actions/changeform.md

@@ -0,0 +1,43 @@
+---
+title: Changeform actions
+description: Changeform actions for detail view.
+order: 3
+---
+
+# Changeform actions
+
+```python
+# admin.py
+
+from django.contrib.admin import register
+from django.contrib.auth.models import User
+from django.shortcuts import redirect
+from django.urls import reverse_lazy
+from django.utils.translation import gettext_lazy as _
+from django.http import HttpRequest
+from unfold.admin import ModelAdmin
+from unfold.decorators import action
+
+
+@register(User)
+class UserAdmin(ModelAdmin):
+    actions_detail = ["changeform_action"]
+
+    @action(
+        description=_("Changeform action"),
+        url_path="changeform-action",
+        attrs={"target": "_blank"},
+        permissions=["changeform_action"]
+    )
+    def changeform_action(self, request: HttpRequest, object_id: int):
+        user = User.objects.get(pk=object_id)
+        user.block()
+
+        return redirect(
+            reverse_lazy("admin:users_user_change", args=(object_id,))
+        )
+
+
+    def has_changeform_action_permission(self, request: HttpRequest, object_id: Union[str, int]):
+        pass
+```

docs/actions/changelist-row.md

@@ -0,0 +1,41 @@
+---
+title: Changelist row actions
+description: Changelist row actions for list view.
+order: 2
+---
+
+# Changelist row actions
+
+These actions will appear on each row on the changelist page as a dropdown button containing all custom row actions.
+
+```python
+# admin.py
+
+from django.contrib.admin import register
+from django.contrib.auth.models import User
+from django.shortcuts import redirect
+from django.urls import reverse_lazy
+from django.utils.translation import gettext_lazy as _
+from django.http import HttpRequest
+from unfold.admin import ModelAdmin
+from unfold.decorators import action
+
+
+@register(User)
+class UserAdmin(ModelAdmin):
+    actions_row = ["changelist_row_action"]
+
+    @action(
+        description=_("Changelist row action"),
+        permissions=["changelist_row_action"],
+        url_path="changelist-row-action",
+        attrs={"target": "_blank"}
+    )
+    def changelist_row_action(self, request: HttpRequest, object_id: int):
+        return redirect(
+          reverse_lazy("admin:users_user_changelist")
+        )
+
+    def has_changelist_row_action_permission(self, request: HttpRequest):
+        pass
+```

docs/actions/changelist.md

@@ -0,0 +1,36 @@
+---
+title: Changelist actions
+description: Changelist actions for list view.
+order: 1
+---
+
+# Changelist actions
+
+These actions will appear at the top of the changelist page as buttons. Please not that these actions are not displayed in the actions dropdown which is provided by default in Django. Changelist action will not reciver any queryset or object ids, because it is meant to be used for general actions for given model.
+
+```python
+# admin.py
+
+from django.contrib.admin import register
+from django.contrib.auth.models import User
+from django.shortcuts import redirect
+from django.urls import reverse_lazy
+from django.utils.translation import gettext_lazy as _
+from django.http import HttpRequest
+from unfold.admin import ModelAdmin
+from unfold.decorators import action
+
+
+@register(User)
+class UserAdmin(ModelAdmin):
+    actions_list = ["changelist_action"]
+
+    @action(description=_("Changelist action"), url_path="changelist-action")
+    def changelist_action(self, request: HttpRequest, permissions=["changelist_action"]):
+        return redirect(
+          reverse_lazy("admin:users_user_changelist")
+        )
+
+    def has_changelist_action_permission(self, request: HttpRequest):
+        pass
+```

docs/actions/index.md

@@ -0,0 +1,5 @@
+---
+title: Actions
+order: 4
+description: Introduction to Unfold actions
+---

docs/actions/introduction.md

@@ -0,0 +1,47 @@
+---
+title: Introduction to actions
+order: 0
+description: Run custom admin actions from different places.
+---
+
+# Actions
+
+It is highly recommended to read the base [Django actions documentation](https://docs.djangoproject.com/en/5.1/ref/contrib/admin/actions/) before reading this section, since Unfold actions are derived from Django actions.
+
+```python
+# admin.py
+
+from django.auth.models import User
+from django.contrib import admin
+from django.db.models import QuerySet
+from django.http import HttpRequest
+from unfold.admin import ModelAdmin
+from unfold.decorators import action  # Import @action decorator from Unfold
+
+@admin.register(User)
+class UserAdmin(ModelAdmin):
+    actions_list = ["custom_action"]
+
+    @action(description="Custom action")
+    def custom_action(self, request: HttpRequest, queryset: QuerySet):
+        pass
+```
+
+## Actions overview
+
+Besides traditional actions selected from dropdown, Unfold supports several other types of actions. Following table gives overview of all available actions together with their recommended usage:
+
+| Type           | Appearance                     | Usage                                                                 |
+| -------------- | ------------------------------ | ----------------------------------------------------------------------|
+| Global         | Changelist - top               | General actions for all instances in listing                          |
+| Row            | Changelist - each row          | Action for one specific instance, executable from listing             |
+| Detail         | Changeform - top               | Action for one specific instance, executable from detail              |
+| Submit line    | Changeform - submit line       | Action performed during form submit (instance save)                   |
+
+## For global, row and detail action
+
+All these actions are based on custom URLs generated for each of them. Handler function for these views is basically function based view.
+
+For actions without intermediate steps, you can write all the logic inside handler directly. Request and object ID are both passed to these action handler functions, so you are free to fetch the instance from database and perform any operations with it. In the end, it is recommended to return redirect back to either detail or listing based on where the action was triggered from.
+
+For actions with intermediate steps, it is recommended to use handler function only to redirect to custom URL with custom view. This view can be extended from base Unfold view, to have unified experience.