Reference

Component Configuration

Description of attributes for the component js-meta.xml file.

analytics__Dashboard Target

To allow the component to be used in Analytics dashboards, add this target to the list of targets.

<targets>
    <target>analytics__Dashboard</target>
<targets>

To customize how the component appears in Analytics dashboards, add a targetConfig to targetConfigs.

<targetConfigs>
    <targetConfig target="analytics__Dashboard">
    </targetConfig>
</targetConfigs>

<hasStep> tag

In an analytics__Dashboard target config, you can choose to include the <hasStep>true</hasStep> attribute.

<targetConfigs>
    <targetConfig target="analytics__Dashboard">
        <hasStep>true</hasStep>
    </targetConfig>
</targetConfigs>

This attribute indicates that your component requires a dashboard step to function as expected. With this tag, the dashboard builder UI prompts the user to attach an existing step or to create a step to an instance of the component. Components with an attached step have access to step specific API hooks like results and selection.

Measure and Dimension Attribute Data Types

Attributes specified in an analytics__Dashboard target config are displayed in the Analytics dashboard builder UI for configuration. In addition to the common data types, this target also supports Measure and Dimension data types for components with <hasStep>true</hasStep>. The dashboard builder is able to choose a column of the given data type from the results of the attached step.

<targetConfigs>
    <targetConfig target="analytics__Dashboard">
        <hasStep>true</hasStep>
        <property name="labelColumn" type="Dimension" label="Label Column" description="Segment label." required="true"/>
    </targetConfig>
</targetConfigs>

API Hooks Overview

API Hooks Details

Results

The results are rows returned by the query represented as an array of maps.

[
    {columnOne: 'one', columnTwo: 123},
    {columnOne: 'two', columnTwo: 456}
]

Metadata

Metadata describes the shape of the results using lists of column developer names organized into groups, numbers, and strings.

• Groups - Grouped dimensions. Typically, all grouped columns can be used together as a primary key for the row.
• Strings - All text fields, also known as Strings or Dimensions.
• Numbers - All numeric fields, also known as Measures.

{
    groups: [],
    strings: ['columnOne'],
    numbers: ['columnTwo']
}

selectMode

Returns the select mode specified for the associated step. Valid values are:

• single
• multi
• singlerequired
• multirequired
• none

isMultiSelect() {
    return this.selectMode.includes('multi');
}

selection

The current selection of the associated step as an Array of objects, with each object being one or more selected rows from results. Use the setSelection function to update the dashboard selection.

return new Map((this.selection ?? []).map((row) => [this.hash(row), row]));

setSelection

The setSelection function is a callback passed in that allows the component to update the attached step's selection in Analytics. In doing so, it potentially applies filters to the rest of the dashboard's contents depending on how the queries are configured.

this.setSelection(this.isMultiSelect() ? [...selectedRowsByHash.values(), row] : [row]);

getState and setState

Use getState to retrieve the current state of the dashboard. Use setState to modify the current state of the dashboard. Fetch and modify all the current selections, filters, and the currently viewed page. Use these functions to add custom logic and behavior that's not standard in the dashboard runtime.

if (!this.getState().pageId == this.targetPage) {
      this.priorPage = this.getState().pageId;
      this.setState({...this.getState(), pageId: this.targetPage, replaceState: true});
}

Learn more about selection syntax with Filter and Selection Syntax for Embedded Dashboards.

refresh

Use refresh to rerun either all the queries on the dashboard or a particular query. To rerun a specific query, use the config argument with the step id of the query.

this.refresh({step: this.step});

Custom Lifecycle Methods

stateChangedCallback

Use stateChangedCallback, a built-in callback method, to inform the component whenever the state of the dashboard changes. Use stateChangedCallback to compare the current state with the new state and then rerender if necessary.

stateChangedCallback(prevState, newState) {
  // perform comparison logic and set the new state to the current state to trigger a rerender of the component
  this.currentState = newState;
}

For an example of this callback in action, see the Breadcrumb javascript in the GitHub example repository.

This callback method is available in v55 and later.

Note