You can configure the dashboard by selecting which widgets the user may add to the dashboard and by describing the initial widget configuration of the dashboard.

To this end, the dashboard configuration is available through the method getDashboardConfiguration() of the editorContext object. It provides a list of WidgetType objects in the types property and a list of WidgetState objects in the widgets property.

Usually, you will not access the configuration object directly, but rather through the ConfigureDashboardPlugin, which also offers a types and a widgets property and takes care of merging these values into the global configuration at the correct time.

The widget state objects in the property widgets determine the widgets to be shown when the user first opens the dashboard. You should therefore select widgets that a typical novice user would find interesting.

Each widget state object must be an instance of the class WidgetState, or a subclass thereof. The class WidgetState itself defines only the properties widgetTypeId, rowspan, and column, indicating the widget type, the relative height of the widget and the placement of the widget, respectively.

Widget types for all initial widgets have to be provided, but you will typically add more widget types for advanced users. Widget types and widget state objects are matched by their id, which can be specified using the widgetTypeId property of the state object. Predefined state objects will typically provide the correct ID automatically.

The following example shows how the ConfigureDashboardPlugin is used inside a Studio plugin specification.

import Config from "@jangaroo/runtime/Config";
import StudioPlugin from "@coremedia/studio-client.main.editor-components/configuration/StudioPlugin";
import ConfigUtils from "@jangaroo/runtime/ConfigUtils";
import ConfigureDashboardPlugin from "@coremedia/studio-client.main.editor-components/sdk/dashboard/ConfigureDashboardPlugin";
import SimpleSearchWidgetState from "@coremedia/studio-client.main.editor-components/sdk/dashboard/widgets/search/SimpleSearchWidgetState";
import SimpleSearchWidgetType from "@coremedia/studio-client.main.editor-components/sdk/dashboard/widgets/search/SimpleSearchWidgetType";

class MyStudioPlugin extends StudioPlugin {
  constructor(config: Config<MyStudioPlugin>) {
    super(ConfigUtils.apply(Config(MyStudioPlugin, {
      //...
      configuration: [
        //...
        new ConfigureDashboardPlugin({
          widgets: [
            new SimpleSearchWidgetState({
              contentType: "CMArticle"
            }),
            new SimpleSearchWidgetState({
              contentType: "CMPicture",
              column: 1
            }),
          ],

          types: [
            new SimpleSearchWidgetType({}),
          ],
        }),
        //...
      ],
    }), config));
  }
}

You can see a single widget type being configured, SimpleSearchWidgetType. In this example, the widget type provides no configuration option itself, but some widget type classes can be customized by configuration.

In the example, there are two widgets using the defined type. By specifying a SimpleSearchWidgetState, the widget type id is set to match the SimpleSearchWidgetType. The two widgets start off with a specific state. As a rule, any configuration options that can be provided using a state object should also be configurable when the widget is in edit mode.

For the second widget, a column is specified. Unless a column property is given, each widget is placed in the same column as the previous widget and the first widget is placed in the leftmost column. For the column property use either a numeric column id from 0 to 2 or one of the constants SAME or NEXT from the class WidgetState, indicating to stay in the same column or to progress one column to the right. The leftmost column is used as the next column of the rightmost column.

Figure 9.7. Dashboard UML overview