Dashboard Widget

When embedded in an application, the Dashboard widget enables complete dashboard management for tenant end users.

Quick Embed Sample (For Testing Only)

Important: This example is for testing purposes only.

• In production, you must use a qvToken instead of exposing an apiKey in the UI.
• The apiKey is private and should only be used for communication between backends.
• For testing, clientId can match the userId. In production, the clientId requires a unique identifier for each tenant end user.

<!-- Tag -->
<qrvey-dashboard settings="dashboardConfig"></qrvey-dashboard>

<!-- Config -->
<script>
var dashboardConfig = {   
   "apiKey": "<YOUR_PRIVATE_API_KEY>",   // Testing only. Do not use in production UI.
   "domain": "<DOMAIN>",   
   "appId":  "<APP_ID>", 
   "userId": "<USER_ID>",
   "dashboardId": "<DASHBOARD_ID>",
   "clientId": "<CLIENT_ID>",            // Optional, for testing, this can match userId.
   "orgId": "org:0"                      // Optional, for testing, use org:0 (base organization)
};  
</script>

<!-- Launcher -->
<script type="module" src="https://<DOMAIN>/qrvey-dashboard/qrvey-dashboard/qrvey-dashboard.esm.js"></script>

Production Deployment

• Use qvToken instead of apiKey.
• Pass sensitive values (appId, userId, clientId, orgId) using the qvToken and not in a plain configuration.
• In production, configure roles, orgs, filters, i18n, and theme as needed.

Configuration Object

Property	Type	Required	QVToken Support	Description
domain	string	Y	N	Qrvey instance URL.
qvToken	string	N	N	Encrypted string securing the widget configuration. Required if no apiKey is provided. This string cannot be used with apiKey.
apiKey	string	N	N	Secret identification token for accessing the application. Required if qvToken is not provided. This string cannot be used with qvToken.
appId	string	Y	Y	ID of the Qrvey application. Must be passed using qvToken in production.
userId	string	N	Y	User ID of the application owner. Must be passed using qvToken in production.
dashboardId	string	N	Y	ID of a specific dashboard to embed. If omitted, the widget displays the "browse dashboards" page.
clientId	string	N	Yes. Must be passed using qvToken during production.	Unique identifier for the tenant end user. - Used for testing. This can match the userId. - In production, each tenant requires a unique value that is passed using qvToken. If omitted, the widget assumes anonymous.
roles	array(string)	N	Only	Used for Column Level Security.
orgId	string	N	Y	Organization ID for the end user. Used for asset ownership. If omitted, the widget uses the clientId's orgId (if set in orgs object). Otherwise, it uses anonymous. Exports created from the widget are owned by the clientId under the orgId. For more information, see Exports.
orgs	array(object)	N	Only	In a dashboard sharing model, organizations, roles, and users are passed through this object. For more information, see Orgs Object.
userFilters	object	N	Y	Collection of custom filters that the system applies to the visualized data. For more information, see Filters in Widgets.
timezone	string	N	Y	Timezone offset applied to dates. For more information, see Configuring Time Zone Settings.
i18n	object	N	N	Defines language and localization. For more information, see i18n Object.
themeId	string	N	N	Theme ID to use in the component. For more information, see Accessing a Theme Programmatically.
styles	JSON	N	N	Key-value JSON with style variables. For more information, see Dashboard Styles.
defaultMode	"design" or "interact"	N	N	Sets the dashboard's default mode to open in design or interact mode. Defaults to interact mode. Only applies to a single dashboard.
customTokens	Custom tokens	N	N	Sets custom tokens. For more information, see Using Custom Tokens.
permissions	JSON	N	Only	Record-Level Security permissions object.
asset_permissions	Asset permissions	N	Only	The asset permissions object.
email	string	N	Only	Email of the clientId user. Required to enable scheduling and subscription. Pass this property in the qvToken.
customization	JSON	N	N	The Dashboard customization object.

Exports

Local and scheduled exports created from this widget are associated with the clientId and orgId that control their display in the Download Manager widget.

If clientId and orgId are passed through a JWT to the widget, the same JWT is sent to the export requests and considered when creating the Download Manager records, even if the widget itself does not use these properties.

Orgs Object

The orgs object determines the list of roles, users, and customer organizations available in the dashboard sharing modal. When defined in the orgs object, sharing settings are displayed in the Sharing modal of an embedded dashboard. For more information, see Share Dashboards in Embedded Scenarios.

Property	Type	Description
orgId	string	ID of the organization for which roles and users are defined.
users	array(object)	List of users in the organization. Each user is defined by clientId and email.
users.clientId	string	Client ID of the user.
users.email	string	Email address of the user.

Example

"orgs": [
  {
    "orgId": "org:1",
    "orgRoles": ["role1", "role2"],
    "users": [
      { "clientId": "client1", "email": "client1@qrvey.com" },
      { "clientId": "client2", "email": "client2@qrvey.com" }
    ]
  },
  {
    "orgId": "org:2",
    "orgRoles": ["role3", "role4"]
  }
]

i18n

For more information, see Internationalization, Step by Step.

Property	Type	Required	Value
lang	string	Y	Language to use for the UI (examples: "es", "es-ES").
locale	string	N	Locale code to use for date and number formatting (for example, "es-ES").
currencyFormatOverride	string	N	Accepts currency codes and sets the currency (for example, "EUR") on visualizations and their exports. It overrides the default currency format in the application. Supports the list of ISO 4217 currency codes.

Note: When applied directly to a column in a chart using the Values Format option, the currency setting supersedes the currency setting in currencyFormatOverride.

Example Configuration

The following code block adds an i18n object to the dashboard widget configuration that includes an override for the default currency format.

var config = {  
  "domain": "<DOMAIN>",  
  "qvToken: "<QVTOKEN>",      
  "i18n": {
    "lang": "en",
    "locale":"EN",
    "currencyFormatOverride":"EUR"
  }
}

Note: The i18n object is supported only in the widget configuration object. It cannot be passed in a JWT.

Styles

The Dashboard Widget supports customization through CSS variables, allowing you to adapt the look and feel of dashboards to match your application’s design system. This includes control over fonts, colors, spacing, and other UI elements.

By overriding the available style variables, you can achieve a fully branded experience for end users without altering functionality. This is the recommended way to ensure consistency across embedded dashboards.

For the complete list of available style variables and examples of how to use them, see Styles.

Methods and Events

The Dashboard widget supports the following interaction patterns:

• Direct Method Calls - Uses the executeAction method.
• Event-Based Communication - Uses custom events with promise-based responses.

Both approaches provide the same functionality with different implementation styles. They allow developers to programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from their host application and integrate dashboard actions into their own UI workflows or automation scripts.

For the complete list of available style variables and examples of how to use them, see Methods and Events.

Use Images in Tokens

Instead of using static images or hardcoded URLs, you can add tokens to retrieve images from their source URLs, allowing the images to update dynamically.

To create a token to use with images, add the image URL to a token within the Dashboard widget's configuration object. For more information, see Custom Tokens.

To add an image from an image URL stored in the token:

1. From the dashboard design view, add an image element to the dashboard.
2. In the Image URL panel, start typing {{ to display the list of tokens.
3. Select a token, then press Enter to add it to the configuration.

The dashboard displays the rendered image in preview mode.