Developing page builder sections

Sections are components which define the layout of widget zones within editable areas. You can define multiple different sections and allow content editors to choose from 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

Each section is implemented as a controller that returns HTML code containing widget zones.

Implementing section controllers

When creating controllers for sections, implement the default Index action which is used to retrieve the section markup. The action must return the section's HTML content, typically a partial view.

The recommended location to store section controllers is the ~/Controllers/Sections folder.

Do not disable POST requests for the Index action

POST requests cannot be disabled for the Index action (e.g., by using the HttpGet attribute). POST requests to the Index action are used in the page builder feature.

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

Registering sections

Register sections by adding an assembly attribute to the controller. Specify the following required 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.
  • Controller type – the type of the section controller class.
  • Display name – the name used to identify the section when displayed in the Kentico administration interface.
[assembly: RegisterSection("LearningKit.Sections.DefaultSection", typeof(DefaultSectionController), "Default section")]

Additionally, you can specify the following optional attribute parameters:

  • Description – the description of the widget displayed as a tooltip.
  • IconClass – the font icon class displayed when viewing the widgets in the widget list.
[assembly: RegisterSection("LearningKit.Sections.DefaultSection", typeof(DefaultSectionController), "Default section", Description = "A default section with one widget zone.", IconClass="icon-box")]

Localizing section metadata

To allow content editors to experience the page builder in their preferred UI culture, you can localize the display names and descriptions of sections.

Implementing section partial views

Create partial views 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.

The recommended location for the view files is the ~/Views/Shared/Sections folder:

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

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

Assigning a default section

Editable areas in the page builder have a default section, which is automatically added into empty areas. 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.

    var options = new PageBuilderOptions()
    {
    	// Specifies a default section for the page builder feature
    	DefaultSectionIdentifier = "Sections.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>

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 containing all .js and .css files located under ~/Content/Sections. The bundles are then linked on all pages with page builder editable areas.

The same bundles also contain script and stylesheet files added for widgets in the ~/Content/Widgets directory and inline property editors in the ~/Content/InlineEditors directory (inline editor scripts and styles are only included in the administration bundles, which are linked when pages are displayed in Edit mode within the Pages application of Kentico).

CSS notes
  • Only use the ~/Content/Sections directory to add basic styles that are required for the section to render correctly. Any site-specific styles that finalize the live site design of the section should be handled separately within the given site's main stylesheet.
  • To avoid potential conflicts between styles from other third-party components, we recommend adding a unique prefix to your CSS classes and identifiers (for example #CompanyName-mid-column), or employ similar measures to ensure their uniqueness.
  • Do not make any assumptions about the relative order of the source CSS in the resulting bundles – individual stylesheet files contained in the bundle may or may not precede each other.

Initializing section scripts

If you need to initialize scripts from the views of page builder sections (for example register an event listener), we recommend adding HTML Event Attributes to the section's elements.

The system does NOT run scripts defined in section views when displaying pages in the page builder editing interface. If you only need to run a script on page load for the live site, you can use a DOMContentLoaded event listener.

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.


Was this page helpful?