Embed Configuration Details

The embed configuration is an object that describes what and how to embed.

export interface IReportLoadConfiguration {
  accessToken: string;
  bookmark?: IApplyBookmarkRequest;
  filters?: ReportLevelFilters[];
  id: string;
  pageName?: string;
  permissions?: Permissions;
  settings?: ISettings;
  tokenType?: TokenType;
  viewMode?: ViewMode;
}

export interface IReportCreateConfiguration {
  accessToken: string;
  datasetId: string;
  settings?: ISettings;
  tokenType?: TokenType;
}

export interface IDashboardLoadConfiguration {
  accessToken: string;
  id: string;
  pageView?: PageView;
  tokenType?: TokenType;
}

export interface ITileLoadConfiguration {
  accessToken: string;
  id: string;
  dashboardId: string;
  tokenType?: TokenType;
  width?: number;
  height?: number;
}

This object is used when calling powerbi.embed(element, embedConfiguration). The type is needed to know what type of embed to instantiate and the embedUrl is needed to set the source of the iframe.

When embedding, the minimum requirements are to have a type, embedUrl, accessToken and id. These can be specified in the embed configuration object as shown above or as attributes on the element which is why these properties are optional here. Read more about AccessToken and TokenType in Embedding Basics section.

There are additional properties settings, pageName, and filters.

Settings

All settings can be provided as attributes prefixed with powerbi-settings- on the containing HTML element.

1. Filter Pane

   FilterPane is enabled/visible by default but can be disabled/hidden by adding the attribute on the element or specifying the setting in the embed configuration:

   <div ... powerbi-settings-filter-pane-enabled="false"></div>

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

2. Page Navigation

   Page navigation is enabled/visible by default but can be disabled/hidden by adding the attribute on the element or specifying the setting in the embed configuration:

   <div ... powerbi-settings-nav-content-pane-enabled="false"></div>

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

3. Locale Settings

   Locale settings are used to define the language and the formatting of the embedded report/dashboard. language defines the language that powerBI uses for localization. formatLocale defines the text formatting that powerBI uses for dates, currency etc.

   var embedConfig = {
   	...
   	settings: {
   		localeSettings: {
   			language: "en",
   			formatLocale: "es"
   		}
   	}
   };

4. Apply Bookmark on load Using bookmark on load feature you can apply a bookmark by name or by bookmark state. Applying a bookmark by name assumes you have a bookmark with the given name saved in your report. bookmark parameter is of type IApplyBookmarkRequest, which is defined as follows:

   type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;
   
   interface IApplyBookmarkStateRequest {
       state: string;
   }
   
   interface IApplyBookmarkByNameRequest {
       name: string;
   }

Examples

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

```javascript
    let bookmarkState = "H4sIAAAAgCZmVuS...G5A6E5f62+EfgTkoWAAA=";
let embedConfig = {
	...
	bookmark: {
		state: bookmarkState
	}
};
```

Options

1. Default Page By default the report will load the last modified page (i.e. the active page during the last save); however, this can be overwritten by specifying a specific page name.

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

2. Pre-applied Filters By default the report will load with the filters that are saved to the report; however, you can programmatically apply additional filters by setting the filters property. For more information about filters visit https://github.com/Microsoft/PowerBI-JavaScript/wiki/Filters.

   var embedConfig = {
     ...
     filters: [...]
   };

3. Opening in Edit mode By default the report will loaded in View mode. To open a report in Edit mode, pass viewMode parameter as Edit and give relevant permissions.

   var embedConfig = {
     ...
     permissions: models.Permissions.All
     viewMode: models.ViewMode.Edit

viewMode possible values

View - Opens report in View mode.

Edit - Opens report in Edit mode.

permissions possible values

Read - Allows view report only.

ReadWrite - Allows view, Edit and Save report.

Copy - Allows Save a copy of a report using Save As.

Create - Allows creating a new report.

All - Allows everything.

Note: permission passed in Load configuration works only if Embed Token acquired with relevant privileges.

Switching between View and Edit mode

You can use the following JavaScript to switch into view mode, if you are in edit mode

```javascript
// Switch to view mode.
report.switchMode("view");
```

You can use the following JavaScript to switch into edit mode, if you are in view mode

```javascript
// Switch to edit mode.
report.switchMode("edit");
```