Contribute to Docs Contribute to Docs

Regions

Regions should be used for fixed occurrences of data on a Content Type, for example a Banner that always appear on the top. For content that can be placed anywhere in the content and occur any number of times Blocks are recommended.

Regions are the top-most level you can use to structure the different pieces of content. They are very flexible and can be configured in several ways, for example:

A single field region - for main content regions
A composite region made up of several fields
A sortable collection of both of the above.

Single Field Regions

When defining single field regions, the field type must be referenced directly from the Content Model. The deserializer does not support custom objects with a single field.

Correct Implementation

using Piranha.AttributeBuilder;
using Piranha.Models;

[PageType]
public class MyPage : Page<MyPage>
{
    [Region]
    public HtmlField Body { get; set; }
}

Incorrect Implementation

using Piranha.AttributeBuilder;
using Piranha.Models;

public class MyBody
{
    [Field]
    public HtmlField Body { get; set; }
}

[PageType]
public class MyPage : Page<MyPage>
{
    [Region]
    public MyBody HtmlBody { get; set; }
}

Region Configuration

When defining a region with the RegionAttribute you can set the following properties. Please note that all of these are totally optional.

Title

[Region(Title = "Main Content")]
public MarkdownField MainContent { get; set; }

Optional title to be shown in the manager interface. If this property is left empty the property name is used. The example below shows a single field region in a Content Type.

ListTitle

public class MyRegion
{
    [Field]
    public StringField Title { get; set; }

    [Field]
    public TextField Body { get; set; }
}

...

[Region(ListTitle = "Title")]
public IList<MyRegion> Teasers { get; set; }

The optional field name of a composite region that should be used when rendering the collapsed list items in the manager interface. The example below shows a composite region that is made up of a StringField and a TextField.

ListExpand

[Region(ListExpand = false)]
public IList<ImageField> Images { get; set; }

If the list item should be expandable or if the fields should be shown directly in the list. The default behavior is true but it can be useful to set it to false if you have a single field region or a very simple list region. The example below will create a list of image fields and show them directly in the list.

SortOrder

[Region(SortOrder = 1)]
public StringField Title { get; set; }

Optional sort order. This can be useful if you want to inherit a base class containing regions and you want to force them into being displayed in a certain way in the manager interface. The default sort order is in the order they are declared in the class.

Icon

[Region(Icon = "fas fas-fish")]
public StringField Title { get; set; }

The CssClass for the icon that should be used when rendering the region in the manager.

Display

[Region(Display = RegionDisplayMode.Setting)]
public MySeoInfo Seo { get; set; }

Defines how the region should be rendered in the manager. The following options are available to choose from:

Content - Displays the region in the content region of the page with a selection button.
Setting - Displays the region in the settings modal in its own tab
Hidden - The region is not rendered. This should be used if it's part of a custom editor.

Remember that it has to make sense to define regions as Settings, otherwise the content editors will most likely not find it when editing the content.

Region Description

[Region]
[RegionDescription("Optional header shown at the top of the page.")]
public MyRegion MyHeader { get; set; }

Optional description that is shown above the region in the manager. This can be used to provide guidance and help to content editors when editing content.

DocsDocumentation