Skip to content

Commit

Permalink
Merge pull request #19283 from unoplatform/dev/agzi/Backport19212To5-6
Browse files Browse the repository at this point in the history
docs(CTK8): Added converters usage sample (Backport #19212)
  • Loading branch information
agneszitte authored Jan 21, 2025
2 parents e1e9197 + 23d93e1 commit 59d155c
Showing 1 changed file with 101 additions and 2 deletions.
103 changes: 101 additions & 2 deletions doc/articles/uno-community-toolkit-v8.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,10 +151,10 @@ When using the Uno Platform solution templates, add the following to your applic

### WinUI / WinAppSDK / UWP

In XAML:
In XAML:
```xmlns:controls="using:CommunityToolkit.WinUI.Controls"```

In C#:
In C#:
```using CommunityToolkit.WinUI.Controls;```

## Example with the SettingsCard Control
Expand Down Expand Up @@ -184,6 +184,105 @@ You can set the `Header`, `HeaderIcon`, `Description`, and `Content` properties

A complete working sample, along with additional examples, is available on GitHub: [Uno Windows Community Toolkit SettingsCard Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample)

## Using Non-UI Elements from the CommunityToolkit: Converters

The CommunityToolkit provides a collection of ready-to-use converters for various scenarios (e.g., `x:Bind` in XAML). These converters streamline development by offering implementations for commonly used functionality, eliminating the need to manually create basic converters.
[List of CommunityToolkit Converters | Windows Toolkit Documentation](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/windows/converters/)

The implementation of these is similar to the example of the `SettingsControl` above, with some minor adjustments required to use them:

1. Install the NuGet package reference needed for the converters

### Single Project Template [WinUI / WinAppSDK]

1. Edit your project file `PROJECT_NAME.csproj` and add this additional needed reference:

```xml
<ItemGroup>
<PackageReference Include="CommunityToolkit.WinUI.Converters" />
<!-- Add more community toolkit references here -->
</ItemGroup>
```

1. Edit `Directory.Packages.props` and add this additional needed reference:

```xml
<ItemGroup>
<PackageVersion Include="CommunityToolkit.WinUI.Converters" Version="8.1.240916" />
<!-- Add more community toolkit references here -->
</ItemGroup>
```

1. Add the related needed namespace(s)

> [!NOTE]
> In WCT version 8.x, the namespaces between UWP and WinAppSDK were merged.

### WinUI / WinAppSDK / UWP

In XAML:
```xmlns:converters="using:CommunityToolkit.WinUI.Converters"```

In C#:
```using CommunityToolkit.WinUI.Converters;```

If you are developing an app using [C# Markup](xref:Uno.Extensions.Markup.Overview) and want to use the converters, you can refer to the [C# Markup Converters Documentation](xref:Uno.Extensions.Markup.Converters) for a detailed usage guide. The general import process is covered from this point onward.

1. XAML Definition

Unlike the previously seen `SettingsCard` control example, it is standard practice to define a converter in the `Page.Resources` section as a `StaticResource` before using it. This approach ensures that converters, like controls, are properly declared with a namespace and can be easily reused throughout the page.

### [Example: StringToVisibilityConverter](#tab/string-visible-conv)

The `StringToVisibilityConverter` is a converter that transforms a string value into a `Visibility` state, returning `Visibility.Visible` for non-empty strings and `Visibility.Collapsed` for null or empty strings.

#### Define the Converter in Page Resources

Add the converter to the `Page.Resources` section as a `StaticResource`:

```xml
<Page.Resources>
<converters:StringToVisibilityConverter x:Key="StringToVisibilityConverter" />
</Page.Resources>
```

#### Use the Converter in Page Content

Here is an example of how to use the converter in your XAML content:

```xml
<TextBlock Text="This text is visible only if the condition is met."
Visibility="{Binding SomeStringProperty, Converter={StaticResource StringToVisibilityConverter}}"/>
```

### [Example: BoolToObjectConverter](#tab/bool-obj-conv)

The `BoolToObjectConverter` allows you to convert a boolean value into a specific object by defining `TrueObject` and `FalseObject`. Depending on the boolean value, the converter will return the corresponding object.

#### Define the Converter in Page Resources

For example, you can use it to switch colors dynamically.
Add the converter to the `Page.Resources` section as a `StaticResource`:

```xml
<Page.Resources>
<converters:BoolToObjectConverter x:Key="BoolToColorConverter"
TrueObject="Green"
FalseObject="Red"/>
</Page.Resources>
```

#### Use the Converter in Page Content

Here is an example of how to use the converter in your XAML content:

```xml
<TextBlock Text="Status:"
Foreground="{Binding IsValid, Converter={StaticResource BoolToColorConverter}}"/>
```

In this example, the `TextBlock` background will be green when `IsValid` is `true` and red when `IsValid` is `false`.

---

[!include[getting-help](includes/getting-help.md)]

0 comments on commit 59d155c

Please sign in to comment.