Creating pages with editable areas

The page builder needs to be initialized for individual pages to work. This initialization happens during the initialization of the page’s data context.

• On sites that use content-tree based routing, the page data context initialization is handled for you automatically by the system.

• On sites where routing is handled by custom routes based on page type URL patterns, you need to initialize the page data context manually.

  Manual initialization of the page data context

  Copy

  
  
  
            private readonly IPageRetriever pagesRetriever;
            private readonly IPageDataContextInitializer pageDataContextInitializer;
  
            // Gets instances of required services using dependency injection
            public PageBuilderInitializationExample(IPageRetriever pagesRetriever,
                                                    IPageDataContextInitializer pageDataContextInitializer)
            {
                this.pagesRetriever = pagesRetriever;
                this.pageDataContextInitializer = pageDataContextInitializer;
            }
  
            public ActionResult Home()
            {
                // Retrieves a page from the Xperience database with the '/Home' node alias path
                TreeNode page = pagesRetriever.Retrieve<TreeNode>(query => query
                                    .Path("/Home", PathTypeEnum.Single))
                                    .FirstOrDefault();
  
                // Responds with the HTTP 404 error when the page is not found
                if (page == null)
                {
                    return NotFound();
                }
  
                // Initializes the page data context (and the page builder) using the retrieved page
                pageDataContextInitializer.Initialize(page);
  
                return View();
            }
  
  
  
    

  Pages protected by authorization

  If the GET action of the view component that handles a page’s URL (route) is protected by an Authorize attribute, you may need to take additional steps to ensure that users can work with the page builder. With most configurations, any user can edit the page via the page builder, given the user has permissions necessary to modify the page in the content tree.

  However, if the Authorize attribute has the Users or Roles parameter specified , only users fulfilling the authorization criteria have access to this page in the Pages application. In these cases, you need to include your content editors to allow them access.

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.

1. Create an EditableAreaOptions object.
2. Set the object’s DefaultSectionIdentifier property to match the identifier of the section which you want to use as default.
3. 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 the entire page builder (either the system’s Default section with a single widget zone, or a custom section assigned when enabling the page builder feature).

Loading page builder scripts and styles

All pages with editable areas must contain scripts and CSS styles required by the 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.

  Copy

  
  
  
    @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, page templates). See the linked documentation to learn how to correctly add custom scripts and styles for your own components.

After adding editable areas to views and ensuring that the pages contain the required scripts and styles, you can see the page builder with the editable areas in the Pages application.

Limiting components allowed in an editable area

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

1. Create an EditableAreaOptions object.
2. 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 Developing widgets and Developing page builder sections to learn more about component identifiers). For identifiers of the default system widgets, check the system widget reference.
3. Assign the EditableAreaOptions object as a parameter of the EditableAreaAsync extension method used to render the given area.

The allowed components parameters work as a whitelist – 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.

<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 in the Pages application, 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.