wikimedia/vegalite-wordpress-plugin

Vega Lite WordPress Plugin

Developed by Human Made and the Wikimedia Foundation.

Stable tag: 0.3.0

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

Development

This project expects Node 16 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 test: Use Jest to run JS unit tests.
• npm run lint: Use ESLint to check src code for errors.

---

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.

Changelog

0.3.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.

vegalite-wordpress-plugin's Issues

Consider auto-filtering rendered CSV data

Especially if #38 is implemented, there may be datasets uploaded to the site which contain many columns of data. A given chart may only use one or two of those, but we still need to deliver the entire CSV to the browser in order to render the spec.

The CSV endpoint could optionally be modified to permit charts to request only the subset of fields they actually need, which we can derive from the fields which are referenced in the chart's JSON spec. This would allow large datasets to be used with less impact to the end user.

Charts re-render unnecessarily when viewport changes

I noticed on some pages that if the viewport changes size very slightly, not enough to cause a different variant of the chart to load, the graphs may still re-render. This causes a small visual flicker, and uses device resources unnecessarily since no change has been made which would require the chart to be re-rendered.

This issue tracks investigating the resize observer code within this plugin to ensure it is only triggering a re-render when absolutely necessary.

Support site-wide color palette

Vega provides a variety of automatic color schemes out of the box, but it also supports registration of custom color schemes. To ensure design consistency across a variety of charts within a site section, it would be beneficial to be able to define a site-level custom color scheme for ordinal, nominal, and continuous data. This would allow charts like this,

to have their coloration be controlled and enable charts to stay more in line with overall site design guidelines and brand colors (as was done in the past with manually-authored charts).

Hypothetical implementation approaches:

• Register a classic-admin-style Site Settings page with custom metaboxes to define and preview the scales for ordinal, nominal, and continuous-range data
• Alternately, have the schemes controlled through a sidebar plugin within the block editor. Opportunity: keeps design closer to the graph usage; risk: could be counter-intuitive to change a design on one page and have that impact other rendered charts using that palette.
• Potentially could provide feedback on contrast between selected colors in order to warn in advance if selected palettes might pose accessibility issues

Stretch goal: Investigate Vega options and see if there's an easy way to introduce a UI to "pin" a particular datapoint (Wikimedia, for example, in the above graph) to be represented by a consistent, brand-specific color.

Allow site-wide datasets

Currently, to use the same dataset CSV across multiple posts, you must upload it to each post. The data gets saved in the post meta of each post separately, and corrections to one dataset would not be reflected in other posts where that same CSV had been uploaded.

In a report context, it may be useful to be able to upload one dataset and then provide different insights based on the data in a variety of charts across multiple pages. To maximize efficiency of data storage and data editing, and to improve the alignment between how datasets actually work and how our initial users assumed they would work, we should provide the ability to upload a dataset at the site level. That dataset should then be selectable within the vega block in the editor.

Assumption: editing the dataset would open the dataset in a different page, to emphasize that the data being changed has cross-post impact.

Spike: Support geographic charts

It is possible to render a map in Vega using geoJSON, and to overlay data points on top of that map. Example: earthquake data example in vega-lite documentation

(This example uses Mike Bostock's MIT-licensed topojson data, derived from Natual Earth's free-use map vector set.)

We have experimented in the past with providing mouse and touch controls to be able to intuitively rotate a globe visualization rendered in this way, but even without that degree of interactivity, this visualization approach would greatly expand what can be created out of the box with this plugin.

Goal: Provide an MVP of a chart type based on geoJSON data.

Improve code editor

The current code editor is hard to use, and provides a poor experience while editing the spec manually.

To provide a user-friendly editing experience while modifying a chart's spec JSON by hand, we should replace the current editor component with a more robust tool. The MIT-licensed Monaco editor from Microsoft is one candidate, but there are others.

Other brainstorming:

• Open in modal to permit better usability when editing graphs in a narrow column?
• Permit editing and previewing spec without saving, to allow experimentation before the new markup is synced back to block attributes. Would require a component state facade or separate preview spec renderer to decouple the draft spec from the saved version. Would also require alerting to the user when their actions would either cause the saved version to be changed (confirmation of save), or of when they may exit out of the editor and lose unsaved draft work (confirmation of discard).
• Monaco should support JSON schema validation but if it does not, using an editor which could interpret the Vega JSON schema and provide inline hints would greatly increase usability

Provide better controls for circle chart sizing

When laying out a circle chart, currently it is not straightforward to tie dimensions of data into the circle's sizing. Scale is best communicated in a circle chart by setting the radius to the square root of the relevant value, so as an MVP we would look at using sqrt scaling for area. Other scaling options could be introduced as needed or handled within the manual spec editor.

Goal: Be able to create a circle-mark chart, and then select a (quantitative) dimension of data to use for circle sizing as a bubble chart.

Vegalite WP Plugin new issue test

Issue description

Experiment: Change renderer to new Expression Interpreter

Vega currently requires the unsafe-eval directive because of how Function() is used when parsing a spec. While this usage is usually safe in our context, it does require CSP headers on an entire site to be defined in a looser fashion than we'd desire. There is a new Expression Interpreter rendering approach, which operates slightly slower but does not cause this same unsafe-eval impact.

We should prioritize implementing the new Expression Interpreter, and profile the difference in chart rendering time to quantify the rendering performance impact of making this security improvement.