Contribute to Docs Contribute to Docs

Custom Block Groups

This article covers how to implement custom block groups for Piranha. If you want to read more about the standard blocks included, please refer to Blocks.

A Block Group is a special kind of block that can have child items. Just like regular blocks, block groups can have Field Properties defined. These fields are global for the group and are displayed above the actual items.

Please note that block groups can not contain other block groups as items, so they can't be used to build a recursive structure.

Reserved Names

When naming your components, whether it's fields, blocks or block groups you should stay clear of the names already used by the internal components of the Piranha manager.

  • block-group-horizontal
  • block-group-vertical
  • block-group
  • folder-item
  • generic-block
  • page-item
  • pagecopy-item
  • post-archive
  • region
  • sitemap-item

Creating a Block Group

The main difference between creating a custom block and a block group is that they inherit from different base classes and uses different attributes for their meta data. All block groups must inherit from the base class Piranha.Extend.BlockGroup.

As an example, let's take a look how the Gallery block group is implemented.

using Piranha.Extend;
using Piranha.Extend.Fields;

[BlockGroupType(Name = "Gallery", Category = "Media", Icon = "fas fa-images")]
[BlockItemType(Type = typeof(ImageBlock))]
public class ImageGalleryBlock : BlockGroup
{
}

Block Group Configuration

In order to register your block group you need to mark it with the BlockGroupType attribute like in the above example. This attribute has the following properties:

Name
public string Name { get; set; }

This is the name that is shown in the manager interface when editing.

Category
public string Category { get; set; }

The name of category the block group will be grouped under in the manager interface.

Icon
public string Icon { get; set; }

Css class for redering the block group icon in the manager interface. The manager interface uses the free icon package from font awesome.

Display
public BlockDisplayMode Display { get; set; }

Determines how the group should be rendered in the manager interface. The available options are:

  • MasterDetail - Displays the group with an item list to the left and the selected item to the right.
  • Horizontal - Displays the group items in a horizontal columns.
  • Vertical - Displays the group items in a vertical list.

The default setting for this property is MasterDetail

Limiting Child Item Types

If you want you can limit the types of blocks that can be positioned within your group. This is done by adding one or several BlockItemType attributes to you class. As an example, the Image Gallery above only accepts child items of the type ImageBlock.

Type
public Type Type { get; set; }

The item type of the block that should be allowed inside the group.

Global Fields

If you want your block group to have global fields you just add them to your block group class. Let's for example say that we'd like to add a title for our entire image gallery:

using Piranha.Extend;
using Piranha.Extend.Fields;

[BlockGroupType(Name = "Gallery", Category = "Media", Icon = "fas fa-images")]
[BlockItemType(Type = typeof(ImageBlock))]
public class ImageGalleryBlock : BlockGroup
{
    public StringField Title { get; set; }
}

Register The Block Group

Block groups are registered in the same way as regular blocks. For more information, please read the article about Blocks.

Create The Manager Component

No specific Vue component is needed to render block groups.