v2.0 and Display Management changes

[kevinasdzine]

I'm trying to convert an OC v1.8 solution to v2.0 and I'm not finding a good description on what new methods to use in regard to display management methods removed in v2.0.

Here's my example. I have a content type "CalendarEvent" - my drivers and templates for the individual event items work the same way on v2.0 but my controller, that gives me a list of events for the next month, does not.

Previously, an MVC controller that needed to return collections of content items worked like this:

• Define a non-ContentType class that contains a collection of the desired ContentType items - in this case CalendarEventList.
• Query for the desired collection and instantiate the afore mentioned object and populate its ContentType collection with the results of the query - an instance of CalendarEventList contains a list named CalendarEvents (IEnumerable).
• Call BuildDisplayAsync on CalendarEventList and return that result as the view of the controller
• To support the BuildDisplayAsync, a display driver needs to be created:
• services.AddScoped<IDisplayDriver<CalendarEventList>, CalendarEventListDisplayDriver>(); services.AddScoped<IDisplayManager<CalendarEventList>, DisplayManager<CalendarEventList>>();
• and that display driver needed an override method of Display:
• public override IDisplayResult Display(CalendarEventList model, IUpdateModel updater) which is where we would BuildDisplayAsync for each of the CalendarEvent items in the collection
• The shape for the CalendarEventList would then be rendered by its template CalendarEventList.Detail.cshtml and the appropriate HTML markup would be used (e.g. create a table representing a calendar view and fill in the appropriate day cells with corresponding events rendered by their template CalendarEvent.Summary.cshtml)

However, public override IDisplayResult Display(CalendarEventList model, IUpdateModel updater) is no longer available and public override IDisplayResult Display(CalendarEventList model, BuildDisplayContext context) does not function as a replacement

InvalidOperationException: Unable to resolve service for type 'OrchardCore.DisplayManagement.DisplayManager`1[EventCalendar.Models.CalendarEventList]' while attempting to activate 'EventCalendar.Controllers.CalendarEventController'.

And all I have been able to find on github or the docs so far is that various display management methods have been removed but not what their replacements are.

I'm using this pattern for a number of controllers that return curated collections of content items.

Can anyone tell me what the recommended replacement for this controller pattern is under v2.0?

[Piedone]

We removed IDisplayResult Display(CalendarEventList model, IUpdateModel updater) because it didn't really make sense: if you want to use IUpdateModel to update the model, use an editor. Why do you need it?

[kevinasdzine]

Because BuildDisplayAsync requires an updater. I just want my controllers to be able to return a shape from a POCO that contains a list of ContentType shapes so that I have one template that renders the list as a whole and one template that renders each list item.

[Piedone]

But why does it need an updater? Where do you use that updater? What you describe should be possible without it.

[kevinasdzine]

Somebody at Lombiq game me this pattern three or four years ago.

• BuildDisplayAsync needed an updater as the second parameter so...
• Controlers inherited IUpdateModel and passed this as the second parameter of their BuildDisplayAsync calls for the POCOs
• The DisplayDriver for the POCOs used IDisplayResult Display(POCO model, IUpdateModel updater).
• The DisplayDriver for the contained ContentTypes used IDisplayResult Display(ContentPart model, BuildPartDisplayContext context) and used context.updater for their BuildDisplayAsync calls

So I used that same pattern for many controllers that returned collections of content items within containing POCOs

If that's not the pattern I should be using (or should have used at the time) I'm good with that. Where do I find the recommended pattern for controllers to return collections of content items such that, in my theme, I have a template for the collection and a template for the items? (that's the endgame, not whether or not it uses an updater)

Thanks

[Piedone]

You only really need the updater if you want to update the model with the model binder (like from POST data), which should only be necessary for editors. So, you don't need to pass the updater around. Just use/call the overloads without it.

[kevinasdzine]

Cool! Thank you.

So I can pass null for the updater parameter and it works (did it always work, even before v2.0?). I can replace IDisplayResult Display(POCO model, IUpdateModel updater) with IDisplayResult Display(POCO model) and my controllers work again under v2.0.

However, that too is expected to go away.

• What is the recommended way to perform Initialize<POCO_ViewModel>() in DisplayDrivers going forward?
• Or, more to the point, what's the recommended way to create Shapes from controller views?

[MikeAlhayek]

Don't pass null or use obsolete methods. Instead follow these steps #16807 (comment)

[gvkries]

@MikeAlhayek You did a lot of changes to display management in v2, maybe you can clarify this for him.

[ns8482e]

IMO, Ideally api methods that defined on interfaces and core classes should not be removed on next version instead should be marked as obsolete, to allow time to api consumers to react to changes, rather blocking then on upgrades

[Piedone]

That's the principle in theory, but in this case, something was necessary to remove due to how these overloads called each other.

[ns8482e]

For my awareness, Can you please share any documentation or discussion or issue link that you know - that describes these changes and why's necessary? May be we need to document the changes in doc and clear path for upgrades

[Piedone]

#16508

[MikeAlhayek]

@kevinasdzine,

You don't need to register a DisplayManager. So remove the following line:

services.AddScoped<IDisplayManager<CalendarEventList>, DisplayManager<CalendarEventList>>();

@kevinasdzine @ns8482e,
The following methods have been removed, with updated alternatives provided:

• Task<IDisplayResult> DisplayAsync(TModel model, IUpdateModel updater) → Use DisplayAsync(TModel model, BuildDisplayContext context) where the Updater property is available via context.
• IDisplayResult Display(TModel model, IUpdateModel updater) → Use Display(TModel model, BuildDisplayContext context) where the Updater property is available via context.
• Task<IDisplayResult> UpdateAsync(TModel model, IUpdateModel updater) → Use UpdateAsync(TModel model, UpdateEditorContext context) where the Updater property is available via context.
• Task<IDisplayResult> EditAsync(TModel model, IUpdateModel updater) → Use EditAsync(TModel model, BuildEditorContext context) where the Updater property is available via context.
• IDisplayResult Edit(TModel model, IUpdateModel updater) → Use Edit(TModel model, BuildEditorContext context) where the Updater property is available via context.

In addition, we've introduced new static methods in the DisplayDriverBase class:

• Task<IDisplayResult> CombineAsync(params IDisplayResult[] results)
• Task<IDisplayResult> CombineAsync(IEnumerable<IDisplayResult> results)

The same refactoring applies to the SectionDisplayDriver class. The following methods are now obsolete:

• Display(TSection section, BuildDisplayContext context)
• Display(TSection section)
• Edit(TSection section, BuildEditorContext context)
• UpdateAsync(TSection section, UpdateEditorContext context)
• UpdateAsync(TSection section, IUpdateModel updater, string groupId)

And the following methods have been removed, with updated alternatives:

• UpdateAsync(TModel model, TSection section, IUpdateModel updater, UpdateEditorContext context) → Use UpdateAsync(TModel model, TSection section, UpdateEditorContext context) where the Updater is available via context.
• UpdateAsync(TSection section, IUpdateModel updater, UpdateEditorContext context) → Use UpdateAsync(TModel model, TSection section, UpdateEditorContext context) where the Updater is available via context.
• UpdateAsync(TSection section, IUpdateModel updater, string groupId) → Use UpdateAsync(TModel model, TSection section, UpdateEditorContext context) where the Updater and GroupId properties are available via context.
• UpdateAsync(TSection section, UpdateEditorContext context) → Use UpdateAsync(TModel model, TSection section, UpdateEditorContext context) where the Updater is available via context.
• EditAsync(TSection section, BuildEditorContext context) → Use EditAsync(TModel model, TSection section, BuildEditorContext context) where the Updater is available via context.
• DisplayAsync(TSection section, BuildDisplayContext context) → Use DisplayAsync(TModel model, TSection section, BuildDisplayContext context) where the Updater is available via context.

I also added PR #16814 to clarify the migration path.

[kevinasdzine]

And, just for clarity, if my controllers are just querying and returning content, I don't need an updater passed to BuildDisplayAsync, yes?

[MikeAlhayek]

You should pass an updater. One of your drivers may need it for some reason.

[kevinasdzine]

Ok, @Piedone says I shouldn’t need an updater and you’re saying I do need one. I’m confused.

[MikeAlhayek]

You should not need it. But you should pass it since the method asks for it. One of the drivers may wants it for some reason

[ns8482e]

We removed IDisplayResult Display(CalendarEventList model, IUpdateModel updater) because it didn't really make sense: if you want to use IUpdateModel to update the model, use an editor. Why do you need it?

I personally don't like these changes of removing IUpdateModel from Display methods and I also don't agree with the above reason. These methods were part of orchard framework.

I understand that orchard cms do not use IUpdateModel in CMS implementation for Display that doesn't necessarily mean that it's useless for the framework.

Consider scenario where you really want to build a display shape that is based on form input - Now with this change user is forced to build editor shape and anyone using these framework methods are forced to editor shape or to build display mode for the editor shape instead of display shape.

[MikeAlhayek]

The updater is available in the context. Nothing is stopping you from using it. We just removed it as a parameter to reduce the duplication and simplify things

[ns8482e]

I understand! But it forced user to make the changes! As the changes were related to the framework!

Also changes to the framework and public APIs should be controlled and intention to removal such APIs marked obsolete first. And should provide enough timeline for people to react to the changes- to avoid issue like

[MikeAlhayek]

We did as much as we could. The once's with the IUpdateModel were not possible to obsolete first.

We are trying to control the breaking changes as much as possible even in major releases.

[ns8482e]

My concern is not the change, but how the changes made.

Change in framework by removing these methods doesn't add any significant value but reduces user's confidence in OC Framework.

The methods removed from framework were just polymorphism and method overloading provided by framework, to allow consumers to use method they prefer to use.

If Orchard Core CMS like to follow specific pattern (i.e. not using methods deleted in question) in CMS's driver implementation then's it's CMS guidelines and does not summon to remove them in framework.

I now strongly feel that OC Framework should be separated in it's own repo to avoid this kind of changes in future

[MikeAlhayek]

The methods removed from framework were just polymorphism and method overloading provided by framework, to allow consumers to use method they prefer to use.

Providing extra unnecessary methods comes at little performance cost that can be avoided. Also, when you have simply API it helps new on comers to use OC without getting confused. Previously we had so many overloads that were just there which confused the users "which one do I use? Is there one better than others?..." in v2 "major version", we decided to simplify common used API's for simplicity and also to reclaim the performance benefit.

I understand your point. Ideally we would write flawless API that will forever stay. But the this is not always possible and which is why we sometimes are forced to release major version.