Popup V2 - Move PopupOptions Settings Into XAML

[david-maw]

The PopupOptions mechanism moves a certain amount of popup formatting into the caller's code rather than the XAML (or C#) for the popup itself as it formerly was.

Moving the control of formatting into XAML would make UI design easier because XAML updates can be visualized fairly easily. Making the properties bindable makes it more flexible and XAML makes some things (like styling and responding to Themes for example) a lot easier. It would also centralize control of the popup appearance and behavior in the popup itself, which seems less error prone than splitting it between the caller and the popup.

This suggestion is that the setting in PopupOptions be turned into bindable properties of the Popup class. Some (CanBeDismissedByTappingOutsideOfPopup, PageOverlayColor and Shadow) could be simple bindable properties and Shape would need to be split into the set of properties Border uses to define the outline (StrokeShape, StrokeThickness etc.). Options provided in a ShowPopupAsync call would override values provided in XAML.

You could use attached properties for this, but that seems fraught with complexity for no great gain over simple bindable properties on Popup.

[bijington]

The suggestion of using attached properties was based around the concept that you do not need to subclass from Popup in order to display something in a Popup - it can be a simple ContentView, etc. If you want to define those properties in this XAML then it would need to be an attached property

[david-maw]

I'd guessed that was probably it, but I suspect in practice XAML will often be used in all but trivial examples and the ease of being able to write something like:

<toolkit:Popup
    x:Class="PopupPage.AppSnackBarPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:local="clr-namespace:PopupPage"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
    xmlns:views="clr-namespace:PopupPage"
    x:DataType="views:AppSnackBarPage"
    CanBeDismissedByTappingOutsideOfPopup = "True"
    StrokeShape = "RoundRectangle 10"
    BackgroundColor="{AppThemeBinding Light={StaticResource LightRed},
                                      Dark={StaticResource DarkRed}}"
    BindingContext="{Binding Source={RelativeSource Self}}"
    HorizontalOptions="Fill"
    VerticalOptions="End">
    <Label
        HorizontalOptions="Center"
        Text="{Binding Text}"
        TextColor="{AppThemeBinding Light={StaticResource Gray900},
                                    Dark={StaticResource White}}" />
</toolkit:Popup>

Struck me as very convenient, especially when fiddling with it during design because it would be able to take advantage of XAML hot reload.

I may have misunderstood attached properties, but offhand I had no idea what to make of the case where the Label is replaced by, say:

    <VerticalStackLayout>
        <Label Text="Line 1" toolkit:Popup:CanBeDismissedByTappingOutsideOfPopup = "True" />
        <Label Text="Line 2" toolkit:Popup:CanBeDismissedByTappingOutsideOfPopup = "False" />
    </VerticalStackLayout>

Which assignment to toolkit:Popup:CanBeDismissedByTappingOutsideOfPopup would take effect? Hence my preference for a simple property rather than an attached one.

[bijington]

Yes sadly that is a drawback of using attached properties. In your scenario neither would apply because I would expect them only to be set on the top level element

[david-maw]

Oh, and i meant to ask, is there a guide for migrating from the old to new popup anywhere?

[bijington]

There is this guide https://github.com/CommunityToolkit/Maui/wiki/Migrating-to-Popup-v2. Please let me know if you feel it needs more detail

[david-maw]

I agree that's what a user should do with these attached properties, alas you have to code for the case where they do it wrong. In practice I suspect the vast majority of cases will simply define a popup in XAML so as to have access to CloseAsync if nothing else (and always to return a value), so the advantage of being able to apply the properties to any view is minimal On the other hand the cost is just a bit more typing and marginally harder migration for CanBeDismissedByTappingOutsideOfPopup .

The guide seems very thorough, I wish I'd read it before attempting my conversion, so my first comment is that it would be helpful to make its existence more obvious (though there may be some terribly obvious place I missed), perhaps add a pointer to it alongside the other Popup documents.

It may be worth mentioning that Margin and Padding have non-zero default values.

I'm not sure if it is useful, but because I prefer to have my UI in XAML I've settled on setting Shape to null in the call (but not Shadow) and putting

    BackgroundColor="Transparent"
    Margin="0"
    Padding="0"

In the Popup XAML. That allows me to put my own border in XAML where it's more readily controllable and design time experiments are easier.

In the Removed The need to Subclass Popup section one might also want to use the Open or Close events, or call CloseAsync, any one of which would require Popup.

I didn't understand the comment under the PopupOptions header that said, Note that each of the following properties are BindableProperty definitions.... Bindable properties on PopupOptions or some other class, are they attached properties? Perhaps an example of using them would clarify this.

As is often the case in this sort of dialogue, it's easy to lose sight of the fact that this is a terribly useful implementation which, overall, works very well. While I might quibble with the details, the big picture is an excellent one, my thanks to all who participated in making it happen.

[bijington]

Thank you for the really helpful feedback! I'll aim to include it into our documentation to help the next person!

And thanks for the discussion around this! It's been extremely constructive which is extremely welcome

[david-maw]

You're welcome. For my own edification can you explain the comment under the PopupOptions header that said, Note that each of the following properties are BindableProperty definitions.... I really don't understand whether they are bindable properties on PopupOptions or some other class, and how I'd use them in XAML (which is presumably why you'd make them bindable).

[bijington]

Let me try to explain it via a hopefully simple example - you have a Page and during the lifetime of that page you wish to show a Popup. While this popup is displayed there may be a time you do not wish to the let the user tap outside of the bounds to dismiss and then at other times you may - let's say you are showing an overlay or progress and the user cannot cancel out of it, once the progress has completed then the user is free to tap outside of the popup to continue. This behaviour could be entirely controlled through the Page that displayed the popup and the PopupOptions that is passed to the call to display the popup. The internal code within the toolkit will bind to the CanDismissByTappingOutsideOfPopup property from the options to the internal wrapper around your popup. Therefore if you can the value of CanDismissByTappingOutsideOfPopup in your Page it will be reflected in the popup and the possible interactions the user can perform.

Does that help?

[david-maw]

Thanks, got it I think, if I keep a reference to the PopupOptions I used I can alter them and see the change reflected in the open popup. I'd assumed the PopupOptions passed as a parameter just provided initial values, partly because I saw a note somewhere that one set of PopupOptions could be shared between calls. Proves what they say about "assume", I guess.

[bijington]

Yes that's correct. So both statements are true, you could pass around the same set of options but given the former statement about changing values that may not be a sensible idea :)

[imsam67]

This discussion is very helpful. Thank you both @david-maw @bijington