Update the `migrate custom renderer page` with better more current examples

[PureWeen]

I feel like this doc is a bit confusing and doesn't quite guide users to what they are looking for. If we want to show migration, then I think we need to have the renderer equivalent on that doc to show a start point and end point.  This doc just feels like a TLDR of a doc explaining what a handler is but not about how to migrate a renderer to a handler.

I think a doc about migrating a custom renderer should have a couple sections covering the paths.

Sections

Easy path of just converting a basic Renderer to Mappers

Here's an example of a renderer someone created inheriting from EntryRenderer in order to set a few properties

MyCustomEntryRenderer : EntryRenderer
...
override OnPropertyChanged
{
    if (propertyName == "TextColor")
}

Then show how that code can easily be shifted to a handler using a mapper. Drawing the comparison between the replacement parts

EntryHandler.Mapper.(Modify/Append/Prefix)("TextColor")

• If that doesn't work try using a shim, and please log a bug
• If that doesn't work, please log a bug
• Are you still confused? Create a discussion here

Areas that match between renderers/handlers

• Mappers -> override OnElementPropertyChanged
• returning your own platform view -> Handler.CreatePlatformViewFactory
• This is also relevant if users are overriding a platform method. For example, in the code if they are overriding UIView.WillMoveToWindow the way to do that in the handler architecture is to use PlatformViewFactory to supply an inherityed view and override it there. (Except for UIButton which is special)
• Dispose -> subscribe to Loaded/Unloaded or watch for the WindowChanged property on the VirtualView (this is a little bit messy right now but we can provide some samples). Disconnect/ConnectHandler won't behave like they expect them to currently if they are wanting a replacement for dispose.
  • We can also use some samples here showing how to inherit from the platform control.

Larger path if user is inheriting from VisualElementRenderer

• If your VER is too complicated currently to just convert to a handler based on (link to docs talking about handlers and comparing to renderers) then we have these options for you
• try using our handler based VisualElementRenderer that's based on a handler
  • here we should make sure to clarify the use of "AddHandler" vs "AddCompatibiltiyRenderer"
• If that doesn't work try using a shim and please log a bug
• If that doesn't work, please log a bug
• Are you still confused? Create a discussion here

Samples

As we add scenarios/samples to this doc we should also accompany them with samples in our maui-samples repository.

• How do I access the NavigationBar on iOS?
• How do I replace the ViewController of a Page?

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 125882c9-c32b-e41d-c39d-6b63b7799499
• Version Independent ID: 125882c9-c32b-e41d-c39d-6b63b7799499
• Content: Migrate a custom renderer to a .NET MAUI handler - .NET MAUI
• Content Source: docs/migration/renderer-to-handler.md
• Product: dotnet-mobile
• Technology: dotnet-maui
• GitHub Login: @davidbritch
• Microsoft Alias: dabritch

[Sweekriti91]

Sample for How do I replace the ViewController of a Page? : https://github.com/TomSoderling/MigratedPageRendererExample

I'll keep updating with other custom renderer samples as I finish them!

@davidbritch do you want a detailed Readme with the sample? I can update that let me know!

[davidbritch]

@Sweekriti91 It needs a readme similar to the other readme's in the maui-samples repo, so that it gets ingested into the samples browser.