abjerner / limbo.umbraco.blocklist

Extended block list editor for Umbraco.

Limbo Block List

This package extends the default block list property editor in Umbraco, making it possible to control the CLR type returned by our version of the block list property editor.

License:	MIT License
Umbraco:	Umbraco 13 (and Umbraco 10-12, Umbraco 9 and Umbraco 8)
Target Framework:	.NET 8 (and .NET 6, .NET 5 and .NET 4.7.2)

But why?

The default block list property editor exposes the value as an instance of BlockListModel representing the invividual blocks as they are added by users in the backoffice.

If you wish to interpret the BlockListModel a bit before rendering the block list on the website, there is a few different ways to go about this. With this package, you can select a type converter which is then used for converting BlockListModel to a desired type.

For us at @limbo-works, we find this particular usefull as we can use a type converter to control the output for our headless API, thereby better being able to tailor the output for our frontenders.

Installation

The Umbraco 13 version of this package is only available via NuGet. To install the package, you can use either .NET CLI:

dotnet add package Limbo.Umbraco.BlockList --version 13.0.0

or the NuGet Package Manager:

Install-Package Limbo.Umbraco.BlockList -Version 13.0.0

Umbraco 9
For the Umbraco 9 version of this package, see the v2/main branch instead.

Umbraco 8
For the Umbraco 8 version of this package, see the v1/main branch instead.

Examples

To create your custom type converter, you can implement the IBlockListTypeConverter interface. In the example below, the type converter will return a flat array of BlockItem representing the individual block list items - or if the maximum amount of blocks it set to 1, an instance BlockList:

using System;
using System.Linq;
using Limbo.Umbraco.BlockList.Converters;
using Limbo.Umbraco.BlockList.PropertyEditors;
using Umbraco.Cms.Core.Models.Blocks;
using Umbraco.Cms.Core.Models.PublishedContent;

namespace UmbracoTests.BlockList {
    
    public class BlockListTypeConverter : IBlockListTypeConverter {

        public string Name => "Block Item Converter";

        public Type GetType(IPublishedPropertyType propertyType, LimboBlockListConfiguration config) {
            return config.IsSinglePicker ? typeof(BlockItem) : typeof(IReadOnlyList<BlockItem>);
        }

        public object? Convert(IPublishedElement owner, IPublishedPropertyType propertyType, BlockListModel? source, LimboBlockListConfiguration config) {

            if (source == null) return config.IsSinglePicker ? null : Array.Empty<BlockItem>();

            if (!config.IsSinglePicker) return source.Select(x => new BlockItem(x)).ToArray();

            BlockListItem? first = source.FirstOrDefault();
            return first == null ? null : new BlockItem(first);

        }

    }

}

using System;
using Umbraco.Cms.Core.Models.Blocks;
using Umbraco.Extensions;

namespace UmbracoTests.BlockList {
    
    public class BlockItem {

        public Guid ContentKey { get; }

        public string Type { get; }

        public IPublishedElement Content { get; }

        public BlockItem(BlockListItem blockListItem) {
            ContentKey = blockListItem.Content.Key;
            Type = blockListItem.Content.ContentType.Alias;
            Content = blockListItem.Content;
        }

    }

}

By creating your own class implementing the IBlockListTypeConverter interface, it will show up for the Type Converter option on the data type:

limbo.umbraco.blocklist's Issues

Consider providing additional detail to the listing at the Umbraco marketplace

Hi @abjerner - I noted you'd listed this package on the Umbraco marketplace, so firstly, thanks for taking the time to do that. I noticed though that we only have the details collected from NuGet for the package... which is fine, but to help it to be found more easily it's possible to provide additional information, as is discussed here.

For example, you can add a category that the package will be shown under, and also provide additional descriptions or "read me" content to better describe what the package does and what benefits developers would get from installing it.

To use this you would need to first add a ProjectUrl to your .cproj file, which would then go into the NuGet package.

Then you can create a file in the folder of the project URL you are referencing, and populate it with the additional information in JSON format, as per the documentation linked above.

I won't spam you with issues but I believe the same applies to the following packages too:

• Limbo.Umbraco.Boolean
• Limbo.Umbraco.MultiNodeTreePicker
• Limbo.Umbraco.Rte
• Limbo.Umbraco.Separator

I hope the above is useful and thanks again for helping get the new website populated with the full range of extensions available to the Umbraco community.