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.

Viewing the live URL of content-only pages

You can view the live site URL of content-only pageson the Properties -> General tab in the Live URL field.

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:

Example



            // 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);



Pages protected by authorization

If the GET action of the controller 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 parameter specified, only the listed users have access to this page in the Pages application. In these cases, you need to include your content editors in the Users parameter to allow them to edit the content.

Initialization when using page templates

It is not necessary to initialize the page builder for pages that use the page templates functionality. The TemplateResult object that is returned in the controller of templated pages automatically initializes the page builder and thus you do not need to do it manually.

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:

Required namespaces



@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.

    
    
    
      <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.

Using jQuery scripts

By default, Kentico links two jQuery bundles required for the correct functioning of the page builder and its default components. The system jQuery version is 3.3.1. If you wish to use a different jQuery version (or link type) on your pages, you need to create your own bundle(s) with the corresponding path:

  • ~/bundles/jquery
  • ~/bundles/jquery-unobtrusive-ajax – bundle for using the jquery.unobtrusive-ajax.js JavaScript library (not to be confused with the jquery.validate.unobtrusive.js library)

When you register a bundle with one of these paths, the corresponding system bundle will no longer be linked automatically. You need to link your custom jQuery bundle manually (either within the used layout or directly in the page’s view) to ensure that the page builder works correctly.

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.

Tip: You can prepare the identifiers of allowed widgets as a string array, and then pass the array as a parameter of the EditableArea method.

Example



<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.

Note: The widget 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 placed in the area are not validated or removed.