Rendering widgets in code

Developers can display page builder widgets manually, without the need to set up editable regions and insert widgets in the page builder interface. The API allows widgets to be rendered directly in the code of MVC views. These can be views that define the output of standard pages and layouts, or even other page builder components, such as page templates or sections.

For example, this rendering approach can be used to include a widget into a site's main layout (the website header or footer). The widget appears as a fixed part of the website, and cannot be removed or adjusted by content editors.

Requirements

  • The page builder feature must be enabled for your MVC project, as described in Page builder development (even though the widgets are rendered without the page builder interface).
  • To allow direct rendering, widgets must be registered using the RegisterWidget assembly attribute (as described in Developing widgets).
  • The page where the widget is rendered must include links to page builder scripts and styles, if these are required by the given widget. The system's default widgets require the page builder scripts and styles.

Rendering widgets

Edit the code of the view where you want to display the widget and call the Html.Kentico().RenderStandaloneWidget extension method (available in the Kentico.PageBuilder.Web.Mvc namespace).

Specify the following parameters for the method:

  • identifier – the string identifier under which the widget was registered. For identifiers of the default system widgets, check the system widget reference.
  • (optional) propertiesIWidgetProperties object representing the widget's properties. Create an instance of the appropriate property model class and set any required values.
@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Content.Web.Mvc
@using Kentico.Web.Mvc

...

@{
    // Prepares properties for the Form widget
    var widgetProperties = new FormWidgetProperties()
    {
        SelectedForm = "FormCodeName"
    };
    // Renders the Form widget
    Html.Kentico().RenderStandaloneWidget(SystemComponentIdentifiers.FORM_WIDGET_IDENTIFIER, widgetProperties);
}

Note: Do not use the RenderStandaloneWidget method in the views of other widgets. If you are developing a widget that extends the HTML output or functionality of an existing widget, call the RenderNestedWidget extension method instead. For more information, see Extending widgets.


Was this page helpful?