This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Widget Configuration

Every widget has it’s own widget configuration. The widget configuration is added by initialvalues (/resources/db/initialvalues/Widget.yaml).

    label: widgets.my_widget.label
    unique_id: my_widget
    active: true
    deleted: false
    relWidget_app: nice_widget_app where unique_id = 'widget_app'
    identifier: unique_id
    priority: 10

If the widget has its own app instead of using a default one like entity-browser, a custom Widget_app will also need to be created.

    unique_id: widget_app
    app_name: client-app
    package_name: widget-bundle
    identifier: unique_id
    priority: 20

Usually all widgets are inside the widget-bundle package.


By default all widgets are inactive (active: false). If a customer licences a widget, a tocco support user needs to activate the licenced widget manually in the respective system(s). This can be done by accessing https://{installation}{new-admin}/e/Widget (e.g.

If a widget is no longer licenced and used by a customer it may be deactivated in the same way.


The My_widget_widget_config.xml entity has to be added.


admin-delete-action and admin-create-action have to be set to false.

<?xml version="1.0" encoding="UTF-8"?>
  <key name="pk" type="serial"/>
    <display language="freemarker">${}</display>

The new My_widget_widget_config entity has then to be set as a relation on the root Widget_config.

<?xml version="1.0" encoding="UTF-8"?>
<relation xmlns="">
  <source entity-model="Widget_config">
    <delete cascade="yes" visualisation="silent"/>
  <target entity-model="My_widget_widget_config"/>


Do not forget to generate the changesets.

Common fields for the widget configuration are:

  • entity_name: entity name used in the widget (add <default type="hard">ENTITY_NAME</default> to entity model and do not show field in the forms of the widget configuration).

  • form_base: base name of the forms used in the widget (add <default type="hard">FORM_BASE</default> to entity model and do not show field in the forms of the widget configuration). See Configurable form base if the form_base should not be hard coded.

Common relations for the widget configuration are:

  • relBusiness_unit: Business unit in which the widget runs

  • relPage_limit: Number of items showed per page in the list

  • relReport: Reports added to list/detail if there exists a report placement

  • relSearch_filter: Search filter applied to list of widget

  • relWidget_search_form_type: How the search should be rendered


ACL configuration (entity.acl)
  grant create to widgetmanager;

  grant access, delete to widgetmanager;
  grant access(read) to widgetguest;

The common fields entity_name and form_base should be read-only:

ACL configuration (entity.acl)
entityPath(My_widget_widget_config, entity_name, form_base):
  deny access(write);


The list and detail form for the My_widget_widget_config should be added to /resources/model/forms.

Any forms needed inside the widget has to be added to /resources/model/widgetforms similar to the legacy publicforms folder.

Config relation contribution

The My_widget_widget_config entity will be mapped to input props to the client widget. Therefore the field names will be transformed automatically from snake case to camel case (e.g. allow_create woudl result in allowCreate).

If this is not good enough (e.g. for relations) a ConfigRelationContribution can be added to map the name explicitly:

public ConfigRelationContribution myRelationRelationContribution() {
    return new ConfigRelationContribution("my_widget", "widget-bundle", "relMyRelation", "relationKey");

Common relations contributions applied globally:

  • relBusiness_unit: businessUnit

  • relPage_limit: limit

  • relReport: reportIds

  • relSearch_filter: searchFilters

  • relWidget_search_form_type: searchFormType

Visibility status configuration

Visibility status are configured as Widget_visibility_status entities. Create one for each visibility status your app supports and relate it to your Widget_app. The name of the status used in the client app can be entered into the visibility_status field.

Initial values for a list visibilty status on widget-app
    label: widget_visibility_status.widget_app.list.label
    unique_id: widget_app_list
    visibility_status: list
    relWidget_app: nice_widget_app where unique_id = 'widget_app'
    identifier: unique_id
    priority: 10

A code block configured to use a visibility status can then be used. These can be generated automatically by the widget-visibility-status-code-copy action on the Widget_config_detail. See Visibility status integration on how to change visibility status in the widget app.

Removing a widget

If a widget may no longer be used because it has been deprecated, replaced or some other reason, you will need to write a changeset that sets the deleted field of the corresponding Widget entity to true.

If a customer simply loses the licence for a widget, just set the active flag back to false.

If existing widget configurations should no longer be able to be started, you can deactivate them by setting the active field on them to false.