Creating pages with editable areas in MVC

After you register the page builder feature in your MVC project, you need to create pages with editable areas, where content editors can add content through 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 through 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. In the Pages application, 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 Developing page builder sections.
• Widget zones – components that allow content editors to insert widgets. Widget zones are defined in the views of sections.

Creating a page in Kentico

1. Open the Kentico administration interface.

2. In the Page types application, set up a content-only page type.

3. Perform the following on the General tab of the given page type’s editing interface:

   1. Specify a URL pattern (e.g. /Home).
   2. Enable the Use Page tab setting (the page builder will be available on the Page tab in the Pages application).
   3. Click Save.

4. In the Pages application, create a page of the appropriate content-only page type in the content tree.

The live site URL of the page must match the route of the MVC page where the page builder is located. For example, if you use the /Home URL pattern, the page builder must be located on your MVC site’s example.com/Home page.

Initializing the page builder in the controller

In your MVC project, initialize the page builder in the GET action of the controller that handles the page’s URL (route). Use the HttpContext.Kentico().PageBuilder().Initialize method with the DocumentID of the page as the parameter:

            // Retrieves the page from the Kentico database
            TreeNode page = DocumentHelper.GetDocuments()
                .Path("/Home")
                .OnCurrentSite()
                .TopN(1)
                .FirstOrDefault();

            // Returns a 404 error when the retrieving is unsuccessful
            if (page == null)
            {
                return HttpNotFound();
            }

            // Initializes the page builder with the DocumentID of the page
            HttpContext.Kentico().PageBuilder().Initialize(page.DocumentID);

Adding 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>
    @Html.Kentico().EditableArea("area1")
</div>

You can optionally specify a default section for each area by setting the identifier of the given section as a parameter of the EditableArea method. The default section is automatically added into new areas and in cases where an editor removes the last section from an area.

<div>
    @Html.Kentico().EditableArea("areaWithSection", defaultSectionIdentifier: "LearningKit.Sections.Col5050")
</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 in your views:

• PageBuilderScripts – renders required script tags and script file links. Call before the closing </body> tag of the page code.

• PageBuilderStyles – renders links for the required stylesheet files. Call within the <head> tag of the page code.

  Copy

  
  
  
    <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 methods load 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 in Kentico.

Limiting widgets allowed in an editable area

To limit which widgets can be added to a specific area, add any number of string parameters to the corresponding EditableArea method in your views.

The strings must contain the identifiers of widgets you want to allow in the area (see Developing widgets in MVC to learn more about widget identifiers). For the system’s default Form widget (used to display forms on pages), get the identifier from the KenticoFormWidgetController.WIDGET_IDENTIFIER constant (available in the Kentico.Forms.Web.Mvc.Widgets namespace).

The allowed widget parameters work as a whitelist – you list the widgets that you want to allow in the editable area, and all others are automatically excluded. When no allowed widgets are specified, all registered widgets can be added to the area.

<div>
    @{
        string[] allowedWidgets = { Kentico.Forms.Web.Mvc.Widgets.KenticoFormWidgetController.WIDGET_IDENTIFIER,
                                    "LearningKit.Widgets.NumberWidget",
                                    "LearningKit.Widgets.SomeOtherWidget" };
    }
    @Html.Kentico().EditableArea("limitedArea", allowedWidgets: allowedWidgets)
</div>

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