Working 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 imported

Deneb 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 Compatibility

Only 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 Tidy

If 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 orginally 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).
• The aspect ratio will be preserved, using the largest dimension of the image (either width or height).
• Include the base64 representation of this image in the template's usermeta.information.previewImageBase64PNG property (refer below for more details).

Template Dataset

Beneath the information and preview image, you have the opportunity to customize your dataset requirements for your users:

Keep Only What you Need

Deneb assumes all columns and measures from your dataset are required. If any columns or measures are superfluous to the template, you should remove them from the Values data role so that they also get removed from this part of the dialog. This will ensure that they aren't included for your end users and cause potential side-effects or ambiguity as to how they should be used.

Each dataset field has a text box that you can use to rename the placeholder to something more general-purpose for your template. This is also particularly useful if your names might be sensitive. It's recommended to try and use specific terms so this helps to document your template for end users.

If you leave a box empty or delete its contents the original name from your dataset will be used. This can also be seen in the Original field column for comparison purposes.

Each field has an optional Author's notes field. In here, you can type more information for your end users, should it be required. This description will be displayed next to the field placeholder when used for import.

Review and Export

When you're happy to proceed, you can either download the template file, or copy it to the clipboard. If copying, you can paste into your editor of choice and save it with an extension if .json.

Direct Downloads May Not Be Possible

Power BI visuals are only permitted to download a file if your tenant admin has enabled downloading from custom visuals. You can learn more about this here.

If downloading is disabled, you will typically receive a warning once you click the Download button and in these cases, you can use the Copy button to copy the template definition to the clipboard.

Template Structure

Whilst templates do not include any data from your visual, they are intended to be portable. You would need to supply your own dataset but it should be possible to use this as jumping-off point elsewhere, similar to how you might start with an existing example before refining it in Deneb.

As such, a template is either a Vega or Vega-Lite specification, with a custom usermeta object (Vega | Vega-Lite). This would typically be ignored by an external Vega parser but is used to identify the template as valid for Deneb. This has the following objects:

deneb

All properties are required.

• build: Which version the template was built with.
  • Whist this is required, it is purely for the purposes of troubleshooting at these early stages, so is ideally left as-is.
• metaVersion: The template metadata version.
  • Only a value of 1 is currently supported.
• provider: Which provider should be used when loading and parsing the template.
  • Valid values are vega or vegaLite.
  • If this is manually modified, Deneb will do its best to auto-resolve this from the top-level $schema property (if supplied), falling-back to parsing spec. It's not guaranteed to be successful.

information

The following required properties are populated from the details entered by the author in the Template Information pane from the Create JSON Template dialog:

• name: The name of the template that is displayed in the dialog for users, once imported.
• description: Longer-form details of the template purpose that are displayed in the dialog for users, once imported.
• author: Used to identify the author.
  • Currently not displayed in the dialog upon import (but might be later on).

The following required properties are auto-generated by Deneb:

• uuid: unique ID for the template.
• generated: time (in UTC) the template was generated.

The following properties are reserved for potential use elsewhere, and are not currently used within Deneb. This may change later on:

• supportUri: A URI to indicate where further information about the template can be found (such as a blog or website).
• videoUri: A URI to indicate where a supporting video asset, such as a demo or 'how-to' guide can be found.
• previewImageBase64PNG: Placeholder for a base64-encoded PNG image, which could be used for displaying a thumbnail or assistive image.
  • This is shown in the Create New Specification dialog if included with the template.
  • Images should be no larger than 150x150 pixels.

The information object can be further extended with any properties you want for your own needs, but they will be ignored by Deneb upon import.

dataset

All properties are required.

Additional Considerations for Developers

If you're looking to generate suitable templates offline that can be imported, then you'll need to ensure that the Vega or Vega-Lite component (i.e. the main spec) validates accordingly.

As the usermeta object is extensible, there is a JSON schema you can use to validate that your object will parse correctly in Deneb when imported. This is hosted at:

https://deneb-viz.github.io/schema/deneb-template-usermeta-v1.json