Contribute to Docs Contribute to Docs

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 in the section Content.

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.

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.

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 or Horizontal. The default setting 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.

DocsDocumentation