2lenet/dashboard2-bundle

Dashboard bundle 2, widgets

2.3.8 2024-03-08 15:46 UTC

Requires

• php: >=7.2
• doctrine/doctrine-bundle: ^2.10
• doctrine/orm: ^2.10
• friendsofsymfony/jsrouting-bundle: ^2.2 || ^2.7 || ^3.0
• symfony/dom-crawler: ^6.0
• symfony/form: ^6.0
• symfony/security-bundle: ^6.0
• symfony/ux-chartjs: ^2.0
• twig/twig: ^3.0

Requires (Dev)

• ergebnis/phpstan-rules: ^2.1
• phpstan/phpstan: *
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-doctrine: *
• phpstan/phpstan-mockery: *
• phpstan/phpstan-phpunit: *
• phpstan/phpstan-strict-rules: ^1.5
• phpstan/phpstan-symfony: *
• phpunit/phpunit: ^10.3
• slevomat/coding-standard: ^8.13
• squizlabs/php_codesniffer: ^3.7
• symfony/maker-bundle: ^1.50

MIT

• HEITZMANN Sébastien

• dashboard

README

This bundle provides a dashboard with customizable widgets.

Table of contents

• Installation
  • Creating widgets
• Recipes
  • Troubleshooting
  • Templating
  • Widget configuration
  • Widget cache
  • Widget roles
• Understand the data structure

Installation

composer require 2lenet/dashboard2-bundle

Add this to routes.yaml

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

You will also need to update your database to have the widgets table.

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

⚠️ Do not forget to check your migration file !

Creating widgets

With the maker:

php bin/console make:widget

Just provide a short name for your widget and the maker will generate the class and the template for you.

If you want a widget for your workflow, you should use this maker : php bin/console make:workflow-widget

If you prefer to do it yourself :

Create a class that extends AbstractWidget and fill in the methods.

use Lle\DashboardBundle\Widgets\AbstractWidget;

Method	Description
render	Mandatory. Return a string that will be the widget content.
getName	Get the widget title that will appear in the header. It will be translated by default.
supports	If this method returns false, the users won't be able to see or add it.
supportsAjax	NOT SUPPORTED YET

Recipes

Troubleshooting

Why don't I see my widget ?!

• Check the roles.
• Check your network tab; maybe the widget is returning a 500.
• Try to clear the cache.

How do I get the logged user ?!

• Use $this->security->getUser().

Why is the dashboard ugly/not working ?!

• bin/console asset:install.

Why do I get a 404 ?

• RTFM. Add the routes as specified above.

When I add a widget, they appear very far in the bottom ?!

• The widgets are added below the most bottom existing widget. You may have a widget that does not appear.

Feel free to add more

Templating

A base template exists :

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

To easily render a template, you can use the twig() method. It will automatically add a "widget" variable that contains your type.

Example :

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

Note that base template uses Bootstrap 5 cards. Various blocks exists to override the base template.

If you want to hide the header of a widget, and only show it on hover : you must add the following lines in the template of your widget :

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

By default, there is a button to export a widget as PDF. You can remove this feature :

Example :

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

You can define two parameters to configure your export : orientation (portrait or landscape) and format (a4, a3, a2, ...)

Example :

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

Widget configuration

Each widget is individually configurable. The property "config" in the widgets is a JSON field where you can put anything you like. By default, this field is used by the configuration form.

If you want to add a configuration form, you can use the createForm() method, which works like the Controller one. Then, you need to pass the form as a variable named config_form to the template.

Example:

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
        ]);
    }
}

The result of the form will overwrite the config property, in a JSON format.

To retrieve your form value in the widget : $this->getConfig("etat");

Widget cache

Widgets are cached for 5 minutes, to avoid doing calculations everytime, especially for big charts.
The cache is based on a cache key, if the value of the key changes, the cache is refreshed, whether 5 minutes have passed or not.

You can change the timeout and the cache key with the following :

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

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

If you want to disable the cache for a widget, just make sure that getCacheTimeout returns 0.

Widget roles

Widgets have roles on them, generated from the name.
Example : PostIt => ROLE_DASHBOARD_POST_IT

If you want to change this behaviour, simply override supports(), or add a voter.

Add/configure a chartJS widget

Once configured, this widget allows the user to obtain a chart based on the application provided charts configuration. To do this, you need to create the different possible configurations and generate the data accordingly.

First, implements the ChartProviderInterface on your class (Repository, Service, ...). Then add the getChart and getChartList methods.

The getChartList method is used to list the provided charts configurations usable by the widget The getChart method return a ChartModel ( from symfonyUx Chart bundle ).

getDataConf:

This method return an array with the differents configurations.

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:

For this method, you will receive selected chart key.

Next, you need to create/return a chart model ( \Symfony\UX\Chartjs\Model\Chart )

A full example with a table KPI and KPI Value to graph arbitrary datas:

    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();
    }

Understand the data structure

Widget Entity <--> Widget Type <--> DashboardController

A WidgetType (eg. PostItWidget) is simply a definition that will be used by the controller.
When an user adds a widget, it will create a distinct entity.
A widget may have multiple entities for the same type. For example, an user may have multiple post-its with different contents.

Some widgets do not have an user_id filled in. They are the default widgets, which may only be created by the super admin (using the buttons in the dashboard)