Skip to content

Commit ec1b81b

Browse files
dansiegeldansiegel
committed
docs: update Popup Plugin Docs
1 parent 2964cdc commit ec1b81b

File tree

1 file changed

+175
-10
lines changed

1 file changed

+175
-10
lines changed

‎docs/plugins/popups.md

+175-10
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,185 @@ uid: Plugins.Popups
44

55
# Getting Started
66

7-
The Prism.Plugin.Popups package for Xamarin.Forms has been hugely popular enabling developers to leverage the PopupPage's from Rg.Plugins.Popup. Following the introduction of the [IDialogService](xref:Dialogs.GettingStarted), the Popup Plugin was updated to migrate the use of Popup Page's as Dialogs and generally help developers avoid strong dependencies on libraries like Rg.Plugins.Popup as the DialogService could be implemented in other ways in the event that the community package were to fall out of maintenance.
7+
The `Prism.Plugin.Popups` package for Xamarin.Forms has been hugely popular, enabling developers to leverage `PopupPage` from the Rg.Plugins.Popup library. Following the introduction of the [IDialogService](xref:Dialogs.GettingStarted), the Popup Plugin was updated to transition `PopupPage` usage to dialogs. This change helps developers avoid strong dependencies on libraries like Rg.Plugins.Popup, as the `IDialogService` offers flexible implementation options should community packages become unmaintained.
88

9-
For .NET MAUI Developers, the Popup Plugin will no longer be publicly available on NuGet.org. It instead will only be provided to those with a Commercial Plus license. This is in large part due to the toxic nature of many developers using the plugin over the years who make demands for changes and updates but who never bother to contribute to any Open Source project, nor both to sponsor any Open Source Developers.
9+
For .NET MAUI developers, the Popup Plugin will no longer be publicly available on NuGet.org. Instead, it will be exclusively provided to those with a Commercial Plus license. This decision supports the project’s long-term sustainability, as maintaining and enhancing the plugin demands significant resources. Restricting access to licensed users allows us to allocate these resources effectively, ensuring continued development and improved support for our customers.
1010

11-
If updating your Xamarin.Forms app, particularly from older version of the Popup Plugin where you may have been using the `INavigationService` to Navigate to your Popup Pages, you will need to take time to re-architect some of your code to instead make use of the [IDialogService](xref:Dialogs.GettingStarted).
11+
If you’re updating your Xamarin.Forms app—especially from older versions of the Popup Plugin where `INavigationService` was used to navigate to `PopupPage` instances—you’ll need to re-architect portions of your code to utilize the [IDialogService](xref:Dialogs.GettingStarted) instead.
1212

13-
## Registering the Popup Plugin
13+
---
14+
15+
## Setup
16+
17+
To integrate `Prism.Plugin.Popups.Maui` into your .NET MAUI project, follow these steps:
18+
19+
1. **Install the NuGet Package**
20+
Add the `Prism.Plugin.Popups.Maui` package to your .NET MAUI project using NuGet Package Manager or by running:
21+
```
22+
dotnet add package Prism.Plugin.Popups.Maui
23+
```
24+
25+
2. **Register the Plugin**
26+
In your `MauiProgram.cs`, configure Prism to use the plugin by adding the following code:
27+
```csharp
28+
builder.UseMauiApp<App>()
29+
.UsePrism(prism => prism.ConfigureMopupDialogs());
30+
```
31+
32+
3. **Register Your Dialog Views**
33+
Dialogs must be registered with Prism’s dialog service (not navigated to like regular pages). For example:
34+
```csharp
35+
containerRegistry.RegisterDialog<MyDialog>();
36+
```
37+
This registers a dialog view named `MyDialog` with the Prism container.
38+
39+
---
40+
41+
## Creating a Dialog View
1442

15-
`Rg.Plugins.Popup` does not support .NET MAUI applications, however the project has been forked and is now called `Mopups`. To use the Popup Plugin, you must be a Commercial Plus subscriber and have added the private Prism NuGet feed. You can then install `Prism.Plugin.Popups.Maui`. Once you have installed the package you simply need to call `ConfigureMopupDialogs` on the PrismAppBuilder.
43+
A dialog view typically inherits from `ContentView` or a similar base class. You can use XAML to define the content and customize its behavior with attached properties from the `PopupDialogLayout` class.
1644

17-
```cs
18-
builder.UseMauiApp<App>()
19-
.UsePrism(prism => prism.ConfigureMopupDialogs())
45+
Here’s a basic template:
46+
```xaml
47+
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
48+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
49+
xmlns:prism="http://prismlibrary.com"
50+
x:Class="YourNamespace.YourDialog">
51+
<!-- Your popup content here -->
52+
</ContentView>
2053
```
2154

22-
> [!NOTE]
23-
> Using PopupPage's directly with Prism Navigation is no longer supported. PopupPage's are best used and make the most sense to be used as a Dialog. For this reason you should migrate your code to use the DialogService. Note that Prism.Plugin.Popups for .NET MAUI does expose a number of additional attached properties that you can use to configure the PopupPage that is created by the DialogService.
55+
---
56+
57+
## Attached Properties
58+
59+
The `PopupDialogLayout` class provides several attached properties to customize popup dialogs. Below is a list of these properties, their purposes, and examples:
60+
61+
### `HasSystemPadding`
62+
- **Type**: `bool`
63+
- **Default**: `true`
64+
- **Description**: Controls whether the popup respects system padding (e.g., status bar, navigation bar). Set to `false` for full-screen popups.
65+
- **Example**:
66+
```xaml
67+
prism:PopupDialogLayout.HasSystemPadding="False"
68+
```
69+
70+
### `SystemPadding`
71+
- **Type**: `Thickness`
72+
- **Default**: `0,0,0,0`
73+
- **Description**: Specifies custom padding around the popup, overriding system padding if needed.
74+
- **Example**:
75+
```xaml
76+
prism:PopupDialogLayout.SystemPadding="20,40,20,20"
77+
```
78+
79+
### `Animation`
80+
- **Type**: `IPopupAnimation`
81+
- **Default**: `ScaleAnimation`
82+
- **Description**: Defines the animation for popup appearance/disappearance. Use Mopups library animations (e.g., `MoveAnimation`) or custom ones.
83+
- **Example**:
84+
```xaml
85+
<prism:PopupDialogLayout.Animation>
86+
<animation:MoveAnimation PositionIn="Top" PositionOut="Bottom" />
87+
</prism:PopupDialogLayout.Animation>
88+
```
89+
90+
### `IsAnimationEnabled`
91+
- **Type**: `bool`
92+
- **Default**: `true`
93+
- **Description**: Enables/disables animations. Set to `false` for instant popup display.
94+
- **Example**:
95+
```xaml
96+
prism:PopupDialogLayout.IsAnimationEnabled="False"
97+
```
98+
99+
### `SystemPaddingSides`
100+
- **Type**: `PaddingSide`
101+
- **Default**: `PaddingSide.All`
102+
- **Description**: Specifies which sides receive system padding (e.g., `All`, `Top`, `Bottom`, `Left`, `Right`).
103+
- **Example**:
104+
```xaml
105+
prism:PopupDialogLayout.SystemPaddingSides="Top,Bottom"
106+
```
107+
108+
### `BackgroundInputTransparent`
109+
- **Type**: `bool`
110+
- **Default**: `false`
111+
- **Description**: If `true`, taps pass through to the background UI; if `false`, the background captures taps.
112+
- **Example**:
113+
```xaml
114+
prism:PopupDialogLayout.BackgroundInputTransparent="True"
115+
```
116+
117+
### `HasKeyboardOffset`
118+
- **Type**: `bool`
119+
- **Default**: `true`
120+
- **Description**: Adjusts the popup position when the keyboard appears. Set to `false` if no adjustment is needed.
121+
- **Example**:
122+
```xaml
123+
prism:PopupDialogLayout.HasKeyboardOffset="False"
124+
```
125+
126+
### `KeyboardOffset`
127+
- **Type**: `double`
128+
- **Default**: `0`
129+
- **Description**: Adds an extra offset (in pixels) when the keyboard appears.
130+
- **Example**:
131+
```xaml
132+
prism:PopupDialogLayout.KeyboardOffset="10"
133+
```
134+
135+
---
136+
137+
## Example Dialog View
138+
139+
Here’s a complete example combining several attached properties:
140+
```xaml
141+
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
142+
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
143+
xmlns:prism="http://prismlibrary.com"
144+
xmlns:animation="clr-namespace:Mopups.Animations;assembly=Mopups"
145+
prism:PopupDialogLayout.HasSystemPadding="False"
146+
prism:PopupDialogLayout.IsAnimationEnabled="True"
147+
x:Class="MauiApp2.MyDialog">
148+
<prism:PopupDialogLayout.Animation>
149+
<animation:MoveAnimation PositionIn="Top" PositionOut="Bottom" />
150+
</prism:PopupDialogLayout.Animation>
151+
<VerticalStackLayout>
152+
<Label Text="Welcome to .NET MAUI!"
153+
VerticalOptions="Center"
154+
HorizontalOptions="Center" />
155+
</VerticalStackLayout>
156+
</ContentView>
157+
```
158+
159+
In this example:
160+
- `HasSystemPadding="False"` makes the popup full-screen.
161+
- `IsAnimationEnabled="True"` activates animations.
162+
- `MoveAnimation` slides the popup from the top in and out to the bottom.
163+
164+
---
165+
166+
## Showing the Dialog
167+
168+
Use Prism’s `IDialogService` to display the dialog from a view model:
169+
```csharp
170+
public class MyViewModel
171+
{
172+
private readonly IDialogService _dialogService;
173+
174+
public MyViewModel(IDialogService dialogService)
175+
{
176+
_dialogService = dialogService;
177+
}
178+
179+
public async Task ShowDialogAsync()
180+
{
181+
await _dialogService.ShowDialogAsync("MyDialog");
182+
}
183+
}
184+
```
185+
- Inject `IDialogService` via constructor.
186+
- Call `ShowDialogAsync` with the registered dialog name.
187+
188+
---

0 commit comments

Comments
 (0)