Visualisation

Type identifier: visualisation Category: Experience Blocks

Description

Data-visualisation block with component-specific configuration for WordCloud, BarChart, and Map.

Component Variants

WordCloud

Optional config:

• textPath, countPath
• padding (0..50)
• rotation (horizontal | mixed | vertical)
• minFontSize (1..100)
• maxFontSize (1..200)
• color

BarChart

Optional config:

• yAxisPath, xAxisPath
• barColor, showGrid, showTooltip, xAxisAngle, barRadius
• showXAxis, showYAxis, layout
• labelPosition, labelFontSize, labelFontWeight, labelFill
• useColorRange, colorRangeStart, colorRangeEnd

Map

Optional config:

• zoomFiltering
• styleMapping
• pointBlock, hoverBlock
• hoverStyle
• worldCopyJump, minZoom, maxZoom, showMinimap

Supported datum payloads:

• GeoJSON geometry, feature, or feature collection payloads
• Geography reference payloads with the following shape:

{
  "mode": "geography-reference",
  "rows": [
    {
      "id": "AU",
      "sources": [
        {
          "type": "reference",
          "geographySet": "world-country-ne-v1",
          "geographyCode": "AU"
        }
      ],
      "properties": {
        "regionName": "Oceania",
        "displayCount": 10
      },
      "value": 124
    }
  ]
}

• Geography reference payloads can also define row-level custom sources when a rendered feature needs to be built from multiple standard regions, inline GeoJSON literals, or both:

{
  "mode": "geography-reference",
  "rows": [
    {
      "id": "anz-core",
      "label": "ANZ Core",
      "properties": {
        "detailLevel": "Continental",
        "displayCount": 12
      },
      "sources": [
        {
          "type": "reference",
          "geographySet": "world-country-ne-v1",
          "geographyCode": "AU"
        },
        {
          "type": "reference",
          "geographySet": "world-country-ne-v1",
          "geographyCode": "NZ"
        },
        {
          "type": "geojson",
          "value": {
            "type": "Polygon",
            "coordinates": [
              [
                [160, -20],
                [161, -20],
                [161, -19],
                [160, -19],
                [160, -20]
              ]
            ]
          }
        }
      ]
    }
  ]
}

Reference-mode requirements:

• mode must be geography-reference
• rows[].id is the feature identifier for the rendered row
• Additional row properties, including rows[].properties, are merged onto feature properties for styling and hover content
• rows[].sources[] is required and can mix standard geography references with inline GeoJSON literals
• rows[].sources[].geographySet is required for reference sources

Mode selection guidance:

• GeoJSON mode accepts custom shapes and ad hoc map geometry.
• Geography-reference mode maps rows onto a known geography set, or assembles custom regions from standard units.

Shipped geography sets:

• world-country-ne-v1: countries, identified by ISO 3166-1 alpha-2 codes
• world-admin1-ne-v1: global first-order subdivisions, identified by ISO 3166-2 codes
• world-admin1-africa-ne-v1, world-admin1-antarctica-ne-v1, world-admin1-asia-ne-v1, world-admin1-europe-east-ne-v1, world-admin1-europe-west-ne-v1, world-admin1-north-america-ne-v1, world-admin1-oceania-ne-v1, world-admin1-south-america-ne-v1: regional admin-1 packs, described in the table below

Geography-Reference Data Shaping

Each row renders one feature.

• rows[].id is a stable row identifier from your dataset. It does not need to equal the geography code.
• Put one or more geometry inputs in rows[].sources[].
• type: "reference" resolves the row to a shipped geography unit from a known geography set.
• type: "geojson" supplies inline custom geometry for the row.
• Put display or styling fields either on the row itself or under rows[].properties; both are merged into the rendered feature properties.

A row that matches one shipped geography unit directly has this shape:

{
  "mode": "geography-reference",
  "rows": [
    {
      "id": "US",
      "label": "United States",
      "sources": [
        {
          "type": "reference",
          "geographySet": "world-country-ne-v1",
          "geographyCode": "US"
        }
      ],
      "properties": {
        "value": 125,
        "segment": "North America"
      }
    }
  ]
}

For first-order subdivisions, keep the same structure but switch both the geographySet and the code format:

{
  "mode": "geography-reference",
  "rows": [
    {
      "id": "US-CA",
      "label": "California",
      "sources": [
        {
          "type": "reference",
          "geographySet": "world-admin1-north-america-ne-v1",
          "geographyCode": "US-CA"
        }
      ],
      "properties": {
        "value": 42
      }
    }
  ]
}

A custom composite region uses one output row with multiple sources:

• Multiple reference sources from the same geography set merge into one output geometry.
• reference sources from different geography sets can be combined, but the output is then a custom composite feature rather than a simple boundary-pack join.
• Inline geojson sources can be mixed with reference sources when you need to extend or patch a region.

Choosing the Geography Set

The geography set follows the level of the identifiers in your rows, not the visual zoom level.

Selection rules:

• Row identifiers that are country codes use world-country-ne-v1.
• Row identifiers that are first-order subdivision codes use an admin-1 set.
• When all admin-1 rows fall inside one regional pack, that regional admin-1 set applies.
• When admin-1 rows span more than one regional pack, world-admin1-ne-v1 applies.
• Country codes must not be sent to an admin-1 geography set, and admin-1 codes must not be sent to world-country-ne-v1.

A subdivision code that resolves in one of the regional packs targets that pack for its row.

Properties

The shared block style, layout, and data properties also apply to Visualisation blocks.

States

State entries follow the shared state shape and support partial Visualisation overrides.

No states are currently available for Visualisation blocks.

Minimal Valid Example

{
  "id": "vis-1",
  "type": "visualisation",
  "component": "WordCloud",
  "datumReference": {
    "type": "datumReference",
    "referenceId": "queryResults"
  }
}