Search by

badpixxel / widgets-dashboards-bundle

BadPixxel

BadPixxel Widgets Dashboards: KPI & Dashboard Blocks

Package info

gitlab.com/badpixxel-public/widgets-dashboard-bundle

Homepage

Type:symfony-bundle

pkg:composer/badpixxel/widgets-dashboards-bundle

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

3.0.x-dev 2026-11-17 12:46 UTC

This package is auto-updated.

Last update: 2026-11-17 11:46:27 UTC


README

Dashboard blocks for BadPixxel Widgets: blocks that make a situation readable at a glance. Is it good or bad, compared to what, how far from target?

Features

  • KPI - Value, change vs previous period with a good / bad meaning, optional target - docs
  • Gauge - Value within a range, on an SVG half circle, with good / warning / critical zones - docs
  • Sparkline - Tiny line without axes, with last value & change, also as KPI history - docs
  • Target Bar - Bullet chart: actual value vs target, over good / warning / critical ranges - docs
  • Status List - Monitored items with OK / warning / critical status & last check time, worst first - docs
  • Ranking - Top N rows, highest first, with proportional bars - docs
  • Activity Feed - Timeline of dated events, newest first - docs
  • Trend Directions - A rise is not always good news: higher is better, lower is better or neutral
  • Numbers Formatting - Separators, units, compact form (84.3k €) and signed percentages
  • Theme Colors - Good & bad news use the theme roles of the Widgets Bundle, following the color mode
  • Translations - English, French, Spanish, Italian, German & Dutch (BadPixxelWidgetsDashboards domain)

More blocks may come later, e.g. a conversion funnel.

Requirements

  • PHP 8.1+
  • Symfony 6.4, 7.4 or 8.0
  • badpixxel/widgets-bundle ^3.0

Installation

composer require badpixxel/widgets-dashboards-bundle

Quick Start

use BadPixxel\Widgets\Attribute\AsStaticWidget;
use BadPixxel\Widgets\Dashboards\Blocks\Kpi\KpiBlock;
use BadPixxel\Widgets\Dashboards\Dictionary\TrendDirections;
use BadPixxel\Widgets\Dictionary\Options;
use BadPixxel\Widgets\Dictionary\Widgets\WidgetWidth;
use BadPixxel\Widgets\Models\AbstractWidget;
use BadPixxel\Widgets\Widgets\Descriptor\SimpleDescriptor;

#[AsStaticWidget(
    channels: array("dashboard"),
    options: array(Options::WIDTH => WidgetWidth::XS, Options::SHOW_HEADER => false),
)]
class ReturnsRateWidget extends AbstractWidget
{
    public function getDescriptor(): SimpleDescriptor
    {
        return new SimpleDescriptor(title: "Returns Rate", description: "Returns rate", icon: "fa fa-undo", origin: "App");
    }

    public function build(): void
    {
        $this->addBlock(
            (new KpiBlock())
                ->setLabel("Returns Rate", "fa fa-fw fa-undo")
                ->setValue(4.2, "%")
                ->setPrevious(3.6, "vs last month")
                ->setDirection(TrendDirections::LOWER_IS_BETTER)    // A rise is bad news
                ->setFormat(1)
        );
    }
}

Render it as any other widget: <twig:Widget :configurator="configurator" />.

Demo Application

The bundle reuses the demo application of the Widgets Bundle (Bootstrap 3 / 4 / 5, Bootswatch themes, color mode), with its own homepage, configured in tests/config/packages/widgets_demo.yaml: Dashboards demo widgets first (tests/Widgets), then the Widgets Bundle shop dashboard.

Demo widgets are configurable, to try blocks display modes from the widget preview page: KPI history / target / compact numbers, gauge values (random by default), sparkline area / trend meaning / color, target bar ranges / targets, status list sorting / summary, ranking rows / bars color, activity feed events. Parameters are declared with tests/Widgets/DemoParametersTrait.php.

make up                     # Start containers: app, sf6, sf7, sf8

Then open http://app.dashboard.widgets.local (see docker-compose.yaml for hosts).

Testing

make verify                 # Quality checks + PHPUnit in all containers (Symfony 6.4, 7.4 & 8.0)
make quality                # Quality checks (lint, code style, PHPStan), current container
php vendor/bin/phpunit      # PHPUnit, current container

Test suites: tests/Core (numbers formatting, trends, thresholds, sparkline paths, all blocks renderers), tests/Integration (generic blocks & widgets test cases of the Widgets Bundle) and tests/Operational (demo homepage).

Links

License

This bundle is licensed under the MIT License. See the LICENSE file for details.