From a56b00c32ffbecc1752ac28857d5fad6b93341b8 Mon Sep 17 00:00:00 2001 From: Sara Arjona Date: Mon, 18 Sep 2023 13:10:01 +0200 Subject: [PATCH] [docs] Migrate admin tools project --- data/migratedPages.yml | 3 ++ data/projects.json | 16 +++++++ docs/apis/plugintypes/index.md | 2 +- general/projects/api/admin-tools.md | 65 +++++++++++++++++++++++++++++ general/releases/2.2.md | 2 +- 5 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 general/projects/api/admin-tools.md diff --git a/data/migratedPages.yml b/data/migratedPages.yml index d750bc2fe6..58007ad4b6 100644 --- a/data/migratedPages.yml +++ b/data/migratedPages.yml @@ -40,6 +40,9 @@ Adding_a_web_service_to_a_plugin: Admin_settings: - filePath: "/docs/apis/subsystems/admin/index.md" slug: "/docs/apis/subsystems/admin/" +Admin_tools: +- filePath: "/general/projects/api/admin-tools.md" + slug: "/general/projects/api/admin-tools" Advanced_grading_API: - filePath: "/docs/apis/core/grading/index.md" slug: "/docs/apis/core/grading/" diff --git a/data/projects.json b/data/projects.json index 5c9047b665..065894f1c5 100644 --- a/data/projects.json +++ b/data/projects.json @@ -37,6 +37,22 @@ } ] }, + "api/admin-tools": { + "title": "Admin tools", + "status": "Complete", + "owners": [ + { + "name": "Petr Škoda", + "githubUsername": "škoďák" + } + ], + "issueLinks": [ + { + "link": "https://tracker.moodle.org/browse/MDL-29029", + "title": "MDL-29029" + } + ] + }, "api/amos": { "title": "Automated Manipulation of Strings (AMOS)", "status": "Complete", diff --git a/docs/apis/plugintypes/index.md b/docs/apis/plugintypes/index.md index 614ec4bb83..485851b3c4 100644 --- a/docs/apis/plugintypes/index.md +++ b/docs/apis/plugintypes/index.md @@ -79,7 +79,7 @@ The underscore character is not supported in activity modules for legacy reasons | [TinyMCE editor plugins](./tiny/legacy.md) | tinymce | /lib/editor/tinymce/plugins | Extra functionality for the TinyMCE text editor. | 2.4+ | | [Enrolment plugins](./enrol/index.md) | enrol | /enrol | Ways to control who is enrolled in courses | 2.0+ | | [Authentication plugins](https://docs.moodle.org/dev/Authentication_plugins) | auth | /auth | Allows connection to external sources of authentication | 2.0+ | -| [Admin tools](https://docs.moodle.org/dev/Admin_tools) | tool | /admin/tool | Provides utility scripts useful for various site administration and maintenance tasks | 2.2+ | +| [Admin tools](/general/projects/api/admin-tools) | tool | /admin/tool | Provides utility scripts useful for various site administration and maintenance tasks | 2.2+ | | [Log stores](./logstore/index.md) | logstore | /admin/tool/log/store | Event logs storage back-ends | 2.7+ | | [Availability conditions](./availability/index.md) | availability | /availability/condition | Conditions to restrict user access to activities and sections. | 2.7+ | | [Calendar types](https://docs.moodle.org/dev/Calendar_types) | calendartype | /calendar/type | Defines how dates are displayed throughout Moodle | 2.6+ | diff --git a/general/projects/api/admin-tools.md b/general/projects/api/admin-tools.md new file mode 100644 index 0000000000..bf29c890bd --- /dev/null +++ b/general/projects/api/admin-tools.md @@ -0,0 +1,65 @@ +--- +title: Admin tools +tags: + - Plugins + - Admin +--- + +import { ProjectSummary } from '@site/src'; +import { Since } from '@site/src/components'; + + + +
+ + + +Admin tools are advanced plugins that are intended especially for site administrators, they are accessible via the admin site administration tree menu. Ideally most of the functionality in `/admin/` directory should be moved to separate plugins in the future. + +## Previous problems + +Before 2.2, tools for administrators were created as admin reports (because we did not have better pluggable place), placed directly into `/admin/` or `/local/ directory`. + +- Confusing `/admin/report/` or `/local/ plugins` +- No way to disable or remove or add custom admin tools +- The official distribution should not include local plugins by definition (`/local/qeupgradehelper`). + +## Benefits + +- Major cleanup in `/admin/` +- No need to abuse admin reports +- Contrib admin tools can be distributed easier +- It is possible to remove or replace core admin tools (no hardcoded links) + +## Upgrades + +How to migrate existing admin reports: + +1. Move all files to new `/admin/tool/yourplugin/` location +1. Update all links to admin tools `/admin/report/` to `/admin/tool/` +1. Rename/add language pack file with at least `pluginname` string +1. Update all language strings (use `tool_yourplugin` instead of `report_yourplugin`. Use [AMOS](https://docs.moodle.org/dev/Languages/AMOS) hints in commit message +1. Update all capability names +1. Create `db/install.php` migration script. Delete old settings and capabilities (see converted plugins for examples) +1. Grep the plugin codebase and look for any remaining `coursereport` occurrences +1. Update CSS selectors + +## FAQs + +- **Is it necessary to migrate existing admin reports?**
+Yes. Old admin reports directory is completely ignored. + +- **Is it difficult to migrate admin reports?**
+No, it usually takes less than an hour to migrate and test one admin tool. + +- **What is the difference between report and admin tool?**
+Report is a view of live or historical data, it may also contain export feature, reports usually do not modify data. Admin tools are intended mostly for administrators, they usually work only in system context. + +- **What is the difference between admin tool and local plugin?**
+Local plugin is everything else, it may be intended for non-admin users. Examples of local plugins: event handlers, web service/function definitions, shared library hacks, new lang strings used in core hacks, etc. + +## See also + +- [General report plugins](https://docs.moodle.org/dev/General_report_plugins) diff --git a/general/releases/2.2.md b/general/releases/2.2.md index 2d2c3b0233..19d6053830 100644 --- a/general/releases/2.2.md +++ b/general/releases/2.2.md @@ -52,7 +52,7 @@ All security issues that were fixed in 2.1.x and 2.0.x were also fixed in 2.2. #### New plugin types - [report - report](https://docs.moodle.org/dev/General_report_plugins) -- [admin/tool - tool](https://docs.moodle.org/dev/Admin_tools) +- [admin/tool - tool](../projects/api/admin-tools.md) - [mod/quiz/accessrule - quizaccess](https://docs.moodle.org/dev/Quiz_access_rules) #### Plugin API changes