Developing page builder sections

Sections are components which define the layout of widget zones within editable areas. You can define any number of different sections and allow content editors to choose them in the Pages application.

The system provides a built-in Default section containing a single widget zone. If you wish to use more advanced layouts in the page builder, you need to develop and register your own sections.

Developing sections

On a basic level, page builder sections are pieces of HTML output code containing widget zones. The main step in the development of a section is to create a partial view that defines the output.

Within the MVC architecture, the section partial view is served by a controller and a model is used to pass any required data. In many cases, sections can utilize a default controller and view model provided by the Kentico API. See the following scenarios for more information:

• Basic sections
• Sections with a custom controller

In both cases you can develop sections with properties, which allow content editors to adjust the section appearance or behavior directly in the Kentico administration interface. For sections with configurable properties, you need to create an additional model class that represents the section properties. For information about this more advanced scenario, see Defining section properties.

Basic sections

Use the following process to develop a page builder section:

1. Create a partial view with code that defines the required layout.
   • Use the WidgetZone extension method to identify locations where widgets can be placed. Every section must contain at least one widget zone – sections without widget zones are not supported.
   • We recommend storing section views in the ~/Views/Shared/Sections folder, and using a view name that matches the identifier assigned to the section upon its registration prefixed with the underscore ('_') character.
   • Alternatively, you can use any required view location or name, and then specify it when registering the section.

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

<div>
    @Html.Kentico().WidgetZone()
</div>

2. Register the section into the system. See Registering sections.

With this approach, the section's view is automatically displayed using a default controller provided by the Kentico API. The values of any properties defined for the section can be passed to the view by using the default ComponentViewModel<TPropertyModel> class as the model.

Sections with a custom controller

When developing sections with advanced functionality, you may need to take full control over the section's logic. You can do this by implementing the section's controller and view model, in addition to the partial view. This allows you to run any custom code within the section's controller, pass any type of required data to the view, or even switch between completely different views based on the current scenario.

The following steps describe the advanced development process for sections:

1. Create a controller class for the section.
   • We recommend storing section controllers in the ~/Controllers/Sections folder.
2. Make the controller inherit from the SectionController base class (available in the Kentico.PageBuilder.Web.Mvc namespace).
3. Implement the default Index action in the controller, which is used to retrieve the section markup. The action must return the section's HTML content, typically a partial view.
   • Do not disable POST requests for the Index action (e.g., by using the HttpGet attribute). POST requests to the Index action are used in the page builder feature.
   • Section controller actions used to retrieve the markup cannot be asynchronous (cannot use the asyncfunction declaration). Actions that render section markup are called as child actions when rendering the markup of an editable area, but MVC 5 does not support asynchronous child controller actions.

public class DefaultSectionController : SectionController
{
    // GET action used to retrieve the section markup
    public ActionResult Index()
    {
        return PartialView("Sections/_DefaultSection");
    }
}

// Gets the page of the Article page type containing the currently processed section
var article = GetPage<Article>();

4. Create any required view model classes used to pass data from the section controller to the partial view.

   • We recommend storing section models in the ~/Models/Sections/<section name> folder.

5. Prepare a partial view that defines the output of the section.

   • Use the WidgetZone extension method to identify locations where widgets can be placed. Every section must contain at least one widget zone – sections without widget zones are not supported.
   • We recommend storing section views in the ~/Views/Shared/Sections folder.

6. Register the section into the system. See Registering sections.

With this advanced development approach, you have full responsibility and control over the section's controller, view model, and partial view.

Registering sections

Every section needs to be registered into the system to be available in the page builder. Register sections using the RegisterSection assembly attribute (available in the Kentico.PageBuilder.Web.Mvc namespace).

To register basic sections (without a custom controller class), we recommend adding the assembly attributes to a dedicated code file. For example, you can create a file named PageBuilderComponentRegister.cs in your project's ~/App_Start folder and use it to register your page builder components. For basic sections, specify the following attribute parameters:

• Identifier – the unique identifier of the section. We recommend using a unique prefix in your section identifiers to prevent conflicts when deploying sections to other projects, for example matching your company's name.

• Name – the name used to identify the section when displayed in the Kentico administration interface.

• PropertiesType – only required for sections with properties. Specifies the System.Type of the section's property model class.

• (Optional) CustomViewName – specifies the name and location of the view that defines the section's output. If not set, the system searches for a corresponding _<Identifier>.cshtml view in the ~/Views/Shared/Sections folder.

  C#Basic section registration example

  Copy

  [assembly: RegisterSection("CompanyName.DefaultSection", "Default section", typeof(CustomSectionProperties), "Sections/_DefaultSection")]

For sections with a custom controller, you can add the assembly attribute directly into the controller code file (above the controller class). In this case, specify the following attribute parameters:

• Identifier – the unique identifier of the section. We recommend using a unique prefix in your section identifiers to prevent conflicts when deploying sections to other projects, for example matching your company's name.

• ControllerType – the System.Type of the section's controller class.

• Name – the name used to identify the section when displayed in the Kentico administration interface.

  C#Controller section registration example

  Copy

  [assembly: RegisterSection("CompanyName.DefaultSection", typeof(DefaultSectionController), "Default section")]

When registering any type of section, you can also set the following optional attribute properties:

• Description – the description of the section displayed as a tooltip.
• IconClass – the font icon class displayed when viewing the sections in the section list.

[assembly: RegisterSection("CompanyName.DefaultSection", typeof(DefaultSectionController), "Default section", Description = "A default section with one widget zone.", IconClass="icon-box")]

Assigning a default section

Editable areas in the page builder have a default section, which is automatically added when the area is empty. This includes new areas where content editors have not yet placed any other section, and scenarios where an editor removes the last section from an area.

By default, the system's built-in Default section is used for this purpose. For most websites, we recommend replacing the default section with your own to ensure that the page builder output code exactly matches the requirements of your website's styling and design.

To specify a global default section, extend the code that registers the page builder feature in your MVC project:

1. Create a PageBuilderOptions object and set its DefaultSectionIdentifier property to the identifier of the appropriate section.

2. To disable the system's built-in Default section, also set the RegisterDefaultSection property to false.

   Warning: If your site already has existing pages that use the page builder, replace all occurrences of the Default section in page content before you disable it. Otherwise an error will occur on the given pages.

3. Pass the PageBuilderOptions object as the parameter of the UsePageBuilder method.

   C#

   Copy

   var options = new PageBuilderOptions()
   {
       // Specifies a default section for the page builder feature
       DefaultSectionIdentifier = "CompanyName.DefaultSection",
       // Disables the system's built-in 'Default' section
       RegisterDefaultSection = false
   };
   
   // Enables the page builder feature
   builder.UsePageBuilder(options);

Empty editable areas now use the new default section. The change does NOT modify the sections within existing page builder content.

You can also override the global default section for individual editable areas – set the identifier of the appropriate section as a parameter of EditableArea methods in your views.

<div>
    @Html.Kentico().EditableArea("areaWithSection", defaultSectionIdentifier: "LearningKit.Sections.Col5050")
</div>

Storing files for use in the page builder

You may wish to develop sections that use or display various files. You can store such files in the system either as page attachments or using media libraries. These two approaches vary in different ways:

• Page attachment files are associated only with a specific page. You should store media files as page attachments only if the files are considered to be a content of a particular page (e.g. a language specific variant of an image).
• Media library files are available for all pages of a particular site. You should store files using media libraries when the file content is reusable or the files are more relevant to the general visual design of the page than to its content (e.g. a background image used on all pages with a similar layout).

This is important to remember especially when creating custom page templates from existing pages. New pages created using templates do not display any page attachments, because the attachments stay as content bound to the original pages. On the other hand, pages based on templates display media library files automatically.

Adding scripts and styles for sections

To add JavaScript and CSS styles required by your page builder sections, place script and stylesheet files into sub-folders under the ~/Content/Sections directory of your MVC project (you may need to create the Sections directory). Use sub-folders that match the identifiers of individual sections, or a Shared sub-folder for assets used by mutliple sections.

The system automatically creates bundles⁠ (opens in a new tab) containing all .js and .css files located under ~/Content/Sections. The bundles are then linked on all pages with page builder editable areas.

Initializing section scripts

If you need to initialize scripts (for example call a function on page load or register an event listener), you can add script tags directly into the view code of your page builder sections. However, you need to keep the following in mind:

• Do not rely on the order of execution of multiple script tags within one section. The order of their execution may be different in the page builder interface than on the live site.

• If you declare variables within section script tags, the variables are defined in the global namespace. To prevent conflicts on pages containing multiple instances of the same section, wrap the scripts into a self-executing anonymous function.

• If you use assets stored in the ~/Content/Sections folder within the section views, the related bundles are added at the end of the HTML document's body tag. Such assets are not available in the section code during the page load process. A solution is to run the initialization script during the DOMContentLoaded⁠ (opens in a new tab) event. However, sections in the page builder interface may be added dynamically after the page is loaded. In this case, the DOMContentLoaded event has already occurred and will not fire again. For example, the following script demonstrates how to reliably call a custom function on page load:

  C#

  Copy

  @using Kentico.PageBuilder.Web.Mvc
  @using Kentico.Web.Mvc
  
  <div>
      @Html.Kentico().WidgetZone()
  </div>
  <script type="text/javascript">
  (function () {
      if (document.readyState === "loading") {
          // Calls the function during the 'DOMContentLoaded' event, after the HTML document has been completely loaded
          document.addEventListener("DOMContentLoaded", function () {
              customFunction();
          });
      } else {
          // Calls the function directly in cases where the section is rendered dynamically after 'DOMContentLoaded'
          customFunction();
      }
  })();
  </script>

Apart from initialization code, avoid linking or executing scripts directly within section views. This could lead to duplicated scripts on pages that contain multiple instances of the same section.