Widgets
A Widget is a specific type of WebApp, distinguished primarily by its rendering location. While a traditional WebApp is rendered on a page, a Widget, in contrast, is rendered on a sv:dashboard within the Sitevision editor.
We recommend utilizing the Create Sitevision App (@latest) tool for generating boilerplate apps, enabling a swift start to Widget development.
When developing a Widget, you can refer to regular WebApp documentation for guidance and applicability. The Public API and other WebApp utilities are accessible in a manner consistent with what one might be accustomed to. However, there are a few differences you should be aware of:
- The parent container (custom module) for a Widget must be of the sv:widgetCustomModule type
- Refer to the WidgetCustomModule REST API-endpoint for more information.
- Rendering hooks are not available
- Widgets should be rendered client side (avoid including rendering libraries in your server bundle)
sv:dashboard
A dashboard (sv:dashboard) serves as a container for rendering sv:widgetCustomModule instances and is accessible throughout the Sitevision editor. Dashboards are not tied to a specific node. They can be created in two distinct contexts: PAGE or WEBSITE.
In the WEBSITE dashboard context, applicable to all nodes in the Sitevision editor, widgets displayed typically convey site-wide information. Conversely, the PAGE dashboard context, available for sv:page-like nodes, is designed for widgets to provide information specific to the current node.
PortletContextUtil
PortletContextUtil has been updated with a method to get the current dashboard when rendering a sv:widgetCustomModule.
const dashboard = portletContextUtil.getCurrentDashboard();
// Get the displayName of the current dashboard and its context (SITE/PAGE)
const { displayName, dashboardContext } = properties.get(dashboard, "displayName", "dashboardContext");When rendering a widget on a dashboard with SITE context, the getCurrentPage function of PortletContextUtil will consistently return the site node. In contrast, when dealing with a widget on a dashboard in PAGE context, getCurrentPage will return the current node in the Sitevision editor.
Widget manifest
The manifest file closely resembles that of a standard WebApp, with the main distinction being the specification of the 'type' as 'Widget'. Another variation is the inclusion of the 'supportedWidgetSizes' property, which allows the specification of the sizes a Widget should support.
// manifest.json
{
"id": "popularPages",
"version": "0.0.1",
"type": "Widget",
"name": {
"sv": "Populära sidor",
"en": "Popular pages"
},
"description": {
"sv": "En Widget att visa webbplatsens mest populära sidor",
"en": "A Widget to display the most popular pages of the website"
},
"author": "Sitevision AB",
"helpUrl": "https://developer.sitevision.se",
"bundled": true, // A Widget is always bundled
"maxUploadSizeInMB": 0,
"requiredLibs": { // Declares required libraries
"react": "17.0.2"
},
// Declare what sizes the widget should support.
"supportedWidgetSizes": ["small", "medium", "large", "extra_large"]
} Supported Widget Sizes
A Widget needs to specify the sizes it supports. These supported Widget sizes will be accessible in the Sitevision editor as part of the Widget configuration, enabling users to apply a suitable setup. If the supported sizes property is omitted, all available sizes will be configurable.
For responsive design across all supported sizes, the Widget should employ Container queries rather than Media queries.
Styling
Envision for Dashboard Widgets is an extension to Envision that should be used when creating Sitevision Dashboard Widgets.
The Sitevision dashboard uses a supplied custom Envision theme as a base.
Additional CSS variables, class names and components for building widgets are available and described here.
Marketplace guidelines
Explore our guidelines for distributing your widget through the Sitevison Marketplace.