README

此组件提供可定制的仪表板小部件。

目录

• 安装
  • 创建小部件
• 食谱
  • 故障排除
  • 模板
  • 小部件配置
  • 小部件缓存
  • 小部件角色
• 理解数据结构

安装

composer require 2lenet/dashboard2-bundle

将以下内容添加到routes.yaml

dashboard_widgets:
    resource: "@LleDashboardBundle/Resources/config/routes.yaml"

您还需要更新数据库以包含小部件表。

php bin/console make:migration
php bin/console doctrine:migrations:migrate

⚠️ 不要忘记检查您的迁移文件！

创建小部件

使用生成器

php bin/console make:widget

只需提供您小部件的简称，生成器将为您生成类和模板。

如果您想为工作流程添加小部件，应使用此生成器： php bin/console make:workflow-widget

如果您希望自行完成

创建一个扩展AbstractWidget的类，并填写方法。

use Lle\DashboardBundle\Widgets\AbstractWidget;

食谱

故障排除

为什么我看不到我的小部件？！

• 检查角色。
• 检查您的网络标签；小部件可能返回了500。
• 尝试清除缓存。

如何获取登录用户？！

• 使用 $this->security->getUser().

为什么仪表板很丑/不起作用？！

• bin/console asset:install.

为什么我收到404？

• 查阅文档。添加上述指定的路由。

当我添加小部件时，它们出现在 非常 底部？！

• 小部件被添加到最底部现有小部件下方。您可能有一个不可见的小部件。

请随意添加更多

模板

存在基本模板

{% extends '@LleDashboard/widget/base_widget.html.twig' %}

为了轻松渲染模板，您可以使用twig()方法。它将自动添加一个包含您的类型的"widget"变量。

示例

public function render()
{
    return $this->twig("widget/pasta_widget.html.twig", [
        "data" => $data,
    ]);
}

请注意，基本模板使用Bootstrap 5卡片。存在各种块以覆盖基本模板。

如果您想隐藏小部件的标题，仅在悬停时显示：您必须在您的模板中添加以下行

{% block widget_class %}
    card-simplified
{% endblock %}

默认情况下，有一个按钮可以将小部件导出为PDF。您可以删除此功能

示例

public function render()
{
    return $this->twig("widget/pasta_widget.html.twig", [
        "data" => $data,
        "exportable" => false
    ]);
}

您可以定义两个参数来配置您的导出：方向（纵向或横向）和格式（a4、a3、a2等）

示例

public function render()
{
    return $this->twig("widget/pasta_widget.html.twig", [
        "data" => $data,
        "exportable" => [
            "orientation" => "landscape",
            "format" => "a3"
        ],
    ]);
}

小部件配置

每个小部件都是单独可配置的。小部件中的"config"属性是一个JSON字段，您可以放置任何内容。默认情况下，此字段由配置表单使用。

如果您想添加配置表单，可以使用createForm()方法，它类似于Controller中的一个。然后，您需要将表单作为名为config_form的变量传递到模板中。

示例

public function render()
{
    $form = $this->createForm(InterventionWidgetType::class);
    
    return $this->twig("widget/cake_widget.html.twig", [
        "data" => $data,
        "config_form" => $form->createView()
    ]);
}

class InterventionWidgetType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('etat', ChoiceType::class, [
                'choices' => $yourChoices
            ])
        ;
    }
    
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            // Configure your form options here
        ]);
    }
}

表单的结果将覆盖配置属性，以JSON格式。

在组件中检索您的表单值：$this->getConfig("etat");

小部件缓存

小部件被缓存5分钟，以避免每次都进行计算，尤其是对于大型图表。
缓存基于缓存键，如果键的值发生变化，则刷新缓存，无论是否已过了5分钟。

您可以使用以下方法更改超时和缓存键

public function getCacheKey(): string
{
    return $this->getId() . "_" .md5($this->config);
}

public function getCacheTimeout(): int
{
    return 300;
}

如果您想为小部件禁用缓存，只需确保getCacheTimeout返回0。

小部件角色

小部件具有角色，这些角色由名称生成。
示例：PostIt => ROLE_DASHBOARD_POST_IT

如果您想更改此行为，只需重写 supports() 方法或添加一个投票者。

添加/配置一个 chartJS 小部件

配置完成后，此小部件允许用户根据应用提供的图表配置获取图表。为此，您需要创建不同的配置并相应地生成数据。

首先，在您的类（仓库、服务等）上实现 ChartProviderInterface。然后添加 getChart 和 getChartList 方法。

getChartList 方法用于列出小部件可用的提供的图表配置。 getChart 方法返回一个 ChartModel（来自 symfonyUx Chart 包）。

getDataConf:

此方法返回一个包含不同配置的数组。

public function getChartList(): array
{
    return [
        'COUNTSOMETHING-DAY-30',
        'COUNTSOMETHING-DAY-60',
        'COUNTSOMETHING-MONTH-12',
        'COUNTSOMETHING-MONTH-24',
        'SUMSOMETHING-DAY-30',
        'SUMSOMETHING-DAY-60',
        'SUMSOMETHING-MONTH-12',
        'SUMSOMETHING-YEAR-1'
    ];
}

getChart:

对于此方法，您将接收到选择的图表键。

接下来，您需要创建/返回一个图表模型（\Symfony\UX\Chartjs\Model\Chart）

一个包含表格 KPI 和 KPI 值以绘制任意数据的完整示例

    public function getChartList(): array
    {
        $qb = $this->createQueryBuilder('kv');
        $qb->join("kv.kpi", "k");
        $qb->distinct();
        $qb->select('k.code');
        $codes = [];

        foreach ($qb->getQuery()->execute() as $code) {
            $codes[] = $code["code"];
        }

        return $codes;
    }
    public function getChart(string $confKey): Chart
    {
        $labels = [];
        $values = [];
        foreach ($this->getData($confKey) as $row) {
            $labels[] = $row['date'];
            $values[] = $row['value'];
        }

        $chart = $this->chartBuilder->createChart(Chart::TYPE_BAR);
        $chart->setData([
            'labels' => $labels,
            'datasets' => [
                [
                    'label' => $confKey,
                    'backgroundColor' => 'rgb(255, 99, 132, .4)',
                    'borderColor' => 'rgb(255, 99, 132)',
                    'data' => $values,
                    'tension' => 0.4,
                ],
            ],
        ]);
        $chart->setOptions([
            'maintainAspectRatio' => false,
        ]);

        return $chart;
    }

    public function getData(string $confKey): array
    {
        $qb = $this->createQueryBuilder('kv');
        $qb->join("kv.kpi", "k");
        $qb->select('SUM(kv.value) as value');
        $qb->where("k.code = :kpi");
        $qb->setParameter("kpi", $confKey);

        $qb
            ->addSelect("CONCAT(WEEK(kv.date), '-', YEAR(kv.date)) as date")
            ->groupBy('date');

        return $qb->getQuery()->getResult();
    }

理解数据结构

小部件实体 <--> 小部件类型 <--> DashboardController

WidgetType（例如 PostItWidget）只是一个 定义，将被控制器使用。
当用户添加小部件时，它将创建一个不同的实体。
一个小部件可能具有多个同类型的实体。例如，一个用户可能有多个不同内容的海报。

某些小部件没有填写 user_id。它们是默认小部件，只能由超级管理员创建（使用仪表板中的按钮）。