Create pages with editable areas

After you enable the Page Builder feature for your Xperience application, you can start creating pages with editable areas where content editors can add content using Page Builder widgets. Content editors can arrange widgets using predefined layouts to achieve their desired result without having to resort to coding. You can adjust the visual arrangement of widgets on a page via the following components:

Editable areas – defined directly in the views of your site’s pages. They are the top-level layout component and contain one or more sections.
Sections– customizable components that specify the visual layout of widget zones. Content editors can choose which sections to add within editable areas, and thus adjust the structure of the page. A section may contain multiple widget zones. See Sections for Page Builder.
Widget zones – components that allow content editors to insert widgets. Widget zones are defined in the views of sections.

Page builder structure

Create a page

Open the Xperience administration.
In the Content types application, set up a content type for which the Page Builder is enabled.
In the a website channel application, create a page of the appropriate content type in the content tree.

Add editable areas to views

Identify the locations on your website where you want editors to place widgets. Then define these locations by adding editable areas to the code of the corresponding views. The identifier of each editable area must be a string without white spaces that is unique within the context of the given page:



@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc

<div>
    @await Html.Kentico().EditableAreaAsync("area1")
</div>

You can optionally specify a default section for each area.

Create an EditableAreaOptions object.
Set the object’s DefaultSectionsIdentifier property to match the identifier of the section which you want to use as default.
Assign the object as a parameter of the EditableAreaAsync extension method (or its Tag Helper alternative) used to render the given area.

The default section is automatically added into new areas and in cases where an editor removes the last section from an area.



<div>
    @{
        var optionsDefaultSection = new EditableAreaOptions
        {
            DefaultSectionIdentifier = "LearningKit.Sections.Col5050"
        };
    }
    @await Html.Kentico().EditableAreaAsync("areaWithSection", optionsDefaultSection)
</div>

If you do not specify the default section for an area, it uses the default section configured for all Page Builder instances (either the system’s Default section with a single widget zone, or a custom section assigned when enabling Page Builder).

Load Page Builder scripts and styles

All pages with editable areas must contain scripts and CSS styles required by Page Builder and its components. To add these resources to pages, call the following extension methods (or their Tag Helper alternatives) in your views:

Html.Kentico().PageBuilderScripts – renders required script tags and script file links. Call before the closing </body> tag of the page code.
Html.Kentico().PageBuilderStyles – renders links for the required stylesheet files. Call within the <head> tag of the page code.
```
  @using Kentico.Web.Mvc
  @using Kentico.PageBuilder.Web.Mvc

  <html>
  <head>
      ...
      @Html.Kentico().PageBuilderStyles()
  </head>
  <body>
      ...
      @Html.Kentico().PageBuilderScripts()
  </body>
  </html>

  
```
For views with an assigned layout, we recommend using Razor sections. Sections allow you to call the methods in the appropriate part of the overall page code, but only for pages that contain editable areas.

The helpers include scripts and styles used in the system’s editing interface, as well as those of individual Page Builder components (widgets, sections, inline property editors). See the linked documentation to learn how to correctly add custom scripts and styles for your own components.

Replace the default jQuery library

By default, the system links the jquery-3.5.1.js jQuery bundle required for the correct functioning of the Form and Page Builder and their default components.

If you wish to use a different jQuery version, specify the path to your custom jQuery bundle via the FormBuilderBundlesOptions options object. See Bundle static assets of builder components for more information.

After adding editable areas to views and ensuring that the pages contain the required scripts and styles, you can see Page Builder with the editable areas in the website channel applications.

Configure allowed components for editable areas

You can define widget restrictions for certain areas. To limit which components (widgets or sections) can be added to a specific area:

Create an EditableAreaOptions object.
Assign a list of strings to the object’s AllowedWidgets and/or AllowedSections property.
- The strings must contain the identifiers of components you want to allow in the area (see Widgets for Page Builder and Sections for Page Builder to learn more about component identifiers). For identifiers of the default system widgets, check the system widget reference.
Assign the EditableAreaOptions object as a parameter of the EditableAreaAsync extension method used to render the given area.

The allowed components parameters work as an allowlist – you list the components that you want to allow in the editable area, and all others are automatically excluded. When allowed components are not specified, all registered components can be added to the area. You can also set the properties to the following special values:

AllowedComponents.ALL – all components are allowed within the editable area.
AllowedComponents.NONE – no components are allowed within the editable area (equivalent to an empty list of identifiers).
- Use the NONE option when limiting sections – this “locks in” the default section for the given area and completely prevents editors from adding further sections of any type.

Tip: Prepare the identifiers of allowed components as a string array, and then assign the array to the appropriate property of the EditableAreaOptions object.

Example



<div>
    @{
        var optionsLimited = new EditableAreaOptions
        {
            AllowedWidgets = new[] { "LearningKit.Widgets.NumberWidget",
                                     "LearningKit.Widgets.SomeOtherWidget" },
            AllowedSections = AllowedComponents.ALL
        };
    }
    @await Html.Kentico().EditableAreaAsync("limitedArea", optionsLimited)
</div>

When adding a new widget or section to the limited editable areas, editors can now only choose from the set of allowed components. When dragging widgets or sections between areas, the interface visually distinguishes between areas where you can and cannot drop the components.

The component limiting feature is intended as a way to set guidelines for content editors, not as a security measure. When you limit an area, existing instances of widgets and sections placed in the area are not validated or removed.

Widget zone restrictions

Editable area restrictions of widgets are combined with any widget restrictions set for individual widget zones. Both sets of restrictions apply to create the final list of allowed widgets for the zone.

Retrieve the Page Builder configuration for the current page

You can access the Page Builder configuration of the current page via the IPageBuilderDataContextRetriever service and its Retrieve method. The method returns an IPageBuilderDataContext object that contains the configuration in its Configuration property.

The configuration is stored in the following nested structure:

Page – The root of the configuration
- EditableAreas – contains a list of all editable areas on the page
  - Sections – contains section properties and all widget zones held within
    - Zones – contains the identifier of the zone and a list of all widgets held within
      - Widgets – contains widget metadata (the widget’s identifier, type, personalization variants, etc.)
PageTemplate – contains page template metadata (the template’s identifier and properties)

You can use the configuration if you wish to develop components that react to the presence of other components on the page.

Establish rendering context

To check whether the currently processed component is being rendered on the live site or in a website channel application in the Xperience administration, use the EditMode property of the IPageBuilderDataContext object.



// Stores an instance of the IPageBuilderDataContextRetriever service (e.g., obtained using dependency injection)
private readonly IPageBuilderDataContextRetriever pageBuilderDataContext;

if (pageBuilderDataContext.Retrieve().EditMode)
{
    // Targeted custom logic 
}