Skip to main content

Widgets

Widget controllers are specialised component controllers. They interact with the Homepage designer feature of Jadu Central.

Registering widgets​

Widgets are registered within the theme services.yml configuration file. Widget services must be tagged with photon.widget. This tag must include at least one of the following parameters to identify the widget in JaduHomepageWidgets:

  • machine_name
  • widget_id (deprecated)

Machine name​

photon_cms_project.widget.website_statistics:
    class: Photon\CmsProject\Widget\WebsiteStatisticsWidget
    parent: photon.controller.widget
    arguments:
        - '@photon_cms_engine.repository.website_statistics'
    tags:
        - { name: photon.widget, machine_name: jadu_cms_website_statistics }

The machine name must match the machineName of the corresponding database entry in JaduHomepageWidgets. Machine names are displayed in the Widget manager feature of Jadu Central.

tip

Every widget's machine name must be unique. To minimise the risk of multiple widgets sharing the same machine name, it is recommended to use a prefix to identify the organisation responsible for creating and maintaining each widget.

When a widget is created through the Widget manager, it will automatically be assigned a machine name based on the title entered. This machine name will always be prefixed with cc_.

When creating your own widgets, you should prefix the machine name with the name of your organisation. For example, any widgets created and maintained by Jadu will be prefixed with jadu_.

Widget ID (deprecated)​

photon_cms_project.widget.website_statistics:
    class: Photon\CmsProject\Widget\WebsiteStatisticsWidget
    parent: photon.controller.widget
    arguments:
        - '@photon_cms_engine.repository.website_statistics'
    tags:
        - { name: photon.widget, widget_id: 31 }

The widget_id should be used only for widgets without a machineName in the database. In these cases, the widget ID must match the id of the corresponding database entry in JaduHomepageWidgets.

warning

The widget_id parameter should not be used for any new widgets. It is provided for backwards compatibility with widgets which do not have their own machine name. If you are creating a new widget, use the machine_name parameter instead.

Using both​

    tags:
        - { name: photon.widget, machine_name: jadu_cms_website_statistics, widget_id: 31 }

In some cases, a widget service may have a machine_name and a widget_id. If a widget has a machine_name and a widget_id, the machine name has priority when matching a corresponding database entry in JaduHomepageWidgets. The widget ID will only be used if no matching database entry is found for the machine name.

tip

When no matching widget service is found using either the machine_name or widget_id, the default widget service is used, with widget_id = 1. The default widget will pass code stored in the database through the function eval() to generate the response returned from the controller.

Invoking widgets​

Widgets are not invoked by a route, but instead by using the widget() Twig function.

{{ widget(widgetRecord) }}

A widget record must be passed as a parameter to the widget() function.