Understanding custom "Content Fields" and "Content Parts": when to create custom "Content Fields"?

[MarGraz]

Hello,

I'm a newbie of Orchard Core and I'm currently diving deeper into Orchard Core to understand best practices. I've been following the "Dojo Course 3" video series, and videos 28 and 29 clearly explain how to create custom "Content Parts", which is useful for creating reusable components, such as a carousel module for example. I also read the documentation about custom Content Fields.

For example, as exercise I'm trying to develop a bookshop manager and I need to create a custom "Content Part" for a Book. I'd like to implement custom validation attributes on its properties, that utilize a regex. Additionally, I want this regex to be customizable from the Admin panel and perform the validation when the Admin add a new book to the DB.

Is this scenario appropriate for a custom "Content Field"?

In the past I used Umbraco, where it was very helpful to specify a validation regex for every field of an object I created.

My question is: how do you determine when you need a custom "Content Field"? In the "Content Parts", you can define your custom model with your custom types and complexity. So, when is it recommended to break it down into custom smaller pieces, and create custom Content Fields?

Thank you

[douwinga]

I am not much of a contributor to OrchardCore, so take this with a grain of salt (but have been using Orchard and OrchardCore for many years). I will explain how I think of things though and maybe it will help.

First, for your regex example, I would just use a custom editor for the existing text field. So then you would have an option like this on text fields

Content Fields are in a way similar to properties on a class, and then parts are the class (only true for parts that are just collections of fields). As a matter of fact you can create a content part class in code that does just that.

Basically I think of content fields as a way to display and edit a single value (like a form field, but displays its value on the frontend). The field may be storing more than just the value in the database, but it is still typically to support just displaying and editing a single value for the user.

Content Parts can be as simple as a collection of content fields, or can provide content items of the content type the part is on with additional functionality. For instance, we have a custom part called PrintPart. It provides the functionality for our content types to have a print button on them and then generate a printable PDF from a liquid template. In that case the part isn't even storing any values, and is just providing functionality.

Maybe some examples for custom fields and parts we have created would help?
We don't have many custom fields as the built in OrchardCore fields cover most things, but here are some examples:
Signature field - Allows users to draw their signature and stores it (we use OrchardCore for an app rather than a website, so users can actually edit content items on the frontend where this type of field makes more sense)
Range Field - A slider with a minimum and maximum value
Encrypted Text Field - Just a text field, but the value is stored in the database using the data protection provider, and an audit trail event is added whenever a user unprotects the value to view it

Some of our parts:
AddressPart - Just a collection of content fields to handle a full address (street, state, city, country, zip, etc)
HelpPart - Shows a button on page that provides a way to lookup help information based on the context of the content item
DuplicateDetectionPart - When a content item is saved, a check is done based on configured parameters to see if there is already a matching content item and prevents saving and links to the duplicate instead.
ChangeHistoryPart - Allows to display specified Audit Trail event types in a formatted way on the frontend

Does this help at all?

[MarGraz]

@douwinga, thank you for the effort you've put into writing those examples, they are really good. Why not include them in the "How to guides" section? If you're unable to do so, I can create a pull request and submit it. I think both examples are excellent starting points. Please, publish them.

From the first example, point number 10 is particularly interesting. I've never tried it before, but I will.

The second example is also very helpful. I'm curious to see how it applies to other fields, I will try it.

Thank you so much, really! 😊

[douwinga]

I don't think these would be good enough to go into an official how to guide. The first example should probably use a ContentFieldHandler and in the ValadatingAsync event it would do the validation instead of using the TextFieldRegExDisplayDriver.cs driver just for validation. I couldn't get that to work though, but something you should look into if you are going to do something similar. I haven't used the ContentFieldHandler Validating event in any of my own code since ContentFieldHandlers didn't always exist and we actually had our own implementation of them, but it does not include the Validating event.

Also, the first example should implement the actual editor view as I mentioned with the TextField-RegEx.Edit.cshtml so it truly is a custom editor. I am just using an older version of OrchardCore and there have been some changes that would affect how I would do that view if I was on the latest and I didn't want things to be too confusing.

In the second example I do not like var partFieldDefinition = context.Shape.GetType()?.GetProperty("PartFieldDefinition")?.GetValue(context.Shape) as ContentPartFieldDefinition; but I think it is the safest way to get the value. You could also cast it to a dynamic object ((dynamic)context.Shape).PartFieldDefinition I believe and get the value that way, but I think that could break. And since this executes on every shape you have to make it as safe as possible. Maybe a different example that does not need something like that would make more sense in official documentation.

Do remember, these are how I would implement things, I am not saying these are the best ways, or the way OrchardCore maintainers would do things. And as you said, the documentation should have some best practices and show the "correct" way of doing things to guide people.

[MarGraz]

We can open two other discussions and ask the community for contributions on these two examples before pulling them. What do you think? I believe it's a great way to enrich the documentation 😊
I will certainly keep both examples as a good starting point.

Regarding the first example, about TextFieldRegExDisplayDriver.cs, if you're considering moving the validation part out of the "display driver" class to adhere to the "single responsibility principle", I think you could adopt a similar approach to what I have done here, by using a "custom attribute" in IsbnFieldViewModel. The main challenge in your first example is retrieving the user input value and applying the custom attribute to that property. Perhaps we could extend the Orchard Core TextField class?

This is a concept, I haven't tried running it yet.
Here's a concept for the custom validation attribute ValidateWithRegExSettingAttribute class, to be created in a new "Helpers" > "DataAnnotations" folder within your module project.

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
public class ValidateWithRegExSettingAttribute : ValidationAttribute
{
    protected override ValidationResult IsValid(object value, ValidationContext validationContext)
    {
        // Here, you would need to access your settings to get the regex expression.
        // This is purely conceptual and might not work as expected in Orchard Core
        var settings = (TextFieldRegExEditorSettings)validationContext.GetService(typeof(TextFieldRegExEditorSettings));
        var expression = settings.Expression;
        var input = value as string;

        if (!string.IsNullOrWhiteSpace(expression) && !string.IsNullOrWhiteSpace(input))
        {
            var regex = new Regex(expression);
            if (!regex.IsMatch(input))
            {
                return new ValidationResult(ErrorMessage ?? "The input does not match the required pattern.");
            }
        }

        return ValidationResult.Success;
    }
}

Here how to apply the custom attribute to the input property. The challenge is to apply this attribute to a property that holds the user input to be validated. Since TextFieldRegExEditorSettings doesn't hold user input, this attribute would be applied elsewhere, in a context where the user input is available and the settings can be accessed. But where? 🤔

public class TextModel
{
    [ValidateWithRegExSetting(ErrorMessage = "The input does not match the required pattern.")]
    public string MyTextField { get; set; }
}

What do you think?

[douwinga]

To be honest, I don't have the motivation to help create an official guide as it just doesn't interest me enough. I would rather write about things that interest me, but wouldn't belong in the official docs like how to integrate Hangfire into OrchardCore, or how our dynamic index table feature works that allows users to "index" anything on content items to be used in queries. I hope to get to that some day on my blog.

I also am hoping to take contributing code to OrchardCore a bit more serious. So much to do, so little time, but I would like to give back where I am able to since I have been working with Orchard daily for years as the base for our apps. If only I could get work to pay for a bit of my time each week to give back 😜.

As for your attribute idea, I think you have already discovered the issue with that approach. It would be difficult to make extendable enough to work with all of the different editors.

[MarGraz]

Yes, it make sense. I love to participate to open source projects, and give back what I took. I'm new of Orchard Core, and I think it has really good potentiality, but it lacks of updated and best practice documentation. Ok that I can learn on the code, but today when you need to use something to create a project, you don't have one month to first learn all the code base, you need a best practice reference.

As for your attribute idea, I think you have already discovered the issue with that approach. It would be difficult to make extendable enough to work with all of the different editors.

If I find a nice way to do it, I will reply in this discussion.

Thank you so much 😊