Vega Lite WordPress Plugin

Developed by Human Made and the Wikimedia Foundation.

Plugin release archive

This plugin provides a flexible data visualization block using the Vega-Lite declarative JSON visualization grammar.

• Getting Started with Vega-Lite
• Documentation for Vega-Lite

Frontend Events

The plugin dispatches DOM events on the .visualization-block element so external code can respond to chart interactions without polling or coupling to the Vega View API.

vegalite:ready

Fired once after a chart finishes rendering.

document.addEventListener( 'vegalite:ready', ( event ) => {
	const { id, view, spec } = event.detail;
	// id  — the chart's DOM id string
	// view — the Vega View instance (full Vega API available)
	// spec — the Vega-Lite specification object
} );

vegalite:click

Fired when a user clicks on a chart element (e.g. a pie/arc segment). The datum object contains the data fields defined in the Vega-Lite spec for the clicked mark.

document.addEventListener( 'vegalite:click', ( event ) => {
	const { id, datum } = event.detail;
	// id    — the chart's DOM id string
	// datum — the data record for the clicked mark (e.g. { category, className, color, … })
} );

Both events bubble, so you can listen on document or scope the listener to a specific container.

Connecting a chart to an accordion via className:

Add a className field to each data record in your Vega-Lite spec, then apply the same class to the matching accordion item in your markup. The listener below opens the accordion whose class matches the clicked segment:

document.addEventListener( 'vegalite:click', ( event ) => {
	const { datum } = event.detail;
	if ( ! datum.className ) return;
	const accordion = document.querySelector( `.${ datum.className }` );
	accordion?.querySelector( 'button' )?.click();
} );

Development

This project expects Node 24 or later and Composer 2. We recommend managing the installed version of Node using nvm, in which case you can select the version of node specified in this project's .nvmrc file by running nvm use in your terminal.

npm install
npm run build

To start a live-reloading dev server, run

npm start

Other useful commands

• npm run lint: Use ESLint to check src code for errors.

Local Environment

This project uses wp-env to run a lightweight, containerized WordPress instance at localhost:8343 for testing purposes. (8343 is "vega" on a phone keypad.) The default username for the localhost environment is admin, with the password password.

These commands can be used to interact with the environment:

Command	Purpose
npm run env:start	Start the local environment at http://localhost:8343
npm run env:stop	Turn off the local environment
npm run env:cli -- wp ...	Run WP-CLI commands within the environment
npm run env:logs	Open (and tail) the error logs for the application‡
npm run env:db	Open the database in the mysql command line
npm run env:destroy	Fully destroy the local environment (deletes container database)

^‡ This command deliberately filters out GET/OPTIONS/HEAD/POST/PUT access log entries

Release Process

Versioning

This plugin follows Semantic Versioning.

In a nutshell, this means that patch releases, for example, 1.2.3, only contain backwards compatible bug fixes. Minor releases, for example, 1.2.0, may contain enhancements, new features, tests, and pretty much everything that does not break backwards compatibility. Every breaking change to public APIs—be it renaming or even deleting structures intended for reuse, or making backwards-incompatible changes to certain functionality—warrants a major release, for example, 2.0.0.

If you are using Composer to pull this plugin into your website build, choose your version constraint accordingly.

Even when bumping a major version, if the blocks provided by this plugin change in a backwards-incompatible way, a block deprecation should be added to let users migrate their visualizations to the new version of the block.

Publishing a Release

Release management is done using GitHub's built-in Releases functionality. When you tag a commit on the main branch with a version number in the format v#.#.#, a release action will trigger when that tag is pushed to GitHub. The GitHub actions release workflow creates a new built release based on the contents of the tag you created. It copies the tag's current state to a new tag of original/v.*.*.*, then builds the project and pushes the built version to the original tag name v*.*.*. This allows composer to pull in a built version of the project without the need to run webpack to use it.

To prepare a release, follow these steps:

0. Ensure you are on the main branch and that there are no uncommitted local changes.
1. Depending on whether you are preparing a major, minor, or patch release (see Versioning above), run one of these three NPM actions to update the version number throughout the project:

• npm run bump:patch: Update the project's version number to the next patch release number.
• npm run bump:minor: Update the project's version number to the next minor release number.
• npm run bump:major: Update the project's version number to the next major release number.

2. Create a tag with the same number as the updated project version number, e.g. v1.2.3.
3. Push the updated main branch and tag to GitHub.

Once a release has been created, update the release's description using GitHub's interface to add patch notes. Release notes should be high-level but complete, detailing all New Features, Enhancements, Bug Fixes and potential other changes included in the according version.

Development testing

Any code merged into the develop branch will be build and committed to the release-develop branch. This branch can be used in non-production applications to validate and test proposed changes.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Changelog

0.7.0

• Prevent charts from overflowing their column if used in column block layouts or narrow sidebars
• Encode chart specification JSON in post content as a Base64 string to keep WordPress sanitization from mangling mathematical operators like > in spec parameters
• Initialize charts as Vega schema v6 by default

Internal:

• Modify and upgrade the plugin's code quality infrastructure and CI actions
• Remove unused bundled copy of v5 vega-lite specification JSON

0.6.0

Breaking changes:

• Upgrade vega-embed from 6.23.0 to 7.1.0; upgrade vega-lite from 5.16.3 to 6.4.3; upgrade vega from 5.26.1 to 6.2.0
  • Vega 6 does not provide a formal list of breaking changes, but existing charts should be checked in case changes to Vega signals require your specs to be adjusted for this upgrade.

New features:

• Introduce vegalite:ready and vegalite:click event dispatch system to bind external functionality to chart interactions
• Improve sanitization of data-attribute output

Internal:

• Modify and upgrade the plugin's build infrastructure and CI actions
• Make GPL-v2-or-later license explicit in repository

0.5.0

• Upgrade vega-embed from 6.20.2 to 6.23.0; upgrade vega-lite from 5.2.0 to 5.16.3; upgrade vega from 5.21.0 to 5.26.1

0.2.4

• Upgrade build dependencies for security and performance.
• Pin the specific SHA1 commits of the GH actions
• Update build actions to use Node.js version 18

0.2.3

• Upgrade build dependencies for security and performance.

0.2.2

• Fix issue where frontend block styles were not getting enqueued for responsive block.

0.2.1

• Fix issue where blocks did not render on frontend due to block.json being deleted on build.
• Fix issue where CSV meta was not registered as an array.
• Fix issue where block scripts loaded on all pages, not only when a block is present.

0.2.0

• Introduce Responsive Visualization Container block.
• UI overhaul for Data Visualization block.
• Fix bug where field dropdowns could de-sync with available fields in dataset.

0.1.0

• Initial release. Introduce "Data Visualization" block.