badpixxel / widgets-bundle
Easy Widgets & Information boxes for Symfony Applications
Package info
gitlab.com/badpixxel-public/widgets-bundle
Type:symfony-bundle
pkg:composer/badpixxel/widgets-bundle
Requires
- php: ^7.4|^8.0
- ext-json: *
- doctrine/doctrine-bundle: ^2.0
- doctrine/orm: ^2.14
- knplabs/knp-menu-bundle: ~2.0|~3.0
- knplabs/knp-time-bundle: ~1.6
- sonata-project/block-bundle: ~3.0|~4.0
- symfony/http-kernel: ^5.4
- symfony/monolog-bundle: ^2.0|^3.0
Requires (Dev)
- badpixxel/php-sdk: dev-main
- sonata-project/admin-bundle: >=3.0
- symfony/browser-kit: ^5.4
- symfony/debug-pack: ~1.0
- symfony/phpunit-bridge: ^5.4
- symfony/runtime: ^5.4
- symfony/webpack-encore-bundle: ^1.7
- twig/twig: ~2.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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/bs5Twig tests for templates - Sonata Integration - Optional Sonata Admin and Sonata Block support
- Translations - English, French, Spanish, Italian, German & Dutch (
BadPixxelWidgetsdomain)
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
- Getting Started - Installation and basic usage
- Creating Custom Widgets - Build your own widgets
- Creating Custom Blocks - Extend with custom blocks
- Configuration Reference - All configuration options
- Architecture Overview - Understanding the bundle design
- Testing - Test suites & tools to test your own widgets and blocks
- JavaScript Modules - Assets, Stimulus controllers & Chart.js plugins
- Creating Extensions - Ship your own controllers & plugins
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
| Key | Default | Description |
|---|---|---|
title | Shop Dashboard | Homepage title, cannot be empty |
subtitle | Static widgets, with demo data | Homepage subtitle |
icon | bundles/badpixxelwidgets/img/widgets-icon.svg | Navbar brand & favicon, public asset path |
widgets | The Shop\ dashboard | Widgets 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
- Report issues: GitLab Issues
- Documentation: docs/