|
| 1 | +--- |
| 2 | +title: Add Tableau Workbook Formatting |
| 3 | +layout: docs |
| 4 | +--- |
| 5 | + |
| 6 | +To help your dashboard extension match the look and feel of the dashboard in which it is placed, you can apply the formatting styles used in the workbook to the HTML elements in your extension. When the formatting changes in the workbook, the corresponding styles are updated in your extension. |
| 7 | + |
| 8 | +**In this section:** |
| 9 | + |
| 10 | +* TOC |
| 11 | +{:toc} |
| 12 | + |
| 13 | +---- |
| 14 | + |
| 15 | + |
| 16 | +## Apply Tableau classes to HTML elements |
| 17 | + |
| 18 | +Starting with the Dashboard Extensions API v1.7 library, and supported with Tableau 2021.4 or later, you can apply workbook formatting styles by specifying the class on the HTML elements in your extension. The specific Tableau classes to use are defined in the [`ClassNameKey`]({{site.baseurl}}/docs/enums/tableau.classnamekey.html){:target="_blank"} enum. |
| 19 | + |
| 20 | +| HTML style (string literal) | ClassNameKey enum| |
| 21 | +| :------------ | :---------- | |
| 22 | +| `tableau-dashboard-title` | `tableau.ClassNameKey.DashboardTitle` | |
| 23 | +| `tableau-story-title` | `tableau.ClassNameKey.StoryTitle` | |
| 24 | +| `tableau-tooltip` | `tableau.ClassNameKey.Tooltip` | |
| 25 | +| `tableau-worksheet` | `tableau.ClassNameKey.Worksheet` | |
| 26 | +| `tableau-worksheet-title` | `tableau.ClassNameKey.WorksheetTitle` | |
| 27 | + |
| 28 | + |
| 29 | +### As an HTML class |
| 30 | + |
| 31 | +To apply the formatting in the body of your HTML page to HTML elements, use the string literal `tableau-*` for the `ClassNameKey` enum. For example, to apply the worksheet title formatting you set the `class` for the HTML element in your extension (`h1`, `h2`, etc.) to `"tableau-worksheet-title"`. |
| 32 | + |
| 33 | +```html |
| 34 | +<h2 class="tableau-worksheet-title">Subheader, using tableau-worksheet-title class</h2> |
| 35 | + |
| 36 | +``` |
| 37 | + |
| 38 | +### In JavaScript code |
| 39 | + |
| 40 | +To reference the workbook formatting in your JavaScript code, use the enum directly. For example, to add the formatting used in the worksheet title, you could use the JQuery method (`.addClass`) to add the `tableau.ClassNameKey.WorksheetTitle` to an element on your page. The following example applies the formatting to a heading with the id `someTitle`. |
| 41 | + |
| 42 | +```javascript |
| 43 | + |
| 44 | +$('#someTitle').addClass(tableau.ClassNameKey.WorksheetTitle); |
| 45 | + |
| 46 | +``` |
| 47 | + |
| 48 | +You could also create a JavaScript function that has `ClassNameKey` as an parameter, and use that function to process and apply the formatting in some way. |
| 49 | + |
| 50 | +```javascript |
| 51 | + |
| 52 | +myFormattingFunction(tableau.ClassNameKey.WorksheetTitle); |
| 53 | + |
| 54 | +// does something with the worksheet title |
| 55 | + |
| 56 | +``` |
| 57 | + |
| 58 | +## Access information about the formatting styles in the workbook |
| 59 | + |
| 60 | +You can access the formatting used in a Tableau workbook from the `tableau.extensions.environment.workbookFormatting` property. The `workbookFormatting` property, `formattingSheets` contains an array of CSS properties for the workbook, organized by `ClassNameKey`. For example, if you wanted to view the formatting styles available using the Chrome DevTools, you could add the following JavaScript code and then view the results in the Console window by navigating the array. |
| 61 | + |
| 62 | +```javascript |
| 63 | + |
| 64 | +if (tableau.extensions.environment.workbookFormatting) { |
| 65 | + console.log(tableau.extensions.environment.workbookFormatting.formattingSheets); |
| 66 | +}; |
| 67 | + |
| 68 | +``` |
| 69 | + |
| 70 | +Or to just print out the formatting information in the Console window you could do something like the following: |
| 71 | + |
| 72 | +```javascript |
| 73 | + |
| 74 | +let formattingSheets = tableau.extensions.environment.workbookFormatting.formattingSheets; |
| 75 | +formattingSheets.forEach(function (formattingSheet) { |
| 76 | + console.log("The formatting sheet is " + formattingSheet.classNameKey + " " + JSON.stringify(formattingSheet.cssProperties)); |
| 77 | + }); |
| 78 | + |
| 79 | +``` |
| 80 | + |
| 81 | +## Set an event listener on workbook format changes |
| 82 | + |
| 83 | +You can set an event listener on changes to the formatting in the workbook. The new event type is `WorkbookFormattingChanged`. The `WorkbookFormattingChanged` event is triggered whenever the workbook formatting is changed in Tableau authoring mode. This includes changes in the font, the font size, whether it is bold, italic, or underlined, and changes in color. |
| 84 | + |
| 85 | +```javascript |
| 86 | + |
| 87 | +dashboard.addEventListener(tableau.TableauEventType.WorkbookFormattingChanged, (event) => { |
| 88 | + console.log(event.formatting); |
| 89 | + // take some other actions based on the change |
| 90 | +}); |
| 91 | + |
| 92 | +``` |
| 93 | + |
| 94 | +For more information about using event listeners, see [Events and Event Handling]({{site.baseurl}}/docs/trex_events.html). |
| 95 | + |
| 96 | +## What's Next |
| 97 | + |
| 98 | +* To see a working sample dashboard extension that uses workbook formatting, see the JavaScript [Formatting](https://github.com/tableau/extensions-api/tree/main/Samples/Formatting){:target="_blank"} sample in the Samples folder, or the TypeScript [Formatting](https://github.com/tableau/extensions-api/tree/main/Samples-Typescript/Formatting){:target="_blank"} sample in the Samples-Typescript folder. |
| 99 | + |
| 100 | +* For information about accessing the formatting styles in a workbook, see [workbookFormatting]({{site.baseurl}}/docs/interfaces/environment.html#workbookformatting){:target="_blank"} in the API reference documentation. |
0 commit comments