[](https://github.com/mutantsan/ckanext-admin-panel/actions)
# ckanext-admin-panel
Next generation admin interface for CKAN.
## Content
- [ckanext-admin-panel](#ckanext-admin-panel)
- [Content](#content)
- [TODO](#todo)
- [Registering config sections](#registering-config-sections)
- [Requirements](#requirements)
- [Installation](#installation)
- [Config settings](#config-settings)
- [Enabling logging](#enabling-logging)
- [Enable CRON logging](#enable-cron-logging)
- [User CRON manager](#user-cron-manager)
- [Scheduling](#scheduling)
- [Create cron job](#create-cron-job)
- [Developer installation](#developer-installation)
- [Tests](#tests)
- [License](#license)
## TODO
This extension is under development, so there are many things to do:
- CKAN forms:
- What do we want to do, if we are editing an entity from admin panel? Use default form or replace it with an admin version?
- Users:
- Add `User edit` page
- Recent log messages:
- We have some types, that we don't want to include in list. E.g xloader resources. Research what is better to do with them.
- Rework the pagination approach, because the current naive one will work very slow on big amount of data
- Rewrite `user_list` action. Currently it's just a copy of contrib one with one small change. Maybe it's a good idea to write
our own versatile version.
- Think about configuration section pages. Do we need a separate page for a section?
- Work on `Extensions` page. What do we want: replace `status_show`. This page should be more informative. Show here what extensions we are using with the respective versions. For now we don't have a standartized mechanism to retrieve versions from extensions, think about it.
- Work on `Available updates?` page. Show user if he could upgrade an extension or CKAN to a new version.
- Work on `Appearance` page. TODO
- Work on `Help` page. TODO
## Registering config sections
We utilize the `ISignal` interface for gathering configuration sections. For instance, to register a configuration section from your extension:
```py
from __future__ import annotations
import ckan.types as types
import ckan.plugins as p
import ckan.plugins.toolkit as tk
import ckanext.ap_main.types as ap_types
class ExamplePlugin(p.SingletonPlugin):
...
p.implements(p.ISignal)
...
# ISignal
def get_signal_subscriptions(self) -> types.SignalMapping:
return {
tk.signals.ckanext.signal("ap_main:collect_config_sections"): [
self.collect_config_sections_subs
],
}
@staticmethod
def collect_config_sections_subs(sender: None):
return ap_types.SectionConfig(
name="Example plugin configuration",
configs=[
ap_types.ConfigurationItem(
name="Configuration",
blueprint="example_plugin.config,
info="Basic configuration options",
),
],
)
```
The structure of the section is outlined in the `SectionConfig` and `ConfigurationItem` [here](ckanext/ap_main/types.py).
You can import these structures and use them to assemble the section or just return a dictionary mirroring the same structure. This method works the same as described above:
```py
@staticmethod
def collect_config_sections_subs(sender: None):
return {
"name": "Example plugin configuration",
"configs": [
{
"name": "Configuration",
"blueprint": "example_plugin.config",
"info": "Basic configuration options",
},
],
}
```
If the section with the specified `name` has already been registered by another plugin, the configuration options will be included into it.
The structure of `ConfigurationItem` is as follows:
- `name` - defines the name of the configuration section link
- `blueprint` - indicates the configuration page blueprint
- `info` (optional, default: `No description`) - provides a description for the configuration link
## Requirements
Compatibility with core CKAN versions:
| CKAN version | Compatible? |
|--------------|-------------|
| 2.9 | no |
| 2.10 | yes |
| 2.11 | yes |
## Installation
To install ckanext-admin-panel:
1. Activate your CKAN virtual environment, for example:
. /usr/lib/ckan/default/bin/activate
2. Clone the source and install it on the virtualenv
git clone https://github.com/mutantsan/ckanext-admin-panel.git
cd ckanext-admin-panel
pip install -e .
pip install -r requirements.txt
3. Add `admin_panel admin_panel_cron` to the `ckan.plugins` setting in your CKAN
config file (by default the config file is located at
`/etc/ckan/default/ckan.ini`).
4. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:
sudo service apache2 reload
## Config settings
None at present
## Enabling logging
To store log messages in a database, you must enable the `admin_panel_log` extension, initialize the database log table,
and create a handler in your 'ckan.ini' file.
1. Add `admin_panel_log` to the `ckan.plugins` setting in your CKAN config file.
2. Initialize all missing tables with: `ckan db pending-migrations --apply`
3. To register a handler, you must specify it in your CKAN configuration file. Due to some CKAN specifics, the logger needs to know the database URI to initialize itself. Provide it with the `kwargs` option.
```
[handler_dbHandler]
class = ckanext.ap_log.log_handlers.DatabaseHandler
formatter = generic
level = NOTSET
kwargs={"db_uri": "postgresql://ckan_default:pass@localhost/master"}
```
4. The logging handler must be also included in `[handlers]` section.
```
[handlers]
keys = console, dbHandler
```
5. The last thing you need to do is to add our handler to a logger you need. For example, if you want to log only `ckan` logs, do this:
```
[logger_ckan]
level = INFO
handlers = console, dbHandler
```
## Enable CRON logging
Register a separate logger for a cron job logging. The DB handler must be initiated first if you want to have an access to logs via UI. Otherwise, you will be able to see logs only in CKAN logs files.
1. Define a logger
```
[logger_ap_cron]
level = DEBUG
handlers = console, dbHandler
qualname = ap_cron
propagate = 0
```
2. Use the newly created logger by specifiyng it in `loggers` section.
```
[loggers]
keys = root, ckan, ckanext, werkzeug, flask_app, ap_cron
```
## User CRON manager
### Scheduling
Each cron job can be manually triggered from the cron manager page. However, it's essential to schedule a single command with crontab to automatically trigger all jobs created within CKAN. For example:
*/10 * * * * /usr/lib/ckan/default/bin/ckan -c /etc/ckan/default/production.ini ap-cron trigger-jobs
This command checks all the jobs every 10 minutes to determine if they should be run again. Without scheduling this command, you can manually initiate a specific job through the user interface by clicking the `Run` button. Alternatively, you can execute all scheduled jobs by clicking the `Run active jobs` button.
### Create cron job
To create a cron job, navigate to the cron manager page and click the `Add cron job` button.
Each job must include the following components:
- Name: A label used primarily in the UI for identification.
- Actions: One or more CKAN actions that will be executed.
- Data: JSON-formatted data that provides arguments to the initial action.
- Job Timeout: The maximum duration allowed for a job to run before it is deemed to have failed.
- Schedule: A cron expression that specifies the frequency and timing of the job execution.
It is important to note that console commands are not permitted within cron jobs for security reasons. Instead, only CKAN actions can be executed. You can chain multiple actions together; each subsequent action will receive the result of the previous one as its arguments.
## Developer installation
To install ckanext-admin-panel for development, activate your CKAN virtualenv and
do:
git clone https://github.com/mutantsan/ckanext-admin-panel.git
cd ckanext-admin-panel
python setup.py develop
pip install -r dev-requirements.txt
## Tests
To run the tests, do:
pytest --ckan-ini=test.ini
## License
[AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/mutantsan/ckanext-admin-panel",
"name": "ckanext-admin-panel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "CKAN",
"author": "Oleksandr Cherniavskyi",
"author_email": "mutantsan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/fc/3fef1ebe427550f8303f3d886012c5577d046e6508bcc791bdee9e07bb32/ckanext_admin_panel-1.0.12.tar.gz",
"platform": null,
"description": "\n[](https://github.com/mutantsan/ckanext-admin-panel/actions)\n\n# ckanext-admin-panel\n\nNext generation admin interface for CKAN.\n\n## Content\n\n- [ckanext-admin-panel](#ckanext-admin-panel)\n - [Content](#content)\n - [TODO](#todo)\n - [Registering config sections](#registering-config-sections)\n - [Requirements](#requirements)\n - [Installation](#installation)\n - [Config settings](#config-settings)\n - [Enabling logging](#enabling-logging)\n - [Enable CRON logging](#enable-cron-logging)\n - [User CRON manager](#user-cron-manager)\n - [Scheduling](#scheduling)\n - [Create cron job](#create-cron-job)\n - [Developer installation](#developer-installation)\n - [Tests](#tests)\n - [License](#license)\n\n## TODO\nThis extension is under development, so there are many things to do:\n\n- CKAN forms:\n\t - What do we want to do, if we are editing an entity from admin panel? Use default form or replace it with an admin version?\n- Users:\n\t - Add `User edit` page\n- Recent log messages:\n\t - We have some types, that we don't want to include in list. E.g xloader resources. Research what is better to do with them.\n\t - Rework the pagination approach, because the current naive one will work very slow on big amount of data\n- Rewrite `user_list` action. Currently it's just a copy of contrib one with one small change. Maybe it's a good idea to write\n our own versatile version.\n- Think about configuration section pages. Do we need a separate page for a section?\n- Work on `Extensions` page. What do we want: replace `status_show`. This page should be more informative. Show here what extensions we are using with the respective versions. For now we don't have a standartized mechanism to retrieve versions from extensions, think about it.\n- Work on `Available updates?` page. Show user if he could upgrade an extension or CKAN to a new version.\n- Work on `Appearance` page. TODO\n- Work on `Help` page. TODO\n\n\n## Registering config sections\n\nWe utilize the `ISignal` interface for gathering configuration sections. For instance, to register a configuration section from your extension:\n\n```py\nfrom __future__ import annotations\n\nimport ckan.types as types\nimport ckan.plugins as p\nimport ckan.plugins.toolkit as tk\n\nimport ckanext.ap_main.types as ap_types\n\n\nclass ExamplePlugin(p.SingletonPlugin):\n ...\n p.implements(p.ISignal)\n\n ...\n\n # ISignal\n\n def get_signal_subscriptions(self) -> types.SignalMapping:\n return {\n tk.signals.ckanext.signal(\"ap_main:collect_config_sections\"): [\n self.collect_config_sections_subs\n ],\n }\n\n @staticmethod\n def collect_config_sections_subs(sender: None):\n return ap_types.SectionConfig(\n name=\"Example plugin configuration\",\n configs=[\n ap_types.ConfigurationItem(\n name=\"Configuration\",\n blueprint=\"example_plugin.config,\n info=\"Basic configuration options\",\n ),\n ],\n )\n```\n\nThe structure of the section is outlined in the `SectionConfig` and `ConfigurationItem` [here](ckanext/ap_main/types.py).\nYou can import these structures and use them to assemble the section or just return a dictionary mirroring the same structure. This method works the same as described above:\n\n```py\n@staticmethod\ndef collect_config_sections_subs(sender: None):\n return {\n \"name\": \"Example plugin configuration\",\n \"configs\": [\n {\n \"name\": \"Configuration\",\n \"blueprint\": \"example_plugin.config\",\n \"info\": \"Basic configuration options\",\n },\n ],\n }\n```\n\nIf the section with the specified `name` has already been registered by another plugin, the configuration options will be included into it.\n\nThe structure of `ConfigurationItem` is as follows:\n- `name` - defines the name of the configuration section link\n- `blueprint` - indicates the configuration page blueprint\n- `info` (optional, default: `No description`) - provides a description for the configuration link\n\n\n## Requirements\n\nCompatibility with core CKAN versions:\n\n| CKAN version | Compatible? |\n|--------------|-------------|\n| 2.9 | no |\n| 2.10 | yes |\n| 2.11 | yes |\n\n\n\n## Installation\n\nTo install ckanext-admin-panel:\n\n1. Activate your CKAN virtual environment, for example:\n\n . /usr/lib/ckan/default/bin/activate\n\n2. Clone the source and install it on the virtualenv\n\n git clone https://github.com/mutantsan/ckanext-admin-panel.git\n cd ckanext-admin-panel\n pip install -e .\n\tpip install -r requirements.txt\n\n3. Add `admin_panel admin_panel_cron` to the `ckan.plugins` setting in your CKAN\n config file (by default the config file is located at\n `/etc/ckan/default/ckan.ini`).\n\n4. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:\n\n sudo service apache2 reload\n\n\n## Config settings\n\nNone at present\n\n## Enabling logging\nTo store log messages in a database, you must enable the `admin_panel_log` extension, initialize the database log table,\nand create a handler in your 'ckan.ini' file.\n\n 1. Add `admin_panel_log` to the `ckan.plugins` setting in your CKAN config file.\n 2. Initialize all missing tables with: `ckan db pending-migrations --apply`\n 3. To register a handler, you must specify it in your CKAN configuration file. Due to some CKAN specifics, the logger needs to know the database URI to initialize itself. Provide it with the `kwargs` option.\n\t```\n [handler_dbHandler]\n class = ckanext.ap_log.log_handlers.DatabaseHandler\n formatter = generic\n level = NOTSET\n kwargs={\"db_uri\": \"postgresql://ckan_default:pass@localhost/master\"}\n ```\n\n 4. The logging handler must be also included in `[handlers]` section.\n\t```\n [handlers]\n keys = console, dbHandler\n\t```\n 5. The last thing you need to do is to add our handler to a logger you need. For example, if you want to log only `ckan` logs, do this:\n\t```\n [logger_ckan]\n\tlevel = INFO\n\thandlers = console, dbHandler\n\t```\n\n## Enable CRON logging\nRegister a separate logger for a cron job logging. The DB handler must be initiated first if you want to have an access to logs via UI. Otherwise, you will be able to see logs only in CKAN logs files.\n\n 1. Define a logger\n\t```\n [logger_ap_cron]\n\tlevel = DEBUG\n\thandlers = console, dbHandler\n\tqualname = ap_cron\n\tpropagate = 0\n\t```\n2. Use the newly created logger by specifiyng it in `loggers` section.\n\t```\n [loggers]\n\tkeys = root, ckan, ckanext, werkzeug, flask_app, ap_cron\n\t```\n\n## User CRON manager\n\n### Scheduling\nEach cron job can be manually triggered from the cron manager page. However, it's essential to schedule a single command with crontab to automatically trigger all jobs created within CKAN. For example:\n\n */10 * * * * /usr/lib/ckan/default/bin/ckan -c /etc/ckan/default/production.ini ap-cron trigger-jobs\n\nThis command checks all the jobs every 10 minutes to determine if they should be run again. Without scheduling this command, you can manually initiate a specific job through the user interface by clicking the `Run` button. Alternatively, you can execute all scheduled jobs by clicking the `Run active jobs` button.\n\n### Create cron job\nTo create a cron job, navigate to the cron manager page and click the `Add cron job` button. \n\nEach job must include the following components:\n\n- Name: A label used primarily in the UI for identification.\n- Actions: One or more CKAN actions that will be executed.\n- Data: JSON-formatted data that provides arguments to the initial action.\n- Job Timeout: The maximum duration allowed for a job to run before it is deemed to have failed.\n- Schedule: A cron expression that specifies the frequency and timing of the job execution.\n\nIt is important to note that console commands are not permitted within cron jobs for security reasons. Instead, only CKAN actions can be executed. You can chain multiple actions together; each subsequent action will receive the result of the previous one as its arguments.\n\n## Developer installation\n\nTo install ckanext-admin-panel for development, activate your CKAN virtualenv and\ndo:\n\n git clone https://github.com/mutantsan/ckanext-admin-panel.git\n cd ckanext-admin-panel\n python setup.py develop\n pip install -r dev-requirements.txt\n\n\n## Tests\n\nTo run the tests, do:\n\n pytest --ckan-ini=test.ini\n\n\n## License\n\n[AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html)\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "Custom admin panel for CKAN to expand default functionality",
"version": "1.0.12",
"project_urls": {
"Homepage": "https://github.com/mutantsan/ckanext-admin-panel"
},
"split_keywords": [
"ckan"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c86d2cab7450f9eb68cc50b541b45d0465aeb452aaa2fc3d260c8935e69c84e",
"md5": "bdcffa40eb846729192ef0ddfbb7ad51",
"sha256": "7cc924c0d304ccdd1fbf26a92a91db7316bf550bd4965eec00987f9d7b3b629e"
},
"downloads": -1,
"filename": "ckanext_admin_panel-1.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdcffa40eb846729192ef0ddfbb7ad51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75953,
"upload_time": "2024-05-02T11:41:57",
"upload_time_iso_8601": "2024-05-02T11:41:57.816083Z",
"url": "https://files.pythonhosted.org/packages/7c/86/d2cab7450f9eb68cc50b541b45d0465aeb452aaa2fc3d260c8935e69c84e/ckanext_admin_panel-1.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8bfc3fef1ebe427550f8303f3d886012c5577d046e6508bcc791bdee9e07bb32",
"md5": "cccd72ed03f2cd0bc5f69187d0be1d5f",
"sha256": "7917d91de14625ab1d3a93676b9e8a8176fe819ee8f58ec17b1f8db7cfd0e869"
},
"downloads": -1,
"filename": "ckanext_admin_panel-1.0.12.tar.gz",
"has_sig": false,
"md5_digest": "cccd72ed03f2cd0bc5f69187d0be1d5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 58411,
"upload_time": "2024-05-02T11:41:59",
"upload_time_iso_8601": "2024-05-02T11:41:59.283464Z",
"url": "https://files.pythonhosted.org/packages/8b/fc/3fef1ebe427550f8303f3d886012c5577d046e6508bcc791bdee9e07bb32/ckanext_admin_panel-1.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 11:41:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mutantsan",
"github_project": "ckanext-admin-panel",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "ckanext-admin-panel"
}
JSON
