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.

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' and 'supportedWidgetContexts' properties,

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.

Supported Widget Contexts (@since 2024.07.1)

A Widget can specify what context it supports (site and/or page). The value determines in what context the widget is available to add. If the supported contexts property is omitted, all contexts will available.

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.