ckanext-charts

此扩展，ckanext-charts，为在CKAN中处理图表提供额外功能。它允许用户基于存储在CKAN数据集中的数据创建、管理和可视化图表。

扩展包括图表创建、图表编辑、图表嵌入和图表共享等功能。它还支持多种图表类型，包括柱状图、折线图、饼图等。

使用ckanext-charts，用户可以轻松生成交互式和视觉上吸引人的图表，以增强CKAN中的数据分析和展示。

本扩展提供两个插件：charts_view和charts_builder_view。第一个插件是一个标准图表构建器，为系统管理员或任何有权编辑或创建资源视图的人设计。使用此插件创建预览会生成一个静态图表，并保存设置。此图表将保留设置，并且始终以相同的方式渲染。

charts_builder_view插件在创建或编辑阶段没有特殊设置。相反，它在资源页面上渲染一个图表构建器JS小部件，允许任何用户与资源数据交互，并创建满足他们需求的图表。未来，我们计划实现一个允许用户保存他们图表的功能。

用户图表构建器可以限制为仅认证用户。有关更多信息，请参阅配置设置部分。在这种情况下，用户将被强制登录以构建图表。用户登录后，将被重定向回图表构建器页面。

需求

需要Redis 7+

与核心CKAN版本的兼容性

安装

• 使用PyPi安装，命令为pip install ckanext-charts
• 将charts_view添加到CKAN配置中的插件列表中（ckan.plugins = charts_view charts_builder_view）

配置设置

配置选项列表

# Caching strategy for chart data (required, default: redis).
# Available options: redis, file_orc, file_csv
ckanext.charts.cache_strategy = file_csv

# Time to live for the Redis cache in seconds. Set 0 to disable cache (default: 3600)
ckanext.charts.redis_cache_ttl = 7200

# Time to live for the File cache in seconds. Set 0 to disable cache.
ckanext.charts.file_cache_ttl = 0

# Enable cache for the charts (default: true)
ckanext.charts.enable_cache = true

# Include HTMX assets. Could be disabled if another plugins are including it (default: true)
ckanext.charts.include_htmx_asset

# Reinit CKAN JS modules after HTMX swap (default: false)
ckanext.charts.reinit_ckan_js_modules

# Allow anonymous users to build charts (default: false)
ckanext.charts.allow_anon_building_charts

管理员配置页面

该扩展提供了一个管理员配置页面，您可以在其中设置所有列出的配置选项。管理员页面仅可通过扩展ckanext-admin-panel访问。管理员面板是一个独立的扩展，为CKAN提供替代的管理界面。它允许您通过Web界面管理CKAN设置和其他扩展设置。

此页面可通过以下URL访问：/admin-panel/charts/config，但只有在安装并启用ckanext-admin-panel时才会注册。

缓存

该扩展实现了一种缓存策略，用于存储从不同来源获取的数据。有三种缓存策略可用：redis、file_orc和file_csv。文件缓存通过将数据存储在文件系统中的orc或csv文件中来工作。Redis缓存将数据存储在Redis数据库中。缓存策略可以通过管理员界面或配置文件在CKAN配置级别进行更改。

缓存TTL可以在CKAN配置文件中设置。默认值为3600秒（1小时）。可以将缓存TTL设置为0以禁用缓存。

redis和file-type缓存具有单独的TTL设置。Redis缓存TTL可以使用ckanext.charts.redis_cache_ttl配置选项设置。file缓存TTL可以使用ckanext.charts.file_cache_ttl配置选项设置。

要使用redis缓存策略，您需要有一个正在运行的Redis服务器。

file-type缓存策略将数据存储在文件系统中一个文件中。文件缓存存储在CKAN存储路径中的ckanext-charts目录下。文件缓存以orc或csv文件格式存储。

可以通过将ckanext.charts.enable_cache设置为false来禁用缓存。在这种情况下，每次渲染图表时都会从源获取数据。这可能在调试目的上很有用。但在生产环境中使用它不建议，因为它可能导致性能问题。

文件ORC缓存策略

此策略需要安装pyarrow Python库。

实现新的数据获取器

数据获取器负责从不同的来源（数据存储、URL、文件系统、硬编码数据）获取数据。

要注册新的数据提取器，您需要创建一个继承自 DataFetcherStrategy 的新类，并实现 fetch_data 和 make_cache_key 方法。 fetch_data 方法应返回一个包含应在图表中显示的数据的 pandas DataFrame 对象。 make_cache_key 方法应返回一个唯一的字符串，该字符串将用作缓存中存储数据的键。

实现新的图表引擎支持

实现对新图表引擎的支持包括多个步骤和 Python、HTML 和 JavaScript 中的更改。从 Python 代码开始

1. 在 ckanext.charts.chart_builder 中创建一个新的构建器类，该类继承自 BaseChartBuilder 并实现 get_supported_forms 方法。此方法必须返回表示支持图表类型表单的类的列表。

2. 每种表单类型的构建器必须与相应的图表类型构建器相关联。

3. 图表类型构建器必须实现一个 to_json 方法，该方法将返回要传递给 JS 脚本的反序列化 JSON 数据。

4. 表单类型构建器必须实现一个 get_form_fields 方法，该方法将返回将用于用户的渲染的所有表单字段列表，使他们能够为图表提供所有必要的信息。

5. 通过将构建器类添加到 get_chart_engines 中，在 ckanext.charts.chart_builder.__init__.py 中注册您的图表引擎。

一个完整的实现示例，用于 obvervable plot 库的 bar 图表。

from __future__ import annotations

import json
from typing import Any

import ckanext.charts.exception as exception
from ckanext.charts.chart_builders.base import BaseChartBuilder, BaseChartForm


class ObservableBuilder(BaseChartBuilder):
    @classmethod
    def get_supported_forms(cls) -> list[type[Any]]:
        return [ObservableBarForm]


class ObservableBarBuilder(ObservableBuilder):
    def to_json(self) -> str:
        return json.dumps(
            {
                "type": "bar",
                "data": self.df.to_dict(orient="records"),
                "settings": self.settings,
            }
        )


class ObservableBarForm(BaseChartForm):
    name = "Bar"
    builder = ObservableBarBuilder

    def fill_field(self, choices: list[dict[str, str]]) -> dict[str, str]:
        field = self.color_field(choices)
        field.update({"field_name": "fill", "label": "Fill"})

        return field

    def get_form_fields(self):
        columns = [{"value": col, "label": col} for col in self.df.columns]
        chart_types = [
            {"value": form.name, "label": form.name}
            for form in self.builder.get_supported_forms()
        ]

        return [
            self.title_field(),
            self.description_field(),
            self.engine_field(),
            self.type_field(chart_types),
            self.x_axis_field(columns),
            self.y_axis_field(columns),
            self.fill_field(columns),
            self.opacity_field(),
            self.limit_field(),
        ]

另一个步骤是注册您想要使用的图表的 JS/CSS 厂商库。有关使用 Webassets 添加 CSS 和 JavaScript 文件的说明，请参阅 CKAN 文档。

您还需要一个 CKAN JS 模块，该模块负责渲染图表。此模块必须在 webassets.yml 中注册。

    ckan.module("charts-render-observable", function ($, _) {
        "use strict";

        return {
            options: {
                config: null
            },

            initialize: function () {
                $.proxyAll(this, /_/);

                if (!this.options.config) {
                    console.error("No configuration provided");
                    return;
                }

                var plot;

                switch (this.options.config.type) {
                    case "bar":
                        plot = Plot.barY(this.options.config.data, this.options.config.settings).plot();
                        break;
                    default:
                        return;
                }

                this.el[0].replaceChildren(plot);
            }
        };
    });

以及一个 HTML 文件，该文件提供适当的容器并将您的 JS 模块包含在 data-module 中。

    {% asset "charts/observable" %}

    {% if chart %}
        <div id="chart-container" data-module="charts-render-observable" data-module-config="{{ chart }}"></div>
    {% else %}
        <p class="text-muted">
            {{ _("Cannot build chart with current settings") }}
        </p>
    {% endif %}

注意，我们不仅在这里，而且在 charts_form.html 中也应添加 {% asset "charts/observable" %}。

具有单独的 HTML 文件和 JS 模块的原因是，不同的库可能需要不同类型的容器元素（如 div、canvas 等）来初始化，或者可能需要额外的样板代码来构建图表。没有简单的方法可以抽象化这些，所以您必须自己实现这些功能。

开发者安装

要为开发安装 ckanext-charts，请激活您的 CKAN 虚拟环境，并执行

git clone https://github.com/DataShades/ckanext-charts.git
cd ckanext-charts
python setup.py develop
pip install -r dev-requirements.txt

故障排除

ImportError: lxml.html.clean 模块现在是一个单独的项目 lxml_html_clean

直接使用 pip 安装 lxml[html_clean] 或 lxml_html_clean。

测试

要运行测试，请执行

pytest --ckan-ini=test.ini

许可协议

AGPL