Update the `migrate custom renderer page` with better more current examples
- Dominant language
- No language data
- Stars
- 282
- Forks
- 265
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 19
Description
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
```C#
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
```C#
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](https://github.com/dotnet/maui/discussions/categories/upgrading-from-xamarin)
#### 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](https://github.com/dotnet/maui/discussions/categories/upgrading-from-xamarin)
### 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](https://learn.microsoft.com/en-us/dotnet/maui/migration/renderer-to-handler?view=net-maui-7.0)
* Content Source: [docs/migration/renderer-to-handler.md](https://github.com/dotnet/docs-maui/blob/main/docs/migration/renderer-to-handler.md)
* Product: **dotnet-mobile**
* Technology: **dotnet-maui**
* GitHub Login: @davidbritch
* Microsoft Alias: **dabritch**
Contributor guide
Assessment
This issue has not been assessed yet.