Building Reusable Components in Canvas Dashboard

With Canvas Dashboard, you can define reusable visuals and components within the dashboard. This doc goes through a simple example to demonstrate the reusability capability.

Reusable Component Example

The Setup

Let's say you have a dashboard with the following syntax:

my_canvas_dashboard.page.aml

Dashboard {
  // metadata
  title: 'My Canvas Dashboard'
  description: 'My new canvas dashboard'

  // collection of blocks
  block t1: TextBlock {
    content: @md
      Hello world
    ;;
  }

  block f1: FilterBlock {
    type: 'field'
    label: 'User role'
    source: FieldFilterSource {
      dataset: 'tenant_user'
      field: ref('public_users', 'role')
    }
  }

  block v1: VizBlock {
    label: 'A pie chart'
    viz: PieChart {
      dataset: 'tenant_user'
      legend: ref('public_users', 'role')
      series {
        field {
          ref: ref('public_users', 'id')
          aggregation: 'sum'
        }
      }
    }
  }

  // layout
  view: CanvasLayout {
    width: 1200
    height: 1200
    margin: 10
    block f1 {
      position: pos(600, 0, 300, 70)
    }
    block v1 {
      position: pos(0, 70, 600, 600)
    }
  }
}

Reusing Block and Filters

You can reuse block and filter with AML Constant like so:

my_reusable_blocks.aml

const myviz = VizBlock {
  label: 'A pie chart'
  viz: PieChart {
    dataset: 'tenant_user'
    legend: ref('public_users', 'role')
    series {
      field {
        ref: ref('public_users', 'id')
        aggregation: 'sum'
      }
    }
  }
}

const myfilter = FilterBlock {
  type: 'field'
  label: 'User role'
  source: FieldFilterSource {
    dataset: 'tenant_user'
    field: ref('public_users', 'role')
  }
}

Then you can create a new dashboard

my_canvas_dashboard.page.aml

Dashboard {
  title: 'My reused Dashboard'

  block f1: myfilter
  block v1: myviz
...
}

Parameterizing components

You can also use Func to parameterize your component, like so:

my_functions.aml

Func myvizBlockWithDataset(dataset: String) {
  VizBlock {
    label: 'A pie chart'
    viz: PieChart {
      dataset: dataset
      legend: ref('public_users', 'role')
      series {
        field {
          ref: ref('public_users', 'id')
          aggregation: 'sum'
        }
      }
    }
  }
}

and use it like this

my_canvas_dashboard.page.aml

Dashboard {
...
  block v1: myvizBLockWithDataset('tenant_user')
...
}

Reused blocks

A Reused Block is an Analytics Block that is explicitly and programmatically defined by users to be used in Canvas Dashboards.

Why do you need Reused Blocks?

Normally, when you use the Visual Editor to develop Canvas Dashboards, Holistics takes care of code generation under the hood to ensure that the generated code correctly reflects how your dashboard works. There are multiple ways to programmatically achieve the same outcome, so we pick a particular path to generate code so that you don't have to worry about it.

But there are cases where you may want to explicitly define Analytics Blocks as-code yourself:

• Build Reusable Components in Canvas Dashboard
• Build a Dashboard with Multiple Similar Charts
• Build Reusable Dashboards for Multiple Clients

What happens when you define Reused Blocks?

When you explicitly define an Analytics Block as a reusable piece of code, it becomes a Reused Block which cannot be edited using the Visual Editor. You must switch to code mode and edit the code yourself. This behavior aims to avoid accidentally replacing user-defined code with auto-generated code.