How To Setup Content

Last Updated: 2018-10-23

In Piranha CMS there are three primary types of content, Pages, Posts and Sites. It's up to you to setup the content types you need for these types and do it in a way that helps the editors keep the website alive and current.

Page Types

Pages are used to build the hierarchical structure of your site. In most applications you will end up with more Page Types than any other type of content, so it's good to really think through what you need before getting started. Pages can be regular pages or archive pages which are used to hold a post repository.

Post Types

Posts are articles that stand on there own. They can't be position in any other way than the fact that they will reside under an archive page. On the other hand posts can be categorized and tagged for filtering.

Site Types

You can also create content types for sites which can be used to handle any site global content. Please note that it is totally optional to assign a content type to a site as you can simply use the site as a container for your pages.

Components

In this article we will mainly talk about the components Blocks, Regions and Fields, that you have available when creating content types. Detailed information and examples on how to create the specific types can be found in their respective section Page Types, Post Types and Site Types.

Blocks

Blocks should be used for pieces of content that can occur any number of times, at any position in the main content area. For fixed elements with a fixed number of occurrences Regions are a better match.

Blocks are the main building piece for pages and posts, it's the part of the content that the editor has total control over. Blocks are small chunks of content that can be added, deleted and reordered. As the content administrators choose for themselves which blocks they add you don't specify anywhere on the Content Type which blocks to use.

To read about the different block types that are available out-of-the box, please refer to Standard Blocks. For information on how to build your own blocks, please refer to Custom Blocks.

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; }
}

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

Region Properties

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

Title

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.

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

ListTitle

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.

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

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

...

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

ListExpand

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.

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

SortOrder

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.

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

Description

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.

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

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

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

Fields

Fields are the lowest level of content in Piranha CMS and are used to build up Regions and Blocks. You can think of Fields as the different data types that you can use to build structures with. When defining a field in your Region or Block you can set the following properties with the FieldAttribute.

Title

Optional title to be shown in the manager interface. If this property is left empty the property name is used.

public class MyRegionarbitrary
{
[Field(Title = "The Title")]
public StringField Title { get; set; }

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

Options

A set of flags defining additional field behavior. At the moment the only flag available is HalfWidth which tells the manager interface that the field should only take up 50% of the available space so that another field can be display next to it.

public class MyRegion
{
[Field(Options = FieldOption.HalfWidth)]
public StringField Title { get; set; }

[Field(Options = FieldOption.HalfWidth)]
public StringField SubTitle { get; set; }

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

Placeholder

Optional placeholder text. The placeholder text is shown for CheckBoxField, DateField, NumberField and StringField. For the CheckBox Field the placeholder text is shown as the checkbox label.

[Field(Placeholder = "Please enter your full name")]
public StringField { get; set; }

For a complete description of the available field types, please refer to Standard Fields.