Search by

badpixxel / widgets-bundle

BadPixxel

Easy Widgets & Information boxes for Symfony Applications

Package info

gitlab.com/badpixxel-public/widgets-bundle

Homepage

Type:symfony-bundle

pkg:composer/badpixxel/widgets-bundle

Statistics

Installs: 13 273

Dependents: 3

Suggesters: 0

Stars: 0

2.0.0 2023-04-14 14:16 UTC

This package is auto-updated.

Last update: 2026-11-17 10:41:15 UTC


README

Latest Stable Version License

Easy Widgets & Information boxes for Symfony Applications.

Build interactive dashboards from composable widgets, rendered with Symfony UX Live Components, Chart.js and Bootstrap.

Features

  • Composable Widget System - Widgets are built from simple, reusable blocks
  • Pre-built Blocks - Text, tables, notifications, alerts, progress bars and charts
  • Chart.js Integration - Line, bar, pie, donut, polar, matrix and Sankey charts
  • Theme Colors - Charts follow your Bootstrap theme & color mode, explicit colors still win
  • Symfony UX Live Components - Interactive widgets, deferred loading, in-place editing
  • Widget Collections - User editable dashboards, persisted with Doctrine
  • Role-Based Access Control - Restrict widget visibility by user roles
  • Widget Caching - Per-widget cache with configurable lifetime
  • Date Presets - Built-in time-range filtering (this week, last month, past year...)
  • Bootstrap 3 / 4 / 5 - Rendering modes for each Bootstrap version, bs3 / bs4 / bs5 Twig tests for templates
  • Sonata Integration - Optional Sonata Admin and Sonata Block support
  • Translations - English, French, Spanish, Italian, German & Dutch (BadPixxelWidgets domain)

Requirements

  • PHP 8.1+
  • Symfony 6.4, 7.4 or 8.0
  • Doctrine ORM 2.14+
  • Symfony UX Live Component & Chart.js, with AssetMapper (StimulusBundle)

Installation

composer require badpixxel/widgets-bundle

With Symfony Flex, the bundle is registered in config/bundles.php, its JavaScript dependencies are added to your importmap.php, and its Stimulus controllers to your assets/controllers.json.

Then create the collections tables and load the integration module in your assets/app.js:

php bin/console doctrine:schema:update --force
// Load Chart.js plugins BEFORE Stimulus starts
import '@badpixxel/ux-widgets';

See Getting Started for details.

Quick Start

1. Create a Widget

use BadPixxel\Widgets\Attribute\AsStaticWidget;
use BadPixxel\Widgets\Blocks\Basics\TextBlock;
use BadPixxel\Widgets\Models\AbstractWidget;
use BadPixxel\Widgets\Widgets\Descriptor\SimpleDescriptor;

#[AsStaticWidget(channels: array("dashboard"))]
class WelcomeWidget extends AbstractWidget
{
    public function getDescriptor(): SimpleDescriptor
    {
        return new SimpleDescriptor(
            title: "Welcome Widget",
            description: "Say hello to your users",
            icon: "fa fa-fw fa-home",
            origin: "My Application"
        );
    }

    public function build(): void
    {
        $this->addBlock((new TextBlock())->setText("Hello World!"));
    }
}

2. Display Widgets

{# A single widget, rendered on a deferred Live request #}
<twig:Widget :configurator="welcomeConfigurator" loading="defer" />

{# A user editable collection of widgets #}
<twig:WidgetsCollection type="my-dashboard" channel="dashboard" />

welcomeConfigurator is resolved in your controller with WidgetsResolver::resolve(WelcomeWidget::class).

3. Widget with Charts

use BadPixxel\Widgets\Blocks\ChartJs\LineChartBlock;

public function build(): void
{
    $chart = (new LineChartBlock())
        ->setDataSet(array(
            array("month" => "Jan", "sales" => 100, "costs" => 80),
            array("month" => "Feb", "sales" => 200, "costs" => 110),
            array("month" => "Mar", "sales" => 150, "costs" => 90),
        ))
        ->setPointLabelKey("month")
        ->setPointValuesKeys(array("sales", "costs"))
        ->setLabels(array("Sales", "Costs"))
    ;
    $this->addBlock($chart);
}

Available Blocks

Basic Blocks

  • TextBlock - Display text or HTML
  • TableBlock - Tabular data
  • NotificationsBlock - Notification messages
  • SparkInfoBlock - Compact info display

Bootstrap Blocks

  • AlertBlock - Alert boxes (success, info, warning, error)
  • ProgressBarBlock - Progress indicators

Chart.js Blocks

  • LineChartBlock - Line charts
  • BarChartBlock - Bar charts
  • PieChartBlock - Pie charts
  • DonutChartBlock - Donut charts
  • PolarChartBlock - Polar area charts
  • MatrixChartBlock - Heatmap charts
  • SankeyChartBlock - Flow diagrams

Configuration

Only defaults.colors is currently read; see Configuration Reference.

# config/packages/badpixxel_widgets.yaml
badpixxel_widgets:
    cache:
        enable:     true
    sonata:
        blocks:     true
        admin:      true
    defaults:
        colors:     [series-1, series-2, series-3, series-4, series-5, series-6, series-7, series-8]

Documentation

CLI Commands

# List all available widgets
php bin/console badpixxel:widgets:widgets

# List all available blocks
php bin/console badpixxel:widgets:blocks

# Upgrade from 2.x: convert collections options & parameters to JSON (--dry-run to count only)
php bin/console badpixxel:widgets:migrate-json

Examples

See the demo/Widgets directory for real-world examples:

  • A shop dashboard (Shop/): KPIs without header or footer, line, donut, stacked bar & heatmap charts, targets, products table and notifications, in various widths
  • Text widgets
  • Time-series charts
  • Matrix heatmaps
  • Date preset widgets
  • Cache status widgets

Demo Application

The demo application (demo/, WidgetsDemoBundle) has a navbar to switch between Bootstrap 3, 4 and 5 (/{bsMode}/...), Bootswatch themes (Bootstrap 4 & 5: Flatly, Minty, Sketchy, Darkly; Bootstrap 5 also Morph Quartz, Slate, Solar and Vapor) and the Bootstrap 5 light / dark color mode. Choices are kept in the bpw_demo_theme and bpw_demo_color_mode cookies. Its homepage is a static shop dashboard.

Extension bundles reuse the demo application with their own homepage dashboard & icon: map "BadPixxel\\Widgets\\Demo\\": "vendor/badpixxel/widgets-bundle/demo" in your autoload-dev, register BadPixxel\Widgets\Demo\WidgetsDemoBundle, import @WidgetsDemoBundle/Resources/config/routing.php with prefix: /{bsMode}, then configure the homepage:

# tests/config/packages/widgets_demo.yaml
widgets_demo:
    title:      "D3.js Dashboard"
    subtitle:   "Static D3.js widgets, with demo data"
    icon:       "bundles/badpixxelwidgetsd3js/img/widgets-d3js-icon.svg"
    widgets:
        - App\Widgets\MyWidget
KeyDefaultDescription
titleShop DashboardHomepage title, cannot be empty
subtitleStatic widgets, with demo dataHomepage subtitle
iconbundles/badpixxelwidgets/img/widgets-icon.svgNavbar brand & favicon, public asset path
widgetsThe Shop\ dashboardWidgets classes, in display order

Demo templates read this configuration with the demo_homepage() Twig function.

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

The bundle also ships generic test cases to test your own widgets & blocks: see Testing.

License

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

Credits

Developed by BadPixxel / Splash Sync

Support