Make ModelsBuilder Great (Again)

[JasonElkin]

N.B. This is not really about bringing back features that were present in "Full" ModelsBuilder

This is about making the ModelsBuilder we have in v9+ better.

The problem

ModelsBuilder is a bit of a blunt instrument and, I find, can result in cruft in larger or more complex projects.

Some examples...

public partial class MyDocType : IImplementAnInterface {

    // unless my property alias is the same as my interface, which isn't always possible/desired, 
    // I'm stuck with an extra property here.
    public string InterfaceProperty => this.PropertyWithDifferentName; 

    // I need to modify this property before it's used. 
    // Now I've got two properties on my model, and one of them shouldn't be used.
    ///<summary>
    /// other devs, please use THIS property and not <seealso cref="MetaDescription"/>  
    ///</summary>
    public string ActualMetaDescription => this.MetaDescription.Customize();

    // Here I need my model to convert to a different type than the default from the PropertyValueConverter.
    // Again, I don't actually want/need both properties in my model.
    public string MyStringProperty => this.Value<string>("PropertyThatIsntAString");

    // similar to above, null values can be very important in understanding if a value was chosen in the backoffice
    // as opposed to a default value - 01/01/0001 00:00:00 is not actually the same as null...
    public DateTime? NullValueIsRelevant => this.Value<DateTime?>("dateProperty");

}

Essentially, models often end up with just too much in them¹.

The start of a solution

Most of the unwanted properties can be removed simply with the ability to ignore certain properties when the model is generated, allowing us to provide our own implementation in a partial class.

Though it might nice to have a bit more control over model generation including the ability to:

1. Define a custom type/TypeConverter to use.
2. Rename properties.

In the long term, this could be controlled in any number of ways - dashboard, config, feature flags etc., and these could all be packages, but initially I'd just like to have an API that makes these options possible.

I'm currently thinking that this would be best achieved by adding a notification here, to be able to override the type models sent to the builder.

Does this make sense?

Does anyone else want this feature?
Does the approach make sense?
Will a PR that does this get approved 😉?

Footnotes

1. 🤓 This is really because ModelsBuilder models have more than one responsibility - they're both models for a published document (IPublishedContent) and viewmodels (they apply PropertyValueConverters that modify content for display). ↩

[abjerner]

I'm a bit surprised that no one has replied to this discussion yet. Maybe there aren't that many having complex requirements like the ones you describe? But we do 🖐️

Pretty much all our Umbraco 8 sites are headless sites, and we return the generated models via our API. So we rely on the legacy ModelsBuilder to allow us changing the models a bit more to our needs, add a custom base class, constructor etc.

---

I'm not entirely sure what you mean by type converters. Maybe it's similar to what we've been doing. For the individual property values, we have updated some of our packages to tailor the output:

• Skybrud.ImagePicker
  The Umbraco 8 package supports specifying an assembly qualified name of a class to be used as model. If set, this model is then returned by the value converted instead of the default type. We're in progress of updating this package to Umbraco 9.

• Skybrud.Umbraco.MultiNodeTreePicker
  For both Umbraco 8 and 9, this package has a pre-value option for selecting an item converter, which is then used for converting each IPublishedContent picked in the MNTP, letting is return a custom model for each item instead.

• Limbo.Umbraco.BlockList
  For both Umbraco 8 and 9, this package has a pre-value option for selecting a type converter, which is then used for converting the BlockListModel into either a desired model for the entire block list, or a collection of models for the items.

This gives us a lot more flexibility. For one, serializing ModelsBuilder models as-is can be quite dangerous in terms of circular references - even though we have a custom JSON contract resolver to handle the properties from Umbraco's models.

We've had some issues with page A having references to page B, which again has reference to page A - which would lead to these circular references when serializing to JSON. Besides also helping us minify the API output, this was one of the reasons I build the custom MNTP package. We can then have a minimalized item model which then don't expose those references.

Even if we look past the circular references, which you might not experience if you're doing regular MVC sites, I think it would be awesome to have the concept of type converters introduced for many of the build-in property editors in Umbraco.

---

As the legacy ModelsBuilder no longer seems to be in active development (even for Umbraco 8), I started dabbling a bit with my own ModelsBuilder-style package, but with some additional features to fit our needs as well.

I never really finished it for Umbraco 8, but as we have gotten used to working with the features of the legacy ModelsBuilder, I've picked up my package again, this time for Umbraco 9. My work so far can be found on GitHub in the Limbo.Umbraco.ModelsBuilder repository (still very much work in progress).

With models for regular pages, compositions and models for each block type element, we usually end up with a long list of models. Having these in the same folder quickly gets messy, so one feature in my package is to to place the models in relevant sub directories. By default, this means that member types are placed in a Members sub directory, media types in a Media sub directory, regular content types in a Content sub directory, and then element types in an Elements sub directory.

Ideally there would also be an option to follow the folder structure from the backoffice. This would especially come in handy when doing multiple sites in the same installation, as they may have individual models specific to each site.

The package also features an event / notifications system. For instance, there is a GetModelsNotification that let's you hook into when the package gathers the information about all the models, and modify the models where you need it - eg. rename properties like you're mentioning, but also ignore specific models - or again because we use Umbraco as a headless CMS, the package let's you specify the JSON.net settings of each property.

Although it's still a bit buggy for now, the package will also support decorating custom partial classes with an IgnorePropertyType attribute and their properties with ImplementPropertyType attributes. Similar to how it worked in the legacy models builder.

---

Besides re-using the build-in ModelsBuilder's section in appSettings.json, the package can for now really only be configured programmatically. Like you also describing, it would be awesome to have a dashboard or something similar in the backoffice to control how the models are generated. I haven't really looked in this part yet, but it should definitely be possible.

---

Like I mentioned, this package mostly started as a hobby project in my spare time for Umbraco 8, but as we now need this functionality for Umbraco 9, I'm now also using company time to work on it. So at the very least, we'll have this as an internal package.

I don't really have a clue how many people have needs beyond what is supported by the build-in ModelsBuilder. And I probably don't have the time to support this is a package also used by the Umbraco community, so I would very much appreciate if similar logic could be added to Umbraco. So perhaps it would be helpful to hear what HQ's plans are for the build-in ModelsBuilder (if they have any).

[JasonElkin]

Thanks @abjerner the package sounds great.

The TypeConverter is what gets used by this.Value<SomeType>("propertyOfSomeOtherType"); to convert the value returned from the PropertyValueConverter to the generic type you ask for - in this case SomeType. TryConvertTo is where the magic happens.

Last I heard, when I raised some issues against the embedded modelsbuilder, was that there were no plans to bring more features to it, but that was nearly two years ago now.

[hfloyd]

I love the "Full" VS Extension ModelsBuilder and have been DREADING moving to v9 due to not being sure about its compatibility... I feel like the "built-in" version (especially PureLive mode (ugh)) just doesn't meet my control-freakish needs. @abjerner I will likely be checking out your package in the near future...

[dawoe]

I missed this one. But I agree some extra flexibility would be nice. One is to ignore properties and another to implement your own in a custom class. Renaming would be nice, but not always needed in our case.

But like @JasonElkin mentioned I got to hear a while back Umbraco is happy with the current state of modelsbuilder and does not plan to add extra features.

[hfloyd]

As a plug for @abjerner's Limbo.Umbraco.ModelsBuilder... I used it VERY successfully on a v7 - > v9 migration project. It supports both these feature requirements.

[NikRimington]

I'm going to start by saying I love models builder. It's a brilliant tool for the Umbraco CMS, both the full version and the embedded version.

I have 2 wish list ideas for the embedded one.

1. I would it to show the same level of extensibility as the CMS does. The ability to customise how your models are produced in a variety of ways would be great. I don't have examples to hand right now, but there have been times when I've wanted to be able to make small tweaks but haven't been able to.

2. I would love it if Dictionary items could generate a single "DictionaryAliasses" class automatically that followed the hirearchy in the dictionary section to make accessing the aliases safer.

For example:

public static class DictionaryAliases
{
     public const String TopLevelDictionaryItemWithNoChildren = "Top Level Dictionary Item With No Children";
    
     public static class TopLevelDictionaryItemWithChildren
     {
             public const string Alias = "Top Level Dictionary Item With Children";
             public const string FirstChildNode = "First Child Node";
     }
}

I hope that makes some sort of sense. Then dictionary items can be a) Compile time safe, and b) runtime exception caught. They can be accessed like this: DictionaryAliases.TopLevelDictionaryItemWithChildren.Alias

[hfloyd]

As a plug for @abjerner's Limbo.Umbraco.ModelsBuilder... I used it VERY successfully on a v7 - > v9 migration project.

It supports a nicely extensible model-building setup (see: GetModelsNotification)

And, I'm sure any Dictionary-related PRs would be accepted ;-)

[abjerner]

I'm already creating a manual file for this when I'm doing localization, so could make sense to add this to our custom models builder. I'd be happy to look at a PR for this - or work a bit on it my self when I have the time.

[hfloyd]

For your convenience, @NikRimington & @abjerner : limbo-works/Limbo.Umbraco.ModelsBuilder#11