Vega-Lite MCP Server

[ { "title": "Page Not Found", "url": "https://deneb.guide/docs/", "content": "Page Not FoundWe could not find what you were looking for.Please contact the owner of the site that linked you to the original URL and let them know their link is broken.", "category": "introduction", "source": "deneb" }, { "title": "Getting Started", "url": "https://deneb.guide/docs/getting-started", "content": "Getting StartedVersion: 1.8On this pageGetting Started Installing from AppSource​ Deneb is available in AppSource, and this is the most straightforward way of getting started and staying up-to-date with the latest versions. If you like Deneb, please leave us a review - we'd love to know how you're getting on! Within Power BI Desktop​ To add: in Power BI Desktop, choose Insert > More visuals > From AppSource in the ribbon, e.g.: Or by clicking the ellipsis in the Visualizations pane and choose Get more visuals, e.g.: In the Power BI Visuals dialog, search for Deneb - a shortlist of visuals will be displayed. Click on Deneb in the shortlist to open the visual. Click the Get It Now button to ad to your report. After a short time, Deneb will be visible in your Visualizations pane, e.g.: You're ready to start creating. Standalone Version​ Because Deneb is certified, there are certain restrictions imposed upon it. If you wish to use features such as loading images from remote URLs, you will need to download the standalone version. Note that the standalone version is not tied to AppSource and will require you to update manually in the event of new versions being published. This can be mitigated by setting it up as an organizational visual if you are using across many reports. The latest version is published via Releases in Deneb's GitHub repository. The packaged .pbiviz file is available in the Assets section for a particular release. You can also use this link to jump straight to the latest release page. Trust Your SourcesPlease be careful when installing custom visuals from unknown or unsolicited sources. I can assure you that our intentions are honorable but you should exercise caution around your data. If you have any doubts, then work with your admins to ensure that all the necessary checks and balances are carried out. Identification​ The standalone build can be identified by its greyscale version of the regular Deneb icon, e.g.: The landing page also specifies the standalone version, e.g.: Early Access Build Channels​ Due to AppSource submission being a lengthy process, users wishing to trial or feed back on early-access releases can find more information about installing these builds here.Edit this pagePreviousIntroductionNextSimple Worked ExampleInstalling from AppSourceWithin Power BI DesktopStandalone VersionEarly Access Build Channels", "category": "getting-started", "source": "deneb" }, { "title": "Simple Worked Example", "url": "https://deneb.guide/docs/simple-example", "content": "Getting StartedSimple Worked ExampleVersion: 1.8On this pageSimple Worked Example In the following pages, we'll create a simple bar chart, using the visual, some data, an inbuilt template and Vega-Lite. Our finished visual is the bar chart on the left: Download this workbook Our Starting Data​ From the sample workbook, we'll use a single column and measure. Here's how this looks in raw form: Here, the [City] column represents a nominal category, and [Mean Temperature] is a simple measure that calculates the average temperature value for the given row context. Think with TablesTry to think about the dataset you wish to add to a Deneb visual in terms of how it will work as a table visual. This will help to understand the granularity of the dataset, and help to \"think visually\" when it comes to creating marks and layouts. Adding the Visual​ No Visual in your Report?If you need assistance with this, refer to the Getting Started page. Once you have added Deneb to your report, you should see it in the Visualizations pane, eg.: You can then click the visual to add it to the report canvas, e.g.: Adding the Data​ We'll now add the [City] column and [Mean Temperature] measure to Deneb's Values data role, e.g.: At this point, we need to create a specification, which is required to instruct Vega-Lite (or Vega) how your visualization should be rendered. Dataset requirementsThere is a limitation with custom visuals where at least one measure needs to be present in the visual dataset for it to be able to persist properties back to the report for retrieval later on. Opening the Visual Editor​ We can now open the Visual Editor by selecting the visual header (...) and then Edit, e.g.: This will display the Visual Editor in focus mode, and the Create New Specification dialog will be shown, e.g.: Can't See the Dialog?If you accidentally dismiss the dialog, or it doesn't show, you can bring it up by clicking on the New Specification button on the command bar, or using [Ctrl + Alt + N] Selecting the Template​ Using Vega or Vega-Lite requires a specification to be written using JSON. You can either select the [empty] template to begin editing with a bare-minimum specification with the dataset bound to it, or use a predefined template. Let's choose Create using... > Vega-Lite > Interactive bar chart template by clicking on it. Note that we now get some additional details about the template, as well as some required placeholders: Assigning Placeholders​ This template expects two placeholders: one for the the category axis and another for the measure axis. As we've already added our data, we can see these are already available in the dropdown lists, e.g.: In our case, we'll add City to the Category placeholder. About Data TypesYou can choose either the column or the measure - the recommended data type is shown next to each one so that you can visually confirm the right type of field to bind to the placeholder. Using an different type might work, but be prepared to have to make some changes afterwards if you proceed with this.Deneb can only see columns or measures added to the Values data role. This is a limitation of visuals in Power BI so that they cannot know more about your data model than they are supposed to. You can add or swap out a column or measure if it's not the one you want and the dropdown list will update accordingly. Next, we'll click on the Measure placeholder and select the Mean Temperature measure: Creating the Initial Specification​ Now that all placeholders have been filled, the Create button is enabled: Clicking on this will show the visual specification in the Visual Editor with our assigned placeholders, e.g.: Reviewing Generated Specification​ In our editor's Specification tab, we'll now have the following Vega-Lite JSON specification: Generated Specification{ \"data\": { \"name\": \"dataset\" }, \"layer\": [ { \"mark\": { \"type\": \"bar\", \"opacity\": 0.3, \"tooltip\": true }, \"encoding\": { \"x\": { \"field\": \"Mean Temperature\" } } }, { \"mark\": { \"type\": \"bar\", \"tooltip\": true }, \"encoding\": { \"x\": { \"field\": \"Mean Temperature__highlight\" }, \"opacity\": { \"condition\": { \"test\": { \"field\": \"__selected__\", \"equal\": \"off\" }, \"value\": 0 }, \"value\": 1 } } } ], \"encoding\": { \"y\": { \"field\": \"City\", \"type\": \"nominal\" }, \"x\": { \"type\": \"quantitative\", \"axis\": { \"title\": \"Mean Temperature\" } } }} This breaks down as follows: There's a data object, which has a mapping of \"dataset\" (lines 2-4). This is required for the specification, instructs that our visual's dataset should be used and should be left as-is. Refer to the Dataset page for more details on how this works. We have a layer view, which allows us to superimpose chart elements (lines 5-39). Within this layer, we have: One bar mark for each data point (lines 6-17). The width (x encoding channel) of this bar is bound to our Mean Temperature measure (lines 13-15). We're displaying a tooltip for this mark (line 10). This is used to display original values in the event of a cross-hig", "category": "getting-started", "source": "deneb" }, { "title": "Visual Editor", "url": "https://deneb.guide/docs/visual-editor", "content": "Getting StartedVisual EditorVersion: 1.8On this pageVisual EditorThe Visual Editor is used to define your specification, configuration and any other options. Opening the Editor​ The Visual Editor is only available when your report is in edit mode - when you're editing in Power BI Desktop or in the Service. If the report is being viewed in the Power BI Service or other application, then it is not eligible for editing and any such options will be unavailable to your end-users. To use the editor, your visual first needs some data, so please ensure that you have added any appropriate columns or measures to the Values data role. Once data has been provided, the Visual Editor is accessed by selecting the visual header (...) and then Edit, e.g.: This will put the visual into focus mode and display the Visual Editor for you to begin creating or amending your specification. Finding your Way Around​ The Visual Editor has 3 main components, or panes: Command Bar - for performing actions on your visual and the editor. Editor Pane - for creating your visual's definitions. Preview Area - for seeing what your visual will look like in your report. Debug Pane - for assisting with the development and refinement process. Here's One We Made EarlierWe're showing a pre-built specification here; if this is your first time opening the editor in a new visual, then the New Specification dialog will be visible, to help you get started. Refer to the Simple Worked Example page for an example of this functionality, or the New Specification section below for more details. The Command Bar​ The Command Bar contains the following operations (from left to right): Specification Editor pane (Ctrl + Alt + 1)​ Selecting this option will display the Specification Editor pane. You can read more about this in the Specification Editor Pane section below. Config Editor pane (Ctrl + Alt + 2)​ Selecting this option will display the Config Editor pane. You can read more about this in the Config Editor Pane section below. Settings pane (Ctrl + Alt + 3)​ Selecting this option will display the Settings pane. You can read more about this in the Settings Pane section below. Apply Changes (Ctrl + Enter)​ Selecting this option will apply any changes you have made in either the Specification or Config and update your visual. This option is disabled if you have Auto-Apply enabled (see below). Apply OftenIf you exit focus mode (and out of the Visual Editor) any unapplied changes may not be saved, so please ensure that you apply changes before returning to the standard view. Refer to the Unapplied Changes section below for more details as to how you can mitigate this. Auto-Apply Changes as you Type (Ctrl + Shift + Enter)​ Selecting this option will apply changes to the Specification or Config editors as you type them. Enabling this option will disable the Apply command. Consider PerformanceWhilst this option is convenient for seeing changes take effect immediately, it can have negative performance implications if you're working with a large number of data points or elements within your visualization. Please refer to the Performance Considerations page for further details on potential risks and mitigation approaches. New Specification (Ctrl + Alt + N)​ Selecting this option will open the Create New Specification dialog. The dialog can be used to replace the current Specification and Config with either an bare-minimum set of JSON for each, or you can choose from a number of simple templates to get started. Templates are currently packaged in with the visual and it's not yet possible to import them, although hopefully this will be something we can work on bringing in later on. First Time UseThis dialog is also displayed by default if this is the first time opening the Visual Editor for any new instance of Deneb that you add to the report canvas. Generate JSON Template (Ctrl + Alt + E)​ Selecting this option will open the Generate JSON Template dialog. The dialog can be used to create an exportable version of the your specification. Refer to the appropriate section in the Templates page for more information on usage. Theme Toggle (Ctrl + Shift + Alt + T)​ Selecting this option will toggle the theme of the Visual Editor between light and dark modes. By default, this will not affect the preview area, which will always attempt to mimic the background color of the report canvas. You can disable this in the Preview Area settings if you wish to see the visual in a consistent theme. Help (Ctrl + Alt + H)​ Selecting this option will cause Power BI to confirm you wish to open the link to this documentation site. Selecting OK will open it in a new browser tab. Editor Pane​ The Editor Pane is where you will edit your specification, config and apply any other settings you need to. Resizing the Editor Pane​ The Editor Pane can be resized, or collapsed if you wish to allocate more space on the screen for your Preview and/or Debug panes. Some points to note: Use [Ctrl + Alt + Space]", "category": "getting-started", "source": "deneb" }, { "title": "Dataset", "url": "https://deneb.guide/docs/dataset", "content": "Getting StartedDatasetVersion: 1.8On this pageDatasetAny data you add to the visual's Values data role is automatically bound to an internal dataset named dataset in the Vega or Vega-Lite view. This will update dynamically as you add or remove columns and measures, or the number of rows in the dataset changes (e.g. filter context). Linking Visual Data to A Specification​ Even though this is passed through from Power BI, a specification needs to contain a reference to the named dataset, otherwise the values cannot be encoded when the specification is parsed. You should always ensure that a specification contains the following content for this to work: { ... \"data\": { \"name\": \"dataset\" } ...} { ... \"data\": [ { \"name\": \"dataset\" } ] ...} The visual's starter templates all follow this approach, so if in doubt, create a new specification using the [empty] template as a boilerplate. Grain / Row Context​ Internally, the visual handles its dataset in much the same way as a core table, i.e. the number of rows in the dataset is equivalent to the combination of all unique values across all columns and measures added. Let's say that we have the following data in our visual: If you're used to working with JSON, a representation similar to the following JSON output is patched into the specification when it is parsed: { \"dataset\": [ { \"City\": \"Auckland\", \"Mean Temperature\": 14.62 }, { \"City\": \"Christchurch\", \"Mean Temperature\": 9.49 }, { \"City\": \"Dunedin\", \"Mean Temperature\": 6.83 }, { \"City\": \"Hamilton\", \"Mean Temperature\": 13.27 }, { \"City\": \"Lower Hutt\", \"Mean Temperature\": 12.12 }, { \"City\": \"North Shore\", \"Mean Temperature\": 14.62 }, { \"City\": \"Tauranga\", \"Mean Temperature\": 12.99 }, { \"City\": \"Waitakere\", \"Mean Temperature\": 14.62 }, { \"City\": \"Wellington\", \"Mean Temperature\": 12.12 } ]} Additional Fields​ When using the Data Pane to inspect your dataset, or looking at a mark's datum with tooltips, you will see additional fields that are not present in your data model. Deneb will create these additional fields when processing your data. This can be to provide assistance with interactivity scenarios, particularly when it comes to working with Cross-Filtering or Cross-Highlighting as well as for giving you access to dynamic format strings that might be applied at a row level. To understand more about what they mean, and how you can work with them, please refer to the appropriate section of documentation. Referencing Columns and Measures​ Wherever you need to reference a column or a measure in your specification, you should use its display name from the Values data role rather than those from the data model. If you rename or remove a column or measure, please remember to update your specification accordingly. Re-Mapping Encoded FieldsIf a renamed/removed field is detected in any encodings or expressions used in your specification, the Edit Specification Field Mapping dialog will be automatically displayed. 'Special Characters' in Column and Measure Names​ You might use all kinds of characters in your data model when naming columns or measures. However, Vega and Vega-Lite (and JSON) have some specific considerations to make with certain characters in field binding and expressions, notably ., [, ], \\ and \". In these cases, Deneb will replace occurrences of these characters with an underscore (_) when they are passed into the visual dataset. By doing this, we avoid placing the onus on you, the author to remember how to escape them using the rules in the linked documentation above. To further illustrate, let's assume we have this measure: Using this in a specification's field encoding would need to substitute the . with an underscore as follows: { ... \"x\": { \"field\": \"$ Sales_Current\", \"type\": \"quantitative\" } ...} It is recommended that if you're passing in measures or columns containing special characters and do not wish for this behavior to occur, then rename them in the Values data role so that they are not passed through to the dataset. Augmenting Other Datasets​ In the case of a Vega specification, you can potentially add further data objects to the array, and Vega-Lite specifications can also contain layer-specific datasets (or multiple named ones) but bear the following in mind: AppSource certified visuals are not permitted to bring in data or resources from external locations. To this end, loading external files is not permitted in the visual. You can attempt this in the standalone version of the visual, but loading data from remote endpoints is subject to CORS restrictions due to security restrictions in all Power BI custom visuals. You can read more about this here. As such, it is recommended that you regard the named \"dataset\" source as where all data for your specification should come from in terms of your data model. Considerations for Transforming Data​ Both Vega and Vega-Lite support the concept of transforms, which ultimately mutate the data from its initial state. Whilst this approach may be necessary to ", "category": "getting-started", "source": "deneb" }, { "title": "Keyboard Shortcuts", "url": "https://deneb.guide/docs/keyboard", "content": "Getting StartedKeyboard ShortcutsVersion: 1.8On this pageKeyboard ShortcutsMost operations in the Visual Editor have corresponding keyboard shortcuts, and a number are mentioned in their corresponding area. However, its always good to see them in one place! Need A Specific Shortcut?Please create an issue in the GitHub repo with what you're missing and we'll see if we can get it added :) Editor Pane​ FunctionShortcutExpand or collapseCtrl + Alt + SpaceNavigate to Specification paneCtrl + Alt + 1Navigate to Config paneCtrl + Alt + 2Navigate to Settings paneCtrl + Alt + 3Apply ChangesCtrl + EnterToggle Auto-ApplyCtrl + Shift + EnterNew SpecificationCtrl + Alt + NGenerate JSON TemplateCtrl + Alt + EHelpCtrl + Alt + H In-Editor​ Deneb utilizes Monaco Editor for JSON editing, which comes with its own keyboard shortcuts and can help you quite considerably in-terms of productivity. You can view a list of shortcut keys by accessing the command palette, either from the context menu (right-clicking the editor), or pressing Ctrl + F1, e.g.: Context menu​ Command Palette​ Some useful commands are: FunctionShortcutFormat documentCtrl + Alt + RToggle line commentCtrl + /Toggle block commentShift + Alt + AFindCtrl + FReplaceCtrl + H Debug Pane​ FunctionShortcutSet view to Data PaneCtrl + Alt + 7Set view to Signals PaneCtrl + Alt + 8Set view to Logs PaneCtrl + Alt + 9Expand or collapse paneCtrl + `Zoom preview out by 10%Ctrl + Alt + Minus(-)Zoom preview in by 10%Ctrl + Alt + Plus(+)Zoom preview to actual sizeCtrl + Alt + 0Zoom preview to fit available spaceCtrl + Alt + *Edit this pagePreviousDatasetNextFormatting ValuesEditor PaneIn-EditorDebug Pane", "category": "getting-started", "source": "deneb" }, { "title": "Formatting Values", "url": "https://deneb.guide/docs/formatting", "content": "Deeper ConceptsFormatting ValuesVersion: 1.8On this pageFormatting Values Default Formatting Behavior​ When it comes to formatting values (if you're just using simple encodings), then Vega or Vega-Lite will use its own deterministic behavior to figure out things like decimal precision or other elements. You can provide your own overrides to these wherever they are used. Vega and Vega-Lite both use the D3 formatting convention for numbers and date & time values (incidentally, so does Charticulator). Power BI has its own syntax, which is probably your preference for applying any customized formatting strings into a specification. To ensure correct compatibility with Vega and Vega-Lite, particularly if you're bringing examples in (or even looking to take them out!) Deneb will use the D3 convention by default, but there's some help at hand if that's not your preference. Power BI Custom Formatter​ If you prefer working with Power BI format strings, Deneb has custom format types named pbiFormat and pbiFormatAutoUnit that you can use in lieu of the D3 format convention. Vega-Lite Implementation​ In Vega-Lite, we can specify \"pbiFormat\" as a formatType wherever you're specifying a format. Quantitative Axis Example​ Let's say we have a simple bar chart that uses the Power BI financial sample dataset, which shows [$ Sales] for each [Country]: { \"data\": { \"name\": \"dataset\" }, \"mark\": { \"type\": \"bar\" }, \"encoding\": { \"y\": { \"field\": \"Country\", \"type\": \"nominal\" }, \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} And this will result in the following output: That's a lot of zeroes! What might be nicer is if his were a little easier to read. If we want to use a Power BI format string for this, we can modify the specification as follows to show values in $bn to one decimal place (changes highlighted): { ... \"encoding\": { ... \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\", \"axis\": { \"format\": \"$#0,,,.0bn\", \"formatType\": \"pbiFormat\" } } }} This results in something a little more human-readable: ​ Vega-Lite's format property is extensibleThe format property can also expect an object instead of a string. If you use an object for the pbiFormat or pbiFormatAutoUnit format types, you can use an object that can include any of the optional ValueFormatterOptions properties from Microsoft's formatting library for custom visuals. The following example is synonymous with the above one:{ ... \"encoding\": { ... \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\", \"axis\": { \"format\": { \"format\": \"#0.0\", \"value\": 1e9 // 1 billion }, \"formatType\": \"pbiFormat\" } } }} Quantitative & Temporal Axes Example​ If instead, we had a line chart using the same dataset, but this time we wanted to plot [$ Sales] by [Date] then we could express this as follows: { \"data\": { \"name\": \"dataset\" }, \"mark\": { \"type\": \"line\" }, \"encoding\": { \"x\": { \"field\": \"Date\", \"type\": \"temporal\" }, \"y\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} And here's how it looks out of the gate: We could use a similar approach as above for both axes, to get them how we want (changes highlighted): { ... \"encoding\": { \"x\": { ... \"axis\": { \"format\": \"MMM yyyy\", \"formatType\": \"pbiFormat\" } }, \"y\": { ... \"axis\": { \"format\": \"$#0,,,.0bn\", \"formatType\": \"pbiFormat\" } } }} And now, we have both axes formatted as we like: Vega Implementation​ If using Vega, you'd call the custom formatter in lieu of the format expression, e.g. for an axis tick label: { ... \"axes\": [ { ... \"encode\": { \"labels\": { \"update\": { \"text\": { \"signal\": \"pbiFormat(datum.value, '$#0,,,.0bn')\" } } } } }, ... ], ...} Locale-Awareness​ If using the pbiFormat formatter, Deneb currently will resolve your locale according to your Power BI configuration for any values. For example, we can view the live chart example from above en français (fr-FR), and the formatting strings will work as expected: Overriding User Locale​ If you wish to specify a different local to Power BI's one (for example, you wish values to be normalized to the same currency for your users irrespective of location), you can either override this using the locale property of a specification's config (V | VL), or manually specify a valid Power BI locale within the options.cultureSelector property in an expression function for pbiFormat (more on this below). Auto Formatting with pbiFormatAutoUnit​ Many Power BI visuals contain an Auto unit type when applying properties. Deneb also contains pbiFormatAutoUnit as a type that mimics this behavior, e.g.: { ... \"encoding\": { ... \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\", \"axis\": { \"formatType\": \"pbiFormatAutoUnit\" } } }} You can still use a format property as normal to specify a specific format string to use in conjunction with the resolved value; this just illustrates that you can omit it and get numbers formatted to their nearest degree of scale with minimal overhead with this format type. pbiFormat Expression Function Full Implementation Details​ When using pbiFormat in an expression functio", "category": "concepts", "source": "deneb" }, { "title": "Scrolling and Overflow", "url": "https://deneb.guide/docs/scrolling-overflow", "content": "Deeper ConceptsScrolling and OverflowVersion: 1.8On this pageScrolling and Overflow By default, Deneb will do its best to fit simple specifications to the visual container. However, there are many scenarios that can and will cause the displayed visual to overflow this container. Such scenarios can include setting the explicit height and/or width of your viewport, working with facets or repeating views, or using an explicit step size for a scale. On the Report Canvas​ Let's use the step size as an example to demonstrate how this looks. Here, we have too many values on our y-axis, causing our visual to overflow vertically: Configuring Scrollbar Appearance​ The Scrollbars formatting card in the Rendered visual menu in Power BI's formatting pane provides some customization options for the scrollbars: Scrollbar color allows you to tailor the displayed color of the scrollbar. Scrollbar opacity (%) allows you to tailor the opacity of the scrollbar. Scrollbar radius (px) allows you to tailor the corder radius of the scrollbar handle. In the Visual Editor​ When viewing your specification in the Visual Editor's preview area, this is shown relative to the viewport marker (dotted area), so that you can quickly determine the degree of overflow and make any corrections if necessary, e.g.: The preview area will have its own scrollbars as needed, and these also take effect if you zoom the output in to a larger footprint than the available room in the editor. Confirming and Configuring Scrollbar Report Canvas Appearance in the Editor​ If you want to see how the visual will appear on the canvas in terms of its scrolling behavior, you can enable the Show scrollbars on overflow property in the Preview area formatting card in the Advanced area property menu: With this property enabled, Deneb will apply the scrollbars to the viewport marker rather than the preview area, e.g.: The displayed scrollbars will also use the appearance configuration from the Scrollbars formatting card, so you can use this option to test this within the editor if so desired. Using pbiContainer to Track Scrolling Events​ Deneb adds a signal named pbiContainer to the Vega view, which provides access to information about the visual container in expressions, e.g.: This is an object with 6 properties: height - the height of the visual container. width - the width of the visual container. scrollHeight - the scrollable height of the container. scrollWidth - the scrollable width of the container. scrollTop the current vertical scroll position. scrollLeft the current horizontal scroll position. If the generated visual overflows the preview area and enables scrolling, Deneb will update the scrollHeight and scrollLeft values as the user scrolls the visible area and re-run the view, meaning that you can assign these values to marks or expressions and they will update. Scroll event monitoring has a default throttle time of 5ms. This can be changed in the Rendered visual > Container scroll events > Throttle time property: This has a minimum value of 0ms and a maximum of 1000ms, and you can use this to tune the performance of scroll event updates as needed. To be able to develop using this feature in the Advanced Editor, it's recommended that you enable Show scrollbars on overflow, to apply this, otherwise the scroll event is not fired. For backwards compatibility purposes, the pbiContainerHeight and pbiContainerWidth signals that Deneb adds for Vega specifications will remain available, but if you rely on these signals, it's recommended that you move to pbiContainer.height and pbiContainer.width accordingly, as these values will update on container changes rather than when the specification is parsed. Edit this pagePreviousFormatting ValuesNextTheme Colors and SchemesOn the Report CanvasConfiguring Scrollbar AppearanceIn the Visual EditorUsing pbiContainer to Track Scrolling Events", "category": "concepts", "source": "deneb" }, { "title": "Theme Colors and Schemes", "url": "https://deneb.guide/docs/schemes", "content": "Deeper ConceptsTheme Colors and SchemesVersion: 1.8On this pageTheme Colors and SchemesDeneb provides some means to bind to your report's current theme, in the form of: Expression-based access using a custom function Custom Vega Color schemes This functionality will dynamically reference the theme are run-time, meaning that if you change your colors, Deneb will keep these references in-sync. Expression-Based Access Using pbiColor​ Deneb provides a custom function, named pbiColor that you can use in Vega or Vega-Lite expressions: pbiColor(index|name, shadePercent = 0) The first parameter (index or name) provides access to the associated theme color: index is a zero-based reference to the Power BI theme palette. This means that: 0 = Theme color 1 1 = Theme color 2 2 = Theme color 3 ...and so on name is a string value (surrounded by single quotes) that specifies a named color from the theme configuration. Valid names are: min / middle / max for divergent colors. negative / neutral / positive for sentiment colors. Power BI also exposes bad and good for sentiment colors, which can also be used instead of negative or positive, should you prefer to use these instead. shadePercent is optional, and is a decimal value between -1 (-100%) and 1 (100%). If supplied, this will darken (< 0) or lighten (> 0) the color by the specified amount. This is to provide variants of the theme colors, much like how Power BI does in its color picker. For example, to specify a bar mark's color to use Theme color 1, you could use the following in your mark's properties: { ... \"mark\": { ... \"color\": { \"expr\": \"pbiColor(0)\" } }} Assuming that you are using the standard theme, output should look like the following for the theme's first two colors (#118DFF and #12239E): Power BI Schemes​ The schemes can be used wherever you might reference a color scheme in a Vega or Vega-Lite scale, e.g.: { ... \"encoding\": { \"color\": { \"field\": \"City\", \"legend\": null, \"scale\": {\"scheme\": \"pbiColorNominal\"} } } ...} { ... \"scales\": [ { \"name\": \"color\", \"type\": \"ordinal\", \"domain\": { \"data\": \"dataset\", \"field\": \"City\", \"sort\": true }, \"range\": { \"scheme\": \"pbiColorOrdinal\" } } ], ...} The available schemes are detailed further below. pbiColorNominal​ The pbiColorNominal scheme is intended to be used for nominal/categorical discrete categories, and matches the current Power BI theme colors, e.g.: pbiColorOrdinal​ The pbiColorNominal scheme can be used for ordinal categories, and uses a ramped scale from the Min divergent Color to the Max divergent color from the current Power BI theme (excluding Middle color), e.g.: Ordinal Scheme has Limited Discrete ColorsThe total number of colors to allocate to the ordinal palette is a fixed number. This is 10 by default.When this limit is reached, the palette 'wraps' back around, which might not be ideal. Similarly, if you don't have enough discrete values, then you may not see an adequate gradient. We have ways of assisting you with this - refer to the Discrete Ordinal Colors section below for more details. pbiColorLinear​ The pbiColorLinear scheme will produce an interpolated gradient from the Min divergent Color to the Max divergent color from the current Power BI theme (excluding Middle color), e.g.: pbiColorDivergent​ The pbiColorDivergent scheme will produce an interpolated gradient from the Min divergent Color to the Max divergent color from the current Power BI theme (including Middle color), e.g.: Discrete Ordinal Colors​ As mentioned higher-up, we only have a limited number of colors in an ordinal palette as they are manually specified values, rather than a linear ramp. We could potentially see issues like the following examples if we don't get this right. The functionality to mitigate these issues follows on afterwards. Issue #1: Not Enough Discrete Colors = \"Wrapping\"​ If we were to allocate, say, 5 discrete colors to our palette but had more values than this, we get a \"Wrapping\" effect, e.g.: Issue #2: Not Enough Discrete Values = Indistinct Gradient​ If we try to mitigate this by guessing a hypothetical number of colors - say, 50 - then we perhaps don't get desired results at a lower cardinality than that, e.g.: Managing via Properties​ The Report Theme Integration menu in the Power BI Format pane allows you to configure the number of values using the Discrete Ordinal Colors property, e.g.: As you may not know what this number is going to be, the property supports Conditional Formatting, so that you could bind a measure that could count the number of distinct category values. This would then allow dynamic assignment (and calculation) of the intervening colors, e.g.: Edit this pagePreviousScrolling and OverflowNextPattern FillsExpression-Based Access Using pbiColorPower BI SchemespbiColorNominalpbiColorOrdinalpbiColorLinearpbiColorDivergentDiscrete Ordinal Colors", "category": "concepts", "source": "deneb" }, { "title": "Pattern Fills", "url": "https://deneb.guide/docs/pattern-fills", "content": "Deeper ConceptsPattern FillsVersion: 1.8On this pagePattern Fills Pattern fills are not a Vega featureThey are only supported for the SVG renderer and will not work for Canvas. Please bear these points in mind if looking to port a specification elsewhere. Overview​ There are a range of SVG fill patterns available wherever a color, stroke or fill can be used in a mark's property. These are based on the excellent work of Irene Ros. Because SVG patterns have to be explicitly defined inside a web page, we can't add all possible combinations of colors and patterns without significant performance reduction. Therefore the functionality is split into two components: Default Patterns: pre-defined monochrome patterns, which are a good starting point for many data visualization use cases. Dynamic Variations: a custom expression function to generate variations of the default patterns with a specific foreground and/or background color. Default Patterns​ Default patterns are referenced using the following syntax: url(#[pattern name]) For example, if we want to use the diagonal-stripe-1 pattern, we would refer to this as follows: url(#diagonal-stripe-1) So, instead of shading our example bar chart from the formatting page with a color, we could use this instead, e.g.: { \"data\": { \"name\": \"dataset\" }, \"mark\": { \"type\": \"bar\", \"fill\": \"url(#diagonal-stripe-1)\" }, \"encoding\": { \"y\": { \"field\": \"Country\", \"type\": \"nominal\" }, \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} And instead of a solid fill, we would now get the following rendered visual: We could augment this with a stroke to provide a boundary to the mark, e.g.: { \"data\": { \"name\": \"dataset\" }, \"mark\": { \"type\": \"bar\", \"fill\": \"url(#diagonal-stripe-1)\", \"stroke\": \"black\" }, \"encoding\": { \"y\": { \"field\": \"Country\", \"type\": \"nominal\" }, \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} Backgrounds​ Default patterns have a transparent background, and this can be observed in the above example with the x-axis gridlines. If you want to provide a solid background, you can either use the dynamic pattern variation expression, or layer a mark behind it with a solid fill, e.g.: { \"data\": { \"name\": \"dataset\" }, \"layer\": [ { \"mark\": { \"type\": \"bar\", \"fill\": \"white\" } }, { \"mark\": { \"type\": \"bar\", \"fill\": \"url(#diagonal-stripe-1)\", \"stroke\": \"black\" } } ], \"encoding\": { \"y\": { \"field\": \"Country\", \"type\": \"nominal\" }, \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} Intensity Modifier​ Default patterns also have a modifier suffix that can be added to reduce the intensity of the stroke from black (#000000) to a softer color. These are in intervals of 10, from 10 to 90, and also at the 1st and 3rd quartiles (25 and 75). So, for our above example, if we wish to reduce the stroke intensity down to 30%, we can use url(#diagonal-stripe-1-30), e.g.: { \"data\": { \"name\": \"dataset\" }, \"layer\": [ { \"mark\": { \"type\": \"bar\", \"fill\": \"white\" } }, { \"mark\": { \"type\": \"bar\", \"fill\": \"url(#diagonal-stripe-1-30)\", \"stroke\": \"black\" } } ], \"encoding\": { \"y\": { \"field\": \"Country\", \"type\": \"nominal\" }, \"x\": { \"field\": \"$ Sales\", \"type\": \"quantitative\" } }} Available Patterns​ The following Power BI report shows all available pre-defined patterns and their SVG URL IDs. You can hover over a pattern to get a tooltip showing its ID in a larger font, as well as how the SVG URL should look in order to apply it. The slicer at the bottom of the page can be used to observe the patterns at the specified intensity, and the SVG URL ID required to apply it. Dynamic Variations​ If you wish to use more color in your patterns, then Deneb provides an expression function that you can use. This will dynamically generate and apply a variation of a default SVG pattern definition to the visual's DOM, and re-use them if necessary. The pbiPatternSVG Expression Function​ The function has the following syntax within a Vega or Vega-Lite expression ref: pbiPatternSVG(pattern, foreground, background) Where: pattern is one of the pre-defined pattern IDs above, enclosed with single quotes. The # used in the SVG URL should not be included here. If an unknown (or invalid) pattern is provided, then this will result in no fill being applied. foreground is a valid CSS color name or hex value, enclosed with single quotes. If foreground is omitted (or null), Deneb will resolve this back to the value used by the default pattern (black). transparent is a permitted value, and this will effectively hide the pattern stroke from the reader. foreground overrides the intensity modifier, if this is supplied in pattern. background is a valid CSS color name or hex value, enclosed with single quotes. If background is omitted, then Deneb will produce a transparent background for the generated pattern. Simple Example - Mark Properties​ If we wanted to apply a custom foreground and background, we could use pbiPatternSVG in an expression function as follows: { \"data\": { \"name\": \"dataset\" }, \"mark\": { \"type\": \"bar\", \"fill\": { \"expr\": \"", "category": "concepts", "source": "deneb" }, { "title": "Working with Templates", "url": "https://deneb.guide/docs/templates", "content": "Deeper ConceptsTemplatesVersion: 1.8On this pageWorking with Templates Deneb has a number of built-in templates that are available from the Create New Specification dialog. This is demonstrated in the Simple Worked Example when we create our first chart. Of course, we can't capture everything in these templates and they're really to help you in getting started. You are able to generate your own, or import those generated by others. Importing a Template​ Much like creating from an inbuilt template, to import a template you will need to ensure that you have at least one column or measure in your visual's dataset so that the advanced editor can be accessed. In the advanced editor's Create New Specification dialog, you have the option to import a template, e.g.: Ensure that Existing template is selected as the method, and either click the area under Import your file to browse to your template's .json file. Click Open when ready. If you have the content of your Deneb template copied to your clipboard (either as plain text or from a file in Explorer), you can past into this dialog with [Ctrl + V] and it will be imported if Deneb recognizes it as a valid template. Only valid Deneb templates can be importedDeneb templates contain special metadata that are typically not present in Vega or Vega-Lite examples you may find elsewhere. For these examples, it's better to create an empty specification for your desired language and then paste in the JSON to the editor. Dataset Placeholders​ The selected file's JSON will be validated and if successful, the placeholder information will be displayed, e.g.: Template CompatibilityOnly valid Deneb templates can be imported. If you're looking to add a Vega or Vega-Lite specification from elsewhere, it's better to create a blank template for the appropriate provider. Then, paste this into the editor and correct it directly, or manually add the appropriate metadata required for Deneb and then import. Refer below for more detail on this. For each placeholder, the suggested data type (that the author used in their dataset) is shown next to the name. You are not restricted to choosing columns or measures of the the same data type, but it is likely that your results may vary if you do choose a different one to the author's design. The only restriction is that columns and measures cannot be used interchangeably, and these are greyed-out and disabled accordingly. If the author decided to enter a description for the placeholder, this can be viewed by interacting with the information icon next to it. Populating Placeholders​ Click or expand a placeholder's dropdown list to select an appropriate column or measure from your dataset, e.g.: The data type for each column and measure is shown next to it, so that you can quickly identify eligible candidates. If a suitable candidate does not exist, you can add new columns or measures from the data model and the details in the dropdown list will update to match. Once all placeholders have been assigned, the Create button is enabled, e.g.: Keep your Dataset TidyIf you have anything from your dataset that is unassigned, (particularly columns), it is recommended that you remove them, in order to preserve the cardinality or row context that the template author originally intended. Selecting the Create button will then add the template to the advanced editor, with all placeholders filled-out as specified, e.g.: Everyone's data is different, so it is highly likely that you'll need to make further tweaks to the specification to make it suit your particular scenario, but otherwise you're good to go! 😄 Generating a Template​ If you're happy with a specification and wish to share with others, or take a copy for re-use or source control, it is possible to 'export' a template. In the advanced editor, select the Generate JSON Template command. This will open the dialog. Template Information​ Fill in a suitable, descriptive name for the template and a more detailed description. This will be displayed to any users when importing it and should help then with filling it in. The author details are currently not shown on import, but may be later on. Including a Preview Image​ You have the option to include a preview image in your generated template's output. Preview Images Can Potentially Contain Sensitive Information By generating a preview image, you are including visual information about your data into the template. Including a preview image can substantially increase the size of your JSON template. Because of these factors, you need to manually opt-in each time the dialog is opened. If your data is sensitive, or you don't know whether your data is sensitive or not, do not include a preview image in your template. By checking this box, Deneb will do the following: Use the Vega View APIs to generate a PNG-encoded image of the current view in the editor. Constrain this to a maximum of 150 x 150 pixels (which helps to keep the physical size of the template lower). Th", "category": "concepts", "source": "deneb" }, { "title": "Performance Considerations", "url": "https://deneb.guide/docs/performance", "content": "Deeper ConceptsPerformance ConsiderationsVersion: 1.8On this pagePerformance Considerations It's Early Days for Deneb​ We're in the very first stages of getting Deneb off the ground and most of what has been done so far has been around solving technical challenges to get the functionality working within a custom visual. For the majority of cases, Deneb should perform quite well, but if you're building a behemoth visual with lots of data, then you may need to think about the resulting output and the demand this can potentially create on a client machine - either while you're building a visual, or when your end users are consuming it. Please bear in mind that while care has been taken so far to try and make things work nicely, we will apply concerted effort to work on performance of the interface as we iterate. The following page has some recommendations for keeping performance optimal. Selection of Renderer​ You can specify the renderer to use in the Settings panel of the Visual Editor. SVG is the default , which will render your specification using vector graphics. You also have the option to select Canvas, which will use pixel graphics. SVG is typically used for the lion's share of simple data visualizations and typically produces \"clearer\" output that scales well at a variety of sizes. However much like adding multiple visuals to a report page in Power BI can have an impact on performance, using SVG with a lot of data can have similar detrimental effects on performance. It's recommended that you try and stick with Canvas, particularly if you're prototyping a design and aren't sure on how many elements or data points you're potentially working with. If you want to use SVG and you're working with a lot of data, consider if you can use elements that consolidate many data points into a single item on-screen, such as a line rather than a point, as this helps reduce the number of moving parts. For more details on Canvas vs. SVG, there's a great article here at CSS-Tricks that consolidates a lot of useful info and summarizes a number of pros and cons. Applying Changes as You Type vs. Manually​ The Visual Editor has the ability to [apply changes to your output as you type them](visual-editor#auto-apply-changes-as-you-type-ctrl--shift--enter. Whilst this is pretty cool, it can really slow things down if you're making many changes to a particularly ambitious specification in a short space of time, as each change requires Vega or Vega-Lite to re-parse and render the output. We already use some techniques to minimize unnecessary chatter if this option is enabled, such as debouncing text input, but it's still recommended that you apply your changes manually when ready, if editing a complex or data-intensive specification. Include only Necessary Columns and Measures​ Any data that you add to the visual will have performance implications, specifically: The DAX query required by Power BI to generate the dataset for Deneb. The amount of resources needed by Deneb to process the dataset and for Vega or Vega-Lite to render the resulting output as per your specification. Creating a row context with lower granularity than you actually need, which can make producing the desired output more challenging. Therefore, only add the columns and measures (and filter context) that your visual needs to communicate its message.Edit this pagePreviousTemplatesNextInteractivity FeaturesIt's Early Days for DenebSelection of RendererApplying Changes as You Type vs. ManuallyInclude only Necessary Columns and Measures", "category": "concepts", "source": "deneb" }, { "title": "Interactivity Features - An Overview", "url": "https://deneb.guide/docs/interactivity-overview", "content": "Interactivity FeaturesVersion: 1.8On this pageInteractivity Features - An Overview Power BI provides the ability to create visuals using R and Python. Whilst these extend your options significantly, these are typically rendered as a static image and mean that it's currently not possible for you to interact back from these visuals to the rest of the report. On occasion, these visuals may also require some additional dependencies if you want to share with a wider pool of end-users, or a library may not be available in the Power BI Service when it comes to deployment. How Deneb Can Be Different from R & Python Options​ In addition to the JSON-based declarative syntax, Deneb is packaged with the Vega and Vega-Lite libraries. Because they are built for the web, anything you produce should ideally be portable within the Power BI ecosystem, irrespective of which device you're using. Both Vega and Vega-Lite have their own approaches to interactivity and it's only logical to start thinking about how we can make use of this to make the visual \"fit in\" with the functionality on offer in other Power BI visuals... Managing your Expectations​ The interactivity part is one of the harder elements of developing your own custom visual and as such, it's going to be challenging to make this work in a visual like Deneb in a generic way, particularly as the Vega tooling provides a lot of creative freedom. We fundamentally have three challenges when it comes to building visuals that are interactive within Power BI: Ensuring that Deneb visuals can interact with the main Power BI window (which handles interactivity events on a visual's behalf). Reconciling data and row context to other visuals or the data model when events happen in our visual. Prescribing how the our visual should behave and respond visually when our end-users interact with it. As such, we have some considerations to make when trying to deliver functionality are interactivity so that you can produce visuals that look and feel at home in Power BI, and your end-users get a consistent experience with your visual vs. others. The below is going to attempt to summarize some of the considerations we need to think about and this is a challenge to do concisely. For a deeper understanding, you're welcome to dive into the developer documentation for visuals. Reconciliation of Data and/or Row Context​ Getting Data from the Model​ Visuals in Power BI can't read from the model of their own volition - they are effectively ring-fenced away from the main interface for a lot of (sensible) reasons. When you add columns and measures to the data roles, this is part of Power BI's interface, rather than the visual's. Power BI looks at all of these, plus the current filter context and runs a DAX query on the visual's behalf. To illustrate, we can use the Financial sample dataset that comes with Power BI Desktop to add the Country column and specify a sum of Sales to Deneb's Values data role: After doing this, Power BI will generate the following query against the data model (which can be verified using the Performance Analyzer): // DAX QueryDEFINE VAR __DS0Core = SUMMARIZECOLUMNS ( 'financials'[Country], \"Sumv_Sales\", CALCULATE ( SUM ( 'financials'[ Sales] ) ) ) VAR __DS0PrimaryWindowed = TOPN ( 10001, __DS0Core, 'financials'[Country], 1 )EVALUATE__DS0PrimaryWindowedORDER BY 'financials'[Country] This would produce the following dataset (visualized using a table): ...and this dataset is supplied by Power BI into the visual. At this point, Deneb's logic will process the dataset and things continue as normal. tipRefer to the Dataset page if you want to see how this data would get represented internally. Signaling Back to Power BI​ Now using the above as an example, we can talk about the following interactivity scenarios: Displaying a report page tooltip or leveraging modern tooltip features Drilling-through from the context menu Cross-filtering other visuals Having other visuals cross-highlight ours All of these situations require the visual to tell Power BI what data it needs to work with... but here's the thing: just like how visuals can't just read whatever they like from the data model, they definitely can't send anything back. For these situations, Power BI provides APIs for a visual to request that Power BI try to do these things on its behalf. For Power BI to fulfil this, it needs to know which row(s) from the original dataset it has to resolve. If you have just taken the dataset as-is and created a mark using Vega or Vega-Lite, then a mark's datum still has the correct row context and identifying information that Power BI needs. However, if you apply an operation in your specification that mutates the data from its original dataset - for example a transform (Vega | Vega-Lite) - then we lose the ability to leverage this functionality in the resulting outputs. Any functionality we can deliver needs to bear these constraints in mind. Additional Datum Fields​ Provided that there are no", "category": "interactivity", "source": "deneb" }, { "title": "Tooltips", "url": "https://deneb.guide/docs/interactivity-tooltips", "content": "Interactivity FeaturesTooltipsVersion: 1.8On this pageTooltips We saw in the worked example, that it's fairly straightforward to add tooltips to a specification, but we'll unpack on this page in a bit more detail. If you haven't read it already, it's worth reviewing the preceding page to understand some of the considerations that need to be made with integrating back to Power BI. It will certainly help with understanding the logistics around report page tooltips in particular. Tooltip Strategy​ Vega and Vega-Lite both provide the ability to customize how their tooltip events can be interpreted. Deneb contains a tooltip handler written specifically for Power BI, which will display under the following conditions: Tooltip Handler is enabled in the Vega > Power BI Interactivity section of the Settings pane in the Visual editor. This is enabled by default. An appropriate tooltip property is assigned to a mark. Refer below for the recommended syntax for each provider. A tooltip-enabled mark is hovered over. Data Point Resolution​ Provided that your mark's datum is not transformed or mutated away from the \"dataset\" and represents the \"pure\" row context passed-in, Deneb can resolve this back to Power BI for delegation. If a report page exists with at least one of the columns in the current datum, then Power BI will display it for the current row context, e.g.: If there is no suitable report page for the current datum or you have specified a default tooltip in the Tooltip menu in Power BI's Properties pane, then a default tooltip will be displayed, e.g.: noteA default tooltip will display all values for the current mark's datum, including any other columns or measures bound to its particular row context. If the title of a tooltip field matches the name of a column or measure from the Values data role, Deneb will attempt to see if it has a format string set in the data model and apply this automatically. If this cannot be resolved, then you can consider applying a format manually. If you have enabled modern tooltip support in your report, and a data point has a corresponding drill through page, this is resolved in the tooltip, e.g.: Default Tooltip Styling​ This is done in the usual way, i.e. in the Tooltip menu in Power BI's properties pane. Vega-Lite Syntax​ The simplest approach for this is recommended, e.g.: { ... \"mark\": { ... \"tooltip\": true, ... }, ...} Vega Syntax​ With Vega, you need to specify the tooltip signal in your mark's encode property, e.g.: { ... \"encode\": { \"enter\": { ... \"tooltip\": { \"signal\": \"datum\" }, ... } }, ...} 'Debugging' with Tooltips​ If you're using an approach to display the underlying data point (e.g. Vega-Lite) rather than the resolved tooltip info that Vega provides by setting to true, we're able to see a bit further under the hood, .e.g: This can be useful to understand what additional fields or calculations may be applied to a datum for usage in expressions. It can also help to understand if a mark still has row context and can be reconciled back to Power BI for interactivity purposes. If a tooltip's datum contains the following properties, then this is a slam-dunk: __identity__ __key__ identityIndex __selected__ Please refer to the interactivity documentation for a further explanation of what these mean. Limitations and Considerations​ Tooltip integration with Power BI is wholly dependent on the correct row context. Refer above, or to the Overview page for more information about ensuring this is preserved. Adding a tooltip does not automatically add visual feedback or effects. If you want to track the position of the resolved data point more visually (e.g. like for a line chart), you will need to add a suitable set of marks to do this. Both Vega and Vega-Lite have examples you can refer to. Development so far has been focused on Power BI integration. It's possible that if you deviate from the above patterns, then tooltips may not display correctly. If you find any such use cases, please create an issue with the appropriate reproduction steps (e.g. example specification and/or data) and we'll see what we can do about it. Edit this pagePreviousInteractivity FeaturesNextContext MenuTooltip StrategyData Point ResolutionDefault Tooltip StylingVega-Lite SyntaxVega Syntax'Debugging' with TooltipsLimitations and Considerations", "category": "interactivity", "source": "deneb" }, { "title": "Context Menu", "url": "https://deneb.guide/docs/interactivity-context-menu", "content": "Interactivity FeaturesContext MenuVersion: 1.8On this pageContext Menu If you or a user right-clicks the visual canvas, Deneb will display the Power BI context menu. The context menu is managed by the main Power BI window, so Deneb manages integration between the Vega view and Power BI, in order to delegate as much as possible on your behalf. Context Menu Strategy​ The context menu works as follows: The context menu will always be available when right-clicking the visual canvas (or within the boundary representing the visual viewport in the Advanced Editor's Preview Area) You can configure whether Deneb should attempt to resolve data points when invoking the context menu, through the Resolve Data Points in Context Menu property in the Vega > Power BI Interactivity section of the Settings pane in the Visual editor. This is enabled by default. Data Point Resolution​ With the Resolve Data Points in Context Menu property enabled: if the right-click target area is a mark, and represents an un-transformed row from your \"dataset\", Deneb will attempt to resolve the current row context and present any options that Power BI makes available from the main window, e.g.: Regular Context Menu (or Resolution Not Possible)​ If the property is disabled or a datum cannot be resolved from a mark (or the target area is not a mark), Deneb will display the regular context menu, e.g.: Limitations and Considerations​ Data resolution integration with Power BI is wholly dependent on the correct row context. Refer above, or to the Overview page for more information about ensuring this is preserved. The Power BI context menu only accepts a single datum, or row. This means that if you are aggregating rows into marks then we cannot resolve the context menu in these cases. Edit this pagePreviousTooltipsNextCross-Filtering (Selection)Context Menu StrategyData Point ResolutionRegular Context Menu (or Resolution Not Possible)Limitations and Considerations", "category": "interactivity", "source": "deneb" }, { "title": "Cross-Filtering (Selection)", "url": "https://deneb.guide/docs/interactivity-selection", "content": "Interactivity FeaturesCross-Filtering (Selection)Version: 1.8On this pageCross-Filtering (Selection) It is possible to enable cross-filtering of other visuals when a mark containing a resolvable datum is clicked (or Ctrl/Shift-Clicked for multi-select). However, cross-filtering is a bit of a special case vs. tooltips and the context menu. As such, this is disabled by default, so as not to create potential UX issues prior to ensuring your visual effects are applied based on selection state. We'll explain on this page what you need to think about if you want to enable this for your visuals, and what to think about from an implementation perspective when creating your specification. Cross-Filtering Strategy​ Both Vega (with Signals and Events) and Vega-Lite (with Parameters) both have their own ways of managing interactivity internally when it comes to clicking on marks. However we also have to think about how Power BI manages selection state between visuals and apply this in a generic manner, so Deneb again bridges this particular gap as much as possible. Therefore, cross-filtering works as follows: You can configure whether Deneb should attempt to resolve data points when clicking on marks, through the Expose cross-filtering values for dataset rows property in the Vega > Power BI Interactivity section of the Settings pane in the Visual editor. This setting is disabled by default. For each row in the visual \"dataset\", Deneb will generate a special field for each row called \"__selected__\", and will update this based on click events, or eligible external events to your visual, such as restoring a bookmark with an active selection state. Management Mode of Cross-Filtering Events​ With the Expose cross-filtering values for dataset rows property enabled, Deneb will then display a Cross-filtering management setting, with two options: 'Advanced' Really Means AdvancedThe documentation on this page continues under the assumption that you will be working with the Simple (default) management mode. It is worth starting with this mode to allow Deneb to handle as much as it can for you, although you will still need to do some work. If you are using Vega and have a need to do more than the Simple mode can offer (and are comfortable with how things work), then you can explore Advanced Cross-Filtering. Additional Strategy for the Simple Management Mode​ If multiple data points are selected (i.e. by holding the Ctrl or Shift key), Deneb will add these to the current list of selected data points and update the __selected__ value accordingly. Clicking anything other than a mark within the visual canvas (or a mark that cannot be resolved to one or more data points) will clear the current selection from the visual, and signal to Power BI to do the same for other visuals on the page. It is up to you as a creator to use this field to manage the visual effects within your specification for selected vs. unselected marks. A simple illustration of this is covered in the worked example and some further simple examples are covered further down the page. Data Point Resolution​ With the Expose cross-filtering values for dataset rows property enabled, Deneb will monitor marks for click events. If the mark represents an un-transformed row's datum from your \"dataset\" (or has enough information for Deneb to resolve it), it will be added to the list of currently selected data points and delegated to Power BI for handling other visuals in a page, e.g.: You Must Manage Visual Effects and EncodingsNote that the above is based on the visual produced in the worked example. As such this has an encoding applied to add an effect to marks that are in the current list of selected data points and is to help illustrate the concept. You will need to manage such encodings yourself. The card to the right of the visual is merely for illustrative purposes: it helps us to re-state the selected values via another measure and confirm selections are propagated. Holding the Ctrl or Shift key and clicking additional marks that contain resolvable data points will add these to the current list and affect other visuals, e.g.: Primitive Aggregate Resolution​ For marks or layers that contain simple aggregates, Deneb can attempt to resolve and collect the individual data points, based on the unique values of grouped fields. This can be useful but there are a couple of considerations here: Any columns and measures need to be aliased in this new data stream as the corresponding columns and measures they are derived from. If you are applying filtering or additional transforms that remove the component rows, this is not taken into account. As the data is a new stream, the granularity (and therefore the row context) is different to the base \"dataset\". This means that there is no corresponding __selected__ field to help manage selection state, but it is possible to be creative here and give the impression of selection at a higher level; there is an example of this below. Data Poi", "category": "interactivity", "source": "deneb" }, { "title": "Advanced Cross-Filtering", "url": "https://deneb.guide/docs/interactivity-selection-advanced", "content": "Interactivity FeaturesAdvanced Cross-FilteringVersion: 1.8On this pageAdvanced Cross-Filtering For many use cases, Deneb's cross-filtering is typically enough. However, there are people who want much more control over how cross-filtering should work within their designs, and the advanced cross-filtering features are designed to help with this. This mode is only available for developers using VegaIf you are using Vega-Lite, or are happy with how your cross-filtering is managed with the Simple mode, then it's probably best to skip through to the next page. How Advanced Cross-Filtering Works (in a Nutshell)​ Because your resulting visual specification might be quite different from your source dataset, it's not always easy to trace lineage of a mark back to its source data point (which is essentially what simple cross-filtering does). At a high level, you can do the following with the functionality provided: Specify exactly when events are triggered through Vega. Rather than just use the current data point in the event, you can specify a filter to apply to the original dataset sent by Power BI, based on this data point (or even static logic). Whatever is returned by this filter will be subject to cross-filtering (with all eligible data points having their __selected__ field set accordingly). The filter you construct is a valid Vega filter transform. There is a lot of scope in this functionality, which will open up how cross-filtering works and we couldn't possibly document (or know) what's possible. Instead this page will focus on providing you with as much detail about the functionality as we can so that you can use this as a basis for your own designs. Enabling Advanced Cross-Filtering​ Vega allows you to control much more in terms of what happens with events inside a visual (known as Event Streams). These Event Streams allow you to set signal values using Expressions. As such, you are able to define all kinds of ways to define how a user can interact with your visual and this can create all kinds of interesting opportunities for how you can invoke cross-filtering from your visual to others on the page. You can configure whether Deneb should attempt to resolve data points when clicking on marks, through the Expose cross-filtering values for dataset rows property in the Vega > Power BI Interactivity section of the Settings pane in the Visual editor. This setting is disabled by default. For each row in the visual \"dataset\", Deneb will generate a special field for each row called \"__selected__\", and will update this based on click events, or eligible external events to your visual, such as restoring a bookmark with an active selection state. The Cross filtering management mode should be set to Advanced. Now you're on your ownWith this setting enabled, Deneb will no longer monitor for click events, or clear the current-cross filter on your behalf. Approach for Advanced Management Within your Specification​ With the above in mind, you need to then think about what to do with the events that you wish to wire up to Vega, either: Clear the current cross-filter selection - this is carried out via the pbiCrossFilterClear expression function. Apply/update the current cross-filter selection - this is carried out via the pbiCrossFilterApply expression function. Both functions are documented in detail further below so that you can get the most out of them, but we'll do a simple worked example that mimics the simple cross filtering, so that you can start to understand how to think about managing this yourself. In this example, we have a mark that we've named data-point, and we want to manage the cross-filter state via a signal we've named pbiCrossFilterSelection: { \"marks\": [ { /* The mark we wish to monitor (and encode) */ \"name\": \"data-point\", ... } ], ... \"signals\": [ { \"name\": \"pbiCrossFilterSelection\", \"value\": [], \"on\": [ /* When specified mark is clicked, apply the cross-filter operation */ { \"events\": { \"source\": \"scope\", \"type\": \"mouseup\", \"markname\": \"data-point\" }, \"update\": \"pbiCrossFilterApply(event)\" }, /* When the view is clicked (but not our mark by name), clear the current cross-filter */ { \"events\": { \"source\": \"view\", \"type\": \"mouseup\", \"filter\": [ \"!event.item || event.item.mark.name != 'data-point'\" ] }, \"update\": \"pbiCrossFilterClear()\" } ] } ], ...} Handling 'catch-all' events against the viewYou'll notice that there is very specific filtering in the mouseup event stream handler, so that the mark is excluded by its name. This is because monitoring the view for an event will include any marks as well. Vega does not currently prevent propagation of the event from a mark to the view, so for now you will need to bear this in mind when implementing 'catch-all' events against the view. Some other key takeaways at this stage: The pbiCrossFilterApply event requires the bound event variable as its first parameter. This contains the information about the event type being captured and the backing datum for the m", "category": "interactivity", "source": "deneb" }, { "title": "Cross-Highlighting", "url": "https://deneb.guide/docs/interactivity-highlight", "content": "Interactivity FeaturesCross-HighlightingVersion: 1.8On this pageCross-Highlighting It is possible to make your visual respond to cross-highlight interactions from other visuals. Much like Cross-Filtering, this requires some additional work to implement the necessary visual effects that you want your visual to have, so as such the properties are disabled by default. This page shows how to enable this, and provides some guidance on how you can work with the data that gets sent to the visual dataset. This is A Deep and Info-Dense TopicThis whole page provides valuable knowledge about how cross-highlighting works in Power BI, and the theory you need to consider how to approach it in your own visuals.If you're the sort of person that just wants to get on with it, the one thing you absolutely need to bear in mind is: any visual you want to build that supports cross-highlighting is really 2 visuals in one: A visual that shows the original values. A visual that shows the highlighted values in context with the originals. It is recommended that you read the page in order so you can best understand what cross-highlighting involves. If you want to jump straight in, you can head down to the Recommended Approaches section, but for those who read the whole thing, it may make your life a bit easier 🙂 Filtering vs. Highlighting: Conceptually​ Power BI offers three types of interactions between visuals: Filter, Highlight and None. As creators, a lot of what goes on under the hood is abstracted away from us with visuals that we directly consume in Power BI. If we want to tear off the mask and manage this ourselves, we need to know more about this at a basic level. What follows is a simple guide on how these interactions may work (this can also be dug into at a lower-level in the custom visuals SDK documentation). Let's say we have a chart which shows Sales by Country Code, but we intend to build a visual with Deneb that used Sales by Product. For now we will represent this using a table visual: Filtering​ When it comes to the Filter interaction, our visual dataset's fields are directly updated by Power BI with the revised values, e.g.: It should be fairly evident that the totals have updated in our table to reflect the values from the US category. In our Deneb dataset, the Sales field will contain the same value and our chart would update as we expect. Highlighting​ With the Highlight interaction, we want to be able to show the values in context to the original values. With this enabled, things change a bit. Our dataset now looks similar to the following representation: Here we can see that this is a combination of both of the above tables - our Sales measure shows the original values that were provided, and we have an additional set of values showing the amount for the highlighted Country in our other visual. If we flip things the other way around and click on a row in our table, we can see a similar effect on the bar chart, e.g.: What we see in the bar chart, is almost the same thing as our table: (ignoring the data labels for a second) each Country has: A solid bar - representing the Sales amount for the highlighted Product. A less opaque bar - representing the original Sales amount for each Country (for all Products). Without spoiling things too much, this is the type of approach we need to think about if we want to build a visual using Deneb that implements cross-highlighting. To complete the loop, if we have no filtering applied, but our visual is enabled for cross-highlight, we can consider that both of these \"measures\" exist in the dataset, but have the same value, e.g.: What this Means for Deneb​ With the above in-mind, and before we talk about the strategy and how to work with cross-highlighting in Deneb, there are some other considerations to think about. Deneb is the Visual​ Deneb is the actual custom Visual that you're adding to your report, and the features it supports at a high-level are what Power BI knows about. Your specification is executed within Deneb's environment. If a Power BI Visual wants to support cross-highlighting, it's assumed that you're going to handle it in your code, and if you're writing a specific custom visual that you're going to package and distribute, that's normally fine. Deneb is different in that it's a host for a language that lets you create your own visual, but as far as Power BI is concerned, it's the one that should be cross-highlighting (as we told Power BI that the feature is supported at the Visual level). For us to offer the functionality for creators who wish to leverage it, we have to enable this support at the visual (Deneb) level. Cross-Highlighting = Additional Thinking​ As such, having the feature enabled essentially creates the challenge that you need to start thinking about it: With Deneb, you as a creator might want to enable support and spend the time building everything around it. But, you might not, and that's fine too. Many users have their default interaction ", "category": "interactivity", "source": "deneb" }, { "title": "Change Log", "url": "https://deneb.guide/docs/changelog", "content": "Change LogVersion: 1.8On this pageChange Log Regarding Support of 1.x ReleasesDeneb v1 is reaching the end of its natural life in terms of how we can continue to improve it. In order for us to do this, we need a better platform, and this is coming in the form of Deneb 2.0. A brief plan of what to expect is outlined in this recent blog post, but more information will become available soon as version 2.0 gets closer to being ready.Because Power BI reports are (ideally!) intended to have a long lifetime once deployed, the plan is to keep Deneb 1.x available in AppSource, hopefully forever, to ensure continuity of service.However any development focus will be on the things we need to do to keep it highly available for existing implementations where you have visuals deployed. The only planned changes will be critical bug fixes, Vega language updates (providing they remain compatible with the v1 architecture) and Power BI visual API compatibility, to comply with certification requirements. 1.8.2​ Submitted for certificationDeneb 1.8.1 has been submitted to AppSource for certification and may take some time to reach your reports. If you need to leverage any features or fixes from this release, you can download and use the standalone version. Vega Updates​ Vega updated to 6.2.0 (from 6.1.2) Vega-Lite updated to 6.4.1 (from 6.1.0) Sample Workbook​ Many examples have been updated with comments in the specification JSON, to help further clarify decisions and language features used to achieve designs. Thanks, Imran Haq! QoL Enhancements​ The cursor has been set to auto when inside the visual container, to provide clearer intent of visual elements (#552) Bugs Fixed​ Deneb should no longer report a 'Remote resources cannot be loaded' message for images using data URLs in the AppSource (certified) version (#555) If you're setting width, height or autosize in the config that potentially conflict with Deneb's internal patching, this no longer causes visuals to hang when parsed/resized (#514) 1.8.1 (2025-08-08)​ Bugs Fixed​ Auto-completion now updates correctly when typing (#551). Root cause was revised visual SDK updates in how visuals are packaged for certification. This should also alleviate some other observed slowness issues experienced while typing in the editor. 1.8.0 (2025-07-16)​ Platform Updates​ Microsoft has recently introduced more stringent certification requirements for custom visuals, so the necessary changes have been applied across Deneb's codebase, including security enhancements and updates to the latest visual APIs. There should be no visible changes to your visuals, but please create an issue for anything you believe may be a detrimental change stemming from these updates. Vega Updates​ Vega Updated to 6.1.2 (from 5.30.0) Vega-Lite updated to 6.1.0 (from 5.19.0) Note that during tests by community members, we noticed an edge case where a visual failed to work. This was traced to that specification containing warnings, and some stricter validation introduced in Vega-Lite 5.21.0. If you experience a previously working specification failing, please check for warnings first, resolve those and re-test before creating an issue. Removal of Edit Specification Field Mapping Functionality​ Since its introduction, field mapping has been problematic for some users, which gets in the way of the development process as the dataset is modified through changes made outside the visual (typically either removing or renaming a field in the Power BI portion of the UI). These issues appear to have increased in frequency recently and are not consistent for everyone, making them difficult to debug and support. Given that we have since introduced a more advanced JSON editor in 1.7, which has find and replace functionality (Ctrl + F / Ctrl + H), managing these situations is still fairly convenient, without the overhead of us having to maintain a UI feature that is obtrusive for many users rather than helpful. As we are also prepping v1.x of Deneb for deprecation (with a view to focus on long term stability once this happens), the decision to remove a potentially flaky feature has been taken. Minor Enhancements​ If using Power BI Desktop with the on-object interaction UI enabled, double-clicking a Deneb visual would force this into format mode. This action has been suppressed. Bugs Fixed​ If using a field containing a special character, this was still being included in auto-completion results (#548) 1.7.2 (2024-09-04)​ Minor Enhancements​ Input widget styling matches that of Vega-Editor, improving their layout Bugs Fixed​ Internal Monaco command:// hyperlinks no longer trigger the MS launch URL API (#491) If you are running Deneb in an insecure (HTTP) environment, it will now work (#488, #493) 1.7.1 (2024-08-05)​ Vega Updates​ Vega-Lite updated to 5.20.1 (from 5.19.0) Minor Enhancements​ The pbiContainer signal is now available and updated on scroll events for faceted and repeated specifications (#474) Bugs Fixed​ pbiFormat not r", "category": "other", "source": "deneb" } ]