Chart Properties Schema Migration - GSS-Cogs/chart-builder GitHub Wiki

As Chart Builder evolves to meet the requirements of new business domains, datasets and visualisations the number of chart properties available to content creators increases. To keep existing chart content up to date their stored properties (and property sections) need to be migrated to match the latest properties schema.

Chart properties fundamentals:

  • Properties in Chart Builder are arranged in sections (both in the side panel in the UI and in the data structures that are used to represent the properties). Each section has a name and one or more properties. Properties in turn each have a name and a value (a key-value pair).

  • We use a schema ChartPropertiesSchema.ts to declaratively specify chart properties to render in the properties side panel - this avoids the need to hard-code properties and also allows properties to easily be re-ordered in the side panel by devs.

  • In the Volto chart builder add-on the properties for each chart are stored in the Volto block state as JSON.

Properties migration

A benefit of using this schema based approach to maintaining the chart properties is that the schema can be used to update the properties of chart instances created using an earlier version of the schema. The volto add-on version of chart builder contains migration logic to do just this.

An explanation the migration logic is provided in chartPropertiesMigrator.js of volto-chart-builder but in very simple terms the migration logic maps through the ChartPropertiesSchema and updates the stored properties and property sections of that chart to match the schema.

Behaviour of the migration logic

  • The migration logic is activated only when an individual chart enters edit mode (there is no site-wide migration)
  • The migrated schema will only be saved if the author saves the chart (i.e. closing out of edit mode will not save the change)
  • Any new property sections and/or individual properties added by the latest schema will show in the chart properties side panel and will take default values
  • Any property sections and/or individual properties removed by the latest schema will not show in the chart properties side panel and will be removed from the stored properties of the chart
  • Any property sections and/or individual properties that remain unchanged (between schema and current state) will retain their current property values (this is the most common case as most properties wont change between schema updates)
  • In the rare case where a property is moved from one section to another during the migration the stored value be not be preserved. In this case the release notes would need to inform content authors to update the default value of the 'new' property