Select solution

dev-docs/plugins/hooks/check-clear-thread-solution-permission-hook.md

@@ -0,0 +1,102 @@
+# `check_clear_thread_solution_permission_hook`
+
+This hook wraps the standard Misago function used to check whether the user has permission to clear the thread’s selected solution. Raises `PermissionDenied` with an error message if they do not.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import check_clear_thread_solution_permission_hook
+```
+
+
+## Filter
+
+```python
+def custom_check_clear_thread_solution_permission_filter(
+    action: CheckClearThreadSolutionPermissionHookAction,
+    permissions: 'UserPermissionsProxy',
+    thread: Thread,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: CheckClearThreadSolutionPermissionHookAction`
+
+Next function registered in this hook, either a custom function or Misago's standard one.
+
+See the [action](#action) section for details.
+
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+The thread to check permissions for.
+
+
+## Action
+
+```python
+def check_clear_thread_solution_permission_action(
+    permissions: 'UserPermissionsProxy', thread: Thread
+) -> None:
+    ...
+```
+
+Misago function used to check whether the user has permission to clear the thread’s selected solution. Raises `PermissionDenied` with an error message if they do not.
+
+
+### Arguments
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+The thread to check permissions for.
+
+
+## Example
+
+The code below implements a custom filter function that blocks a user from clearing a thread’s solution unless they were the one who selected it.
+
+```python
+from django.core.exceptions import PermissionDenied
+from django.utils.translation import pgettext
+from misago.permissions.hooks import check_clear_thread_solution_permission_hook
+from misago.permissions.proxy import UserPermissionsProxy
+from misago.threads.models import Thread
+
+@check_clear_thread_solution_permission_hook.append_filter
+def check_clear_thread_solution_permission(
+    action,
+    permissions: UserPermissionsProxy,
+    thread: Thread,
+) -> None:
+    # Run standard permission checks
+    action(permissions, thread)
+
+    if (
+        not thread.solution_selected_by_id
+        or thread.solution_selected_by_id != permissions.user.id
+    ):
+        raise PermissionDenied(
+            pgettext(
+                "solution permission error",
+                "You can't clear this thread's solution."
+            )
+        )
+```

dev-docs/plugins/hooks/check-select-thread-solution-permission-hook.md

@@ -0,0 +1,97 @@
+# `check_select_thread_solution_permission_hook`
+
+This hook wraps a standard Misago function used to check whether the user has permission to select a post as the thread’s solution. Raises `PermissionDenied` with an error message if they don't.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import check_select_thread_solution_permission_hook
+```
+
+
+## Filter
+
+```python
+def custom_check_select_thread_solution_permission_filter(
+    action: CheckSelectThreadSolutionPermissionHookAction,
+    permissions: 'UserPermissionsProxy',
+    post: Post,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: CheckSelectThreadSolutionPermissionHookAction`
+
+Next function registered in this hook, either a custom function or Misago's standard one.
+
+See the [action](#action) section for details.
+
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `post: Post`
+
+The post to check permissions for.
+
+
+## Action
+
+```python
+def check_select_thread_solution_permission_action(permissions: 'UserPermissionsProxy', post: Post) -> None:
+    ...
+```
+
+Misago function used to check whether the user has permission to select a post as the thread’s solution. Raises `PermissionDenied` with an error message if they don't.
+
+
+### Arguments
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `post: Post`
+
+The post to check permissions for.
+
+
+## Example
+
+The code below implements a custom filter function that blocks a user from selecting a post as a solution if it was posted by a shadow-banned user.
+
+```python
+from django.core.exceptions import PermissionDenied
+from django.utils.translation import pgettext
+from misago.permissions.hooks import check_select_thread_solution_permission_hook
+from misago.permissions.proxy import UserPermissionsProxy
+from misago.threads.models import Post
+
+@check_select_thread_solution_permission_hook.append_filter
+def check_select_thread_solution_permission(
+    action,
+    permissions: UserPermissionsProxy,
+    post: Post,
+) -> None:
+    # Run standard permission checks
+    action(permissions, post)
+
+    if post.poster and post.poster.plugin_data.get("shadow_banned"):
+        raise PermissionDenied(
+            pgettext(
+                "solution permission error",
+                "This post can’t be selected as the thread’s solution."
+            )
+        )
+```

dev-docs/plugins/hooks/clear-thread-solution-hook.md

@@ -0,0 +1,116 @@
+# `clear_thread_solution_hook`
+
+This hook allows plugins to replace or extend the logic used to clear the thread’s solution.
+
+
+## Location
+
+This hook can be imported from `misago.solutions.hooks`:
+
+```python
+from misago.solutions.hooks import clear_thread_solution_hook
+```
+
+
+## Filter
+
+```python
+def custom_clear_thread_solution_filter(
+    action: ClearThreadSolutionHookAction,
+    thread: Thread,
+    commit: bool=True,
+    request: HttpRequest | None=None,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: ClearThreadSolutionHookAction`
+
+Next function registered in this hook, either a custom function or Misago's standard one.
+
+See the [action](#action) section for details.
+
+
+#### `thread: Thread`
+
+The thread to update.
+
+
+#### `commit: bool`
+
+Whether the updated thread instance should be saved to the database.
+
+Defaults to `True`.
+
+
+#### `request: HttpRequest | None`
+
+The request object, or `None` if not provided.
+
+
+## Action
+
+```python
+def clear_thread_solution_action(
+    thread: Thread, commit: bool=True, request: HttpRequest | None=None
+) -> None:
+    ...
+```
+
+Misago function used to clear the thread’s solution.
+
+
+### Arguments
+
+#### `thread: Thread`
+
+The thread to update.
+
+
+#### `commit: bool`
+
+Whether the updated thread instance should be saved to the database.
+
+Defaults to `True`.
+
+
+#### `request: HttpRequest | None`
+
+The request object, or `None` if not provided.
+
+
+## Example
+
+Record the user who cleared the solution:
+
+```python
+from django.http import HttpRequest
+from misago.solutions.hooks import clear_thread_solution_hook
+from misago.threads.models import Thread
+
+
+@clear_thread_solution_hook.append_filter
+def record_cleared_solution_user(
+    action,
+    thread: Thread,
+    commit: bool = True,
+    request: HttpRequest | None = None,
+) -> None:
+    action(thread, False, request)
+
+    if request:
+        thread.plugin_data.update(
+            {
+                "solution_cleared_user_id": request.user.id,
+                "solution_cleared_user_ip": request.user_ip,
+            }
+        )
+
+    if commit:
+        thread.save()
+```

dev-docs/plugins/hooks/reference.md

@@ -15,6 +15,7 @@ Hooks instances are importable from the following Python modules:
 - [`misago.polls.hooks`](#misago-polls-hooks)
 - [`misago.posting.hooks`](#misago-posting-hooks)
 - [`misago.privatethreads.hooks`](#misago-privatethreads-hooks)
+- [`misago.solutions.hooks`](#misago-solutions-hooks)
 - [`misago.threads.hooks`](#misago-threads-hooks)
 - [`misago.threadupdates.hooks`](#misago-threadupdates-hooks)
 - [`misago.users.hooks`](#misago-users-hooks)
@@ -115,6 +116,7 @@ Hooks instances are importable from the following Python modules:
 - [`check_access_thread_permission_hook`](./check-access-thread-permission-hook.md)
 - [`check_browse_category_permission_hook`](./check-browse-category-permission-hook.md)
 - [`check_change_private_thread_owner_permission_hook`](./check-change-private-thread-owner-permission-hook.md)
+- [`check_clear_thread_solution_permission_hook`](./check-clear-thread-solution-permission-hook.md)
 - [`check_close_thread_poll_permission_hook`](./check-close-thread-poll-permission-hook.md)
 - [`check_delete_attachment_permission_hook`](./check-delete-attachment-permission-hook.md)
 - [`check_delete_post_edit_permission_hook`](./check-delete-post-edit-permission-hook.md)
@@ -143,6 +145,7 @@ Hooks instances are importable from the following Python modules:
 - [`check_see_private_thread_post_permission_hook`](./check-see-private-thread-post-permission-hook.md)
 - [`check_see_thread_permission_hook`](./check-see-thread-permission-hook.md)
 - [`check_see_thread_post_permission_hook`](./check-see-thread-post-permission-hook.md)
+- [`check_select_thread_solution_permission_hook`](./check-select-thread-solution-permission-hook.md)
 - [`check_start_poll_permission_hook`](./check-start-poll-permission-hook.md)
 - [`check_start_private_threads_permission_hook`](./check-start-private-threads-permission-hook.md)
 - [`check_start_thread_permission_hook`](./check-start-thread-permission-hook.md)
@@ -241,6 +244,14 @@ Hooks instances are importable from the following Python modules:
 - [`validate_new_private_thread_owner_hook`](./validate-new-private-thread-owner-hook.md)
 
 
+## `misago.solutions.hooks`
+
+`misago.solutions.hooks` defines the following hooks:
+
+- [`clear_thread_solution_hook`](./clear-thread-solution-hook.md)
+- [`set_thread_solution_hook`](./set-thread-solution-hook.md)
+
+
 ## `misago.threads.hooks`
 
 `misago.threads.hooks` defines the following hooks: