Quickly create personalized visuals showcase
In the Power BI embedded Quickly create personalized visuals showcase application, users can edit existing report visuals and create their own personalized visuals, even if they don't have previous Power BI experience. The showcase code demonstrates how to use the Power BI report authoring APIs to create and edit several types of visualizations at runtime. For more information about using the report authoring APIs, see the Report authoring overview.
Quickly create personalized visuals showcase experience
Contoso, a fictitious company, uses the Quickly create personalized visuals showcase to present a Power BI embedded report with several visualizations of their sales data. A column chart, area graph, bar chart, pie chart, and line graph show revenue and opportunities as functions of industry type, salesperson, and opportunity status.
The embedded report has a Create quick visual button that users can select to create new visuals based on the data.
Create a new quick visual
Report users can select the Create quick visual button anytime during their viewing session to create new visuals based on the Contoso sales data.
For example, if a user wants to see a column chart that shows Actual Revenue based on Opportunity Status, they select Create quick visual to open the Create quick visual dialog box. The dialog box, which is defined in the application code, contains an embedded report visual preview on the right.
In the Create quick visual dialog box, under Choose visual type, the user selects Column chart. Different fields and values are available depending on which visual type the user selected. For the column chart, the user selects Opportunity Status for the Axis field and Actual Revenue for Values. Optionally, they select Estimated Revenue for Tooltips.
After they fill out the Axis and Values fields, the user can select various formatting options, like whether to display actual values and labels. They can also write and format a title for the visual.
The embedded report preview in the dialog box shows the visualization as the user builds it.
When the visual is complete, the user selects Create, and the new visualization appears in the report.
A tooltip appears when a user hovers over a data point in visualizations. Since the user specified Estimated Revenue under Tooltips when they created the visual, that field's data appears in the tooltips. If the user doesn't specify a tooltip, only the axis and value data appear in the tooltip.
Change an existing visual
Report users can change any existing visual in the report by selecting the More options ellipsis (...) at the upper-right of the visual, and then selecting Change visual.
For example, a report user might want to change the Number of Opportunities by Industry area chart to a column chart, because the data isn't continuous. When the user selects Change visual, the Create quick visual dialog box opens, and the user can change any of the settings.
In this example, the user changed the visual type to Column chart. The data now displays as a column chart.
Quickly create personalized visuals showcase code
The code for implementing the showcase is in the PowerBI-Embedded-Showcases GitHub repository.
The application HTML code builds the embedded report container and elements, dialog boxes, text fields, and buttons.
The report JavaScript code defines the visualization types, handles commands and events, and performs all report embedding and interactions.
You can use the powerbi-report-authoring extension for the Power BI Client library to help easily and quickly author reports and visuals. For more information, see the report authoring overview.
For more information about creating visuals and binding them to data, see Create a visual. For more information about visual properties, see Format visual properties.
Create and configure visuals
You create Power BI visuals by using createVisual and specifying the visual type, such as barChart or pieChart. You then bind the visual type to properties, roles, fields, and data. The showcase visuals.js file defines the properties, data roles, data fields, and targets for the visual types this application supports.
In the index.js file, the following code creates an embedded visual inside the Create quick visual dialog box, and sets and applies its properties. For example, the legend property is enabled for pie chart visuals, but disabled for bar and column charts.
// Based on the state object, create a visual inside the modal
async function createVisualInsideTheModalInEditMode(visualType, dataRoles) {
// Create visual inside the modal
const newVisual = await visualCreatorShowcaseState.page.createVisual(visualType, getVisualLayout());
// Update state
visualCreatorShowcaseState.newVisual = newVisual.visual;
visualCreatorShowcaseState.visualType = newVisual.visual.type;
const visual = newVisual.visual;
const newVisualType = visual.type;
// Enable the legend property for pie chart
if (visualCreatorShowcaseState.visualType === "pieChart") {
visual.setProperty(propertyToSelector("legend"), { schema: schemas.property, value: true });
}
// Add properties to the created visual
Object.entries(visualCreatorShowcaseState.properties).forEach(property => {
let [propertyName, propertyValue] = property;
...
// Check the validity of the given property for the given visual-type and apply it to the visual
applyValidPropertiesToTheVisual(visual, newVisualType, propertyName, propertyValue);
});
// Disable the legend for the column and bar charts
if (visualCreatorShowcaseState.visualType === "columnChart" || visualCreatorShowcaseState.visualType === "barChart") {
visual.setProperty(propertyToSelector("legend"), { schema: schemas.property, value: false });
}
Change the visual type
In the Create quick visual dialog box, all existing editing fields are available as long as the selected visual type remains unchanged. When creating a new visual or changing visual type, the relevant editing fields become available after the user selects the new visual type.
The following code changes the visual type if the user edits a visual to change the type, for example from an area chart to a column chart. For more information about changing visual type, see Change the visual type.
const oldVisualType = selectedVisual.visual.type;
const oldVisual = selectedVisual.visual;
if (oldVisualType !== visualCreatorShowcaseState.visualType) {
// If visual-type is changed, remove all active data-fields on the visual
await removeAllActiveDataRoles(oldVisual, oldVisualType);
// Change the visual type
await oldVisual.changeType(visualCreatorShowcaseState.visualType);
}
Add the Change visual command to the More options menu
The report embedConfiguration uses the extend menu command API to add a changeVisual command to the report, which appears in the More options menu of each visualization.
let config = {
...
settings: {
...
extensions: [
{
command: {
name: "changeVisual",
title: "Change visual",
extend: {
visualOptionsMenu: {
title: "Change visual",
menuLocation: models.MenuLocation.Top,
The configuration also hides all the default, pre-existing Power BI More options menu commands, such as Export data and Sort. For more information about customizing visual commands, see Customize menu commands.
Handle the Change visual and Create quick visual selection events
The following code handles the Change visual command selection and Create quick visual button click events. The code listens for the command or button selection, and opens the Create quick visual modal dialog box to edit or create the visual.
// Listen for the commandTriggered event
baseReportState.report.on("commandTriggered", function (event) {
// Open the modal and set the fields, properties and title for the visual
openModalAndFillState(event.detail);
});
baseReportState.report.on("buttonClicked", function () {
// Show the modal to create the visual
openModalAndFillState();
});