Configure report settings

Artikel
01/04/2023

By using the Power BI Client APIs, you can embed Power BI analytics in your application. When you use this client-side library to embed a Power BI report, you provide the API with information about that report.

You can use a configuration object to store information about your Power BI report. When you embed the report, you then pass that object to the API.

Besides giving the API access to the report, you can also use the configuration object to customize your report's appearance and behavior. For instance, you can adjust the filter visibility, navigation access, and location settings in the configuration object.

The following sections explain how to embed and configure Power BI content.

Provide configuration information

The IReportLoadConfiguration interface displays properties that a configuration object can supply to the Power BI Client APIs about a report:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

See Embed a report for an explanation of this interface's required parameters and for code examples showing how to embed a report.

Customize settings

The following sections describe how you can use the settings property to adjust the appearance and behavior of your embedded Power BI report. To update the report settings when the report is already loaded, use the report.updateSettings method. For more information, see Update report settings at runtime.

Panes

Control the appearance of all the panes in your Power BI report with a single panes property, as shown in the following code:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

From the following table, you can see which values each panes property supports:

Property	Visible	Expanded
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Filter pane

By default, the filter pane is visible. If you want to hide this pane, use the filterPaneEnabled property, as shown in the following code:

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Note

The panes property replaces the filterPaneEnabled property. To maintain backward compatibility, the filterPaneEnabled property still exists. However, you should avoid using these two properties together.

By default, the page navigation arrows are visible on embedded reports. To hide these arrows, use the navContentPaneEnabled property, as shown in the following code:

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Note

The panes property replaces the navContentPaneEnabled property. To maintain backward compatibility, the navContentPaneEnabled property still exists. However, you should avoid using these two properties together.

The page navigation pane appears at the bottom of the report, to use the new vertical pages pane you can set the position property:

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Note

You can't change the position of the page navigation pane using updateSettings.

Bars

Set the visibility of the action bar and status bar by using the bars property.

Action bar

The following code makes the action bar visible:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Alternatively, in view mode, it is also possible to use the actionBarEnabled URL parameter:

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Note

In view mode the action bar is only supported for the embed for your organization scenario.

For the action bar in view mode it’s recommended to enable UserState.ReadWrite.All permission for your Azure AD application. This permission is required to allow end users to add the report to their favorites, and for enabling personal bookmarks and persistent filters.

Status bar

The status bar holds the canvas zoom controller, which provides the ability to zoom on the canvas.

The following code makes the status bar visible:

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

Locale settings

Use the localeSettings property to specify the language and the formatting of the embedded report:

The language property in localeSettings consists of two parts of two letters each, separated by a hyphen:

language defines the language that Power BI uses for localization. Examples of languages include en (English), es (Spanish), and tr (Turkish).
locale defines the text formatting that Power BI uses for dates, currency, and other related content. Examples of locales include US (English), ES (Spain), and TR (Türkiye).

See Supported languages for a list of available languages and regions.

The following code assigns a specific values to these localeSettings:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Note

Locale settings cannot be changed after the report is loaded. To change the report locale settings, reset the iframe by calling powerbi.reset(element), and then embed the report again.

Transparent background

By default, the background of the embedded content is white with gray margins. If you prefer, you can give the embedded content a transparent background. Then you can apply the style you want to the HTML div element that contains the embedded content. The div element's styling then becomes visible.

Use this code to make the background of the embedded content transparent:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

Hyperlink click behavior

You can control the behavior of a hyperlink in a table, or matrix out-of-the-box visuals. By default, the hyperlink will open a new window.

The behavior modes that are available are listed below:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - The URL will be loaded into a new browsing context.
NavigateAndRaiseEvent - The URL will be loaded into a new browsing context, and will raise a dataHyperlinkClicked event.
RaiseEvent - Prevents the default behavior of URL click, and raise dataHyperlinkClicked event.

Use this code to change the behavior of links to raise an event:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

A dataHyperlinkClicked event fires when a hyperlink is clicked on an out-of-the-box table or matrix visuals and the behavior is either NavigateAndRaiseEvent or RaiseEvent.

report.on('dataHyperlinkClicked', () => {
    ...
});

For more information about handling events, see How to handle events.

Visual rendered events

You can listen to an event for each rendered visual. By default, the visual rendered events are disabled.

Use this code to make the visualRendered events triggered:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

A visualRendered event fires when a visual is rendered and the visualRenderedEvents is enabled on the report settings.

report.on('visualRendered', () => {
    ...
});

For more information about handling events, see How to handle events.

Note

Because visuals might render due to user interactions, it's recommended to turn on this event only when needed.

Error messages

If you'd like to display customized error messages in embedded reports, use the hideErrors property to hide the default Power BI embedded error messages. Your code can then handle error events in a way that fits your app design. See Override default error messages for more information on overriding default errors.

Use this code to hide default error messages:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Customize options

The following sections describe how you can use additional properties to further customize the appearance and behavior of your embedded Power BI report.

Default page

You can control which page of your embedded report appears initially. By default, the initial page is the page that you modified most recently, which was the active page the last time you saved the report. You can override this behavior by using the pageName property and supplying it with the name of the page you'd like to display. However, if no page with that name exists in Power BI, the request to open it fails.

The following code shows how to configure your app to display a specific page:

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

On load filters

You can control the filters that your app applies to an embedded report. By default, the report initially uses the filters that you saved to the report. However, you have two options if you want to adjust the filters:

Configure additional filters to use together with the saved filters. The following code shows how to use the filters property to append additional filters:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Replace the saved filters with a new set. The setFilters method provides a way to dynamically change a report's filters. If you use this method during phased embedding, you can override the filters that the report initially applies. For more information about constructing filters and using the setFilters method, see Control report filters.

On load slicers

You can control the state of the slicers that your app applies to an embedded report. By default, the API uses the slicers that you saved to the report. However, you can use the slicers property to modify the state of the existing slicers, as the following code demonstrates:

embedConfig = {
    ...
    slicers: slicerArray,
};

See Control report slicers for more information about modifying the state of a slicer.

On load bookmark

By using the bookmark property, you can apply a bookmark to an embedded report. See Bookmarks for more information about using bookmarks to capture the currently configured view of report pages.

You can specify the bookmark to use by providing either the bookmark name or the state. If you provide the bookmark name, your Power BI report needs to contain a saved bookmark with that name.

The bookmark property is of type IApplyBookmarkRequest. The following code shows this type's definition:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

This code shows how to specify a bookmark by name:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

This code shows how to specify a bookmark by state:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Themes and high-contrast mode

You can control the theme and contrast level that your embedded content uses. By default, any content that you embed appears with the default theme and with zero contrast. You can override this behavior by configuring a specific theme or contrast level. For more information about themes, see Apply report themes.

The contrast modes that are available are listed below:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Use code similar to the following lines to configure a specific theme:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

The following code shows how to override the default contrast level, None:

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Note

The API cannot apply a theme and a contrast level at the same time. If you configure both properties, the API uses the contrast level that you specified but ignores the theme setting.

Zoom level

To learn more about adjusting the report zoom level check the accessibility document.

Open in edit mode

By default, the report that you embed appears in view mode. However, you can override this behavior to open the report in edit mode. You can also switch between modes.

Configure edit mode

To open an embedded report in edit mode, use the viewMode property together with the permissions property.

You can assign the viewMode property the following values:

View - Opens the report in view mode.
Edit - Opens the report in edit mode.

You can assign the permissions property these values:

Read - Users can view the report.
ReadWrite - Users can view, edit, and save the report.
Copy - Users can save a copy of the report by using Save As.
Create - Users can create a new report.
All - Users can create, view, edit, save, and save a copy of the report.

When you configure content to open in edit mode, assign the permissions property a value that is appropriate for editing, as the following code demonstrates:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Note

The permissions value that you configure only works if the embed token that you acquired has sufficient privileges. For more information about embed tokens, see Create the embed token.

Switch between edit and view modes

Besides specifying a mode for embedded content to start in, you can also switch between edit and view modes dynamically.

If the content is in edit mode, and you'd like to switch to view mode, use this JavaScript code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

If the content is in view mode, and you'd like to switch to edit mode, use this JavaScript code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

Considerations and limitations

Consider the following points when you configure embedded content:

The page navigation position can't be changed when the action bar is visible. Learn more about the action bar.
When you use the bars property in the setting property, as described in Bars, the API only applies your configuration if the embedded content is in edit mode. If your content is in view mode, the API ignores the bars setting.
When you use the viewMode property to display content in edit mode, you need to take two additional steps:
- Configure a permission level with the permissions property. That permission level needs to give the user appropriate access for modifying content. For instance, if you assign a permissions value of Read, the user will not be able to edit content.
- Ensure that the embed token that you generate has privileges that support editing. For instance, if you acquire a token with an accessLevel value of view, the API will fail to display content in edit mode.
The panes property replaces the following settings properties:
- filterPaneEnabled
- navContentPaneEnabled
If you use the panes property to configure filter or page navigation visibility, do not use the filterPaneEnabled or navContentPaneEnabled property in your app.
The API can't apply a theme and a contrast level to embedded content at the same time. If you configure both options by using the theme and contrastMode properties, the API uses your contrastMode value with the embedded content. However, the API ignores the theme setting.
If you want to apply a bookmark to an embedded report, you can use the bookmark property. If you supply a bookmark name with that property, the API can only use the bookmark if one exists with that name. Likewise, if you use the pageName property to specify an opening page, the API can only display that page if one exists with the given name. Before configuring a name, consider using an accessor method, such as the Report getPages method, to check whether a component exists with that name.

Configure report settings

Provide configuration information

Customize settings

Panes

Filter pane

Page navigation pane

Bars

Action bar

Status bar

Locale settings

Transparent background

Hyperlink click behavior

Visual rendered events

Error messages

Customize options

Default page

On load filters

On load slicers

On load bookmark

Themes and high-contrast mode

Zoom level

Open in edit mode

Configure edit mode

Switch between edit and view modes

Considerations and limitations

Next steps

Aanvullende resources