Ordered metadata

[laurentkempe]

Is there a way to get metadata in the order in which those are declared in a YAML file for example?

Let say I have the following sidebar.yml

sidebar:
  menu:
    home:
      title: global.home
      url: /
      icon: fa fa-home
    archives:
      title: global.archives
      url: /all-archives
      icon: fa fa-archive
    presentations:
      title: global.presentations
      url: /presentations.html
      icon: fa fa-file-powerpoint
    about:
      title: global.about
      url: /about-laurent-kempe.html
      icon: fa fa-question

I would like to be able to render in the same order declared in the file.

I cannot find a way to achieve that, any idea appreciated?

[daveaglick]

Unfortunately the metadata is inherently unordered because it's implemented at a very low level as a dictionary. Very early in the project I experimented with some sort of ordering for metadata, but it quickly became intractable because of the way metadata is layered from global settings all the way down through document cloning, etc. There are just too many places it could come from and be overridden to establish a single ordering methodology.

That said, what you want to do here isn't an unusual pattern. I usually accomplish it by adding an order item (I.e. order: 1, etc.) and then sorting on that where it needs to be ordered. There's even a strongly-typed Keys.Order key you can use in the Razor code instead of magic strings.

[laurentkempe]

Thanks @daveaglick I thought it was the case due to the dictionary, but said to myself, I might miss something!
My initial goal was to get all the configuration files from my original blog as is, but I will add an order and my problem will be gone!

[laurentkempe]

Works like a charm @daveaglick, in fact I am using TypeConverter extensively to build a model out of the yaml so that I can build my Razor code with strongly typed objects.

I have the following yaml

sidebar:
  menu:
    order: 1
    home:
      order: 1
      title: global.home
      url: /
      icon: fa fa-home
    archives:
      order: 2
      title: global.archives
      url: /all-archives
      icon: fa fa-archive

And my converters

[TypeConverter(typeof(SideBarTypeConverter))]
public record SideBar(IEnumerable<SideBarMenu> SideBarMenus)
{
    public static string Key => "sidebar";
}

public class SideBarTypeConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType) 
        => sourceType.IsAssignableTo(typeof(IMetadata));

    public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
    { 
        if (value is not IMetadata menus) return default;

        return new SideBar(TypeHelper.Convert<IList<SideBarMenu>>(menus).OrderBy(m => m.Order));        
    }
}

[TypeConverter(typeof(SideBarMenuTypeConverter))]
public record SideBarMenu(string Name, int Order, IEnumerable<SideBarButton> SideBarButtons);

public class SideBarMenuTypeConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType) 
        => sourceType.IsAssignableTo(typeof(KeyValuePair<string, object>));

    public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
    { 
        if (value is not KeyValuePair<string, object> menu) return default;
        
        if (menu.Value is not IMetadata metadata) return default;

        var barButtons = TypeHelper.Convert<IList<SideBarButton>>(menu.Value);
        var sideBarButtons = barButtons.Where(button => button is not null).OrderBy(sbb => sbb.Order);
        
        return new SideBarMenu(menu.Key, metadata.GetInt("order"), sideBarButtons);
    }
}

[TypeConverter(typeof(SideBarButtonTypeConverter))]
public record SideBarButton(string Name, int Order, string Title, string Url, string Icon);

public class SideBarButtonTypeConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType)
        => sourceType.IsAssignableTo(typeof(KeyValuePair<string, object>));

    public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
    { 
        if (value is not KeyValuePair<string, object> menuButton) return default;

        if (menuButton.Value is not IMetadata metadata) return default;

        return new SideBarButton(menuButton.Key, metadata.GetInt("order"), metadata.GetString("title"), metadata.GetString("url"), metadata.GetString("icon"));
    }
}

Then my Razor code is clean and easy to write

@foreach(var menu in Context.GetSidebar().SideBarMenus)
{
    <ul class="sidebar-buttons">
    @foreach (var (_, _, title, url, icon) in menu.SideBarButtons)
    {

Now my menu is built correctly

[laurentkempe]

IMHO UniversalTypeConverter could be improved by not inserting in collection null!

For example, for my SideBarButtonTypeConverter when I do the following

public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
{
    if (value is not KeyValuePair<string, object> { Value: IMetadata metadata } menuButton) return default;

with yaml like that

menu:
  order: 1
  home:
    order: 1
    title: global.home

My converter will return default, so null, in the case of order: 1, then for the second entry home: it will return a correctly initialized object. UniversalTypeConverter insert this null in the collection and I think it should not.

barButtons.Where(button => button is not null).OrderBy(sbb => sbb.Order);

[daveaglick]

This is stretching my recollection a bit since the UniversalTypeConverter goes back almost 5 years to the earliest days of Wyam, but I think I went down this same road at one point and ended up with the current behavior because it preserves as much information as possible. For example, it maintains the same number of elements as the original collection. Then, if the unconverted default items are not needed, it's easy enough to filter them out as you found.

While it could be worth some additional exploration to see if that's still the "right" way (C# looked pretty different back then too), it's probably a moot point since so much is built on top of that functionality and I'd worry about breaking things in subtle, untested ways.

In general though, I love what you're up to! Especially using the type converter in the first place. It's one of the most powerful yet poorly documented parts of the whole framework, so I'm glad you found it and are using it successfully!

[laurentkempe]

because it preserves as much information as possible. For example, it maintains the same number of elements as the original collection.

That was the argument I thought that would make sense 👍🏼

it's probably a moot point since so much is built on top of that functionality and I'd worry about breaking things in subtle, untested ways.

As you mentioned it can be easily filtered out, so it is not a problem. You just need to know it or learn it. In my case, it was throwing. I had to dig deeper to understand where is this null coming from, it was not immediately obvious.

In general though, I love what you're up to! Especially using the type converter in the first place. It's one of the most powerful yet poorly documented parts of the whole framework, so I'm glad you found it and are using it successfully!

Thanks. I found the documentation useful to understand the concept from a high level point of view, so it is not as bad as that! And it is truly powerful, this I agree.