Skip to content

987993 - WinUI Kanban API links updated for sorting #1204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: DOCINFRA-2341_merged_using_automation
merged 2 commits into from
Oct 17, 2025
Merged

987993 - WinUI Kanban API links updated for sorting #1204

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
015716e
WinUI Kanban API links updated for sorting
KerubananthanGanesan Oct 16, 2025
72ea0f6
987993-[WinUI Kanban] Sorting example code alignment changes
KerubananthanGanesan Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 117 additions & 53 deletions winui/Kanban/sorting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ documentation: ug

The Kanban control supports customizable card sorting within columns based on specific data fields such as `Priority`, `DueDate`, or `Status`. Sorting can be configured programmatically and updated dynamically at runtime using the following properties:

* `SortingMappingPath` - Used to map the sorting field to a property name in the `KanbanModel` or `CustomModel`. The default value is `string.Empty`, in which case the cards will not be sorted.
* `SortingOrder` - Used to define the direction of cards sorting within each column.
* `Ascending` - Cards with lower values appear first.
* `Descending` - Cards with higher values appear first.
* [SortingMappingPath](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingMappingPath) - Used to map the sorting field to a property name in the [KanbanModel](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.KanbanModel.html) or `CustomModel`. The default value is `string.Empty`, in which case the cards will not be sorted.
* [SortingOrder](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingOrder) - Used to define the direction of cards sorting within each column.
* [Ascending](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.KanbanSortingOrder.html#Syncfusion_UI_Xaml_Kanban_KanbanSortingOrder_Ascending) - Cards with lower values appear first.
* [Descending](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.KanbanSortingOrder.html#Syncfusion_UI_Xaml_Kanban_KanbanSortingOrder_Descending) - Cards with higher values appear first.

N> The `SortingOrder` property is applicable only when a valid value is assigned to `SortingMappingPath`.
N> The [SortingOrder](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingOrder) property is applicable only when a valid value is assigned to [SortingMappingPath](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingMappingPath).

## Customize card order with sorting configuration

Expand All @@ -27,12 +27,12 @@ Sorting in the Kanban control can be implemented using the following approaches.

### Custom Field Sorting

To enable custom sorting behavior, a valid property name from the `ItemsSource` must be mapped using the `SortingMappingPath` property. This mapping ensures that cards are loaded and repositioned based on the corresponding property value, allowing consistent sorting during both initialization and drag-and-drop operations.
To enable custom sorting behavior, a valid property name from the [ItemsSource](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_ItemsSource) must be mapped using the [SortingMappingPath](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingMappingPath) property. This mapping ensures that cards are loaded and repositioned based on the corresponding property value, allowing consistent sorting during both initialization and drag-and-drop operations.

This example demonstrates how card positions are updated based on sorting configurations and property mappings.

{% tabs %}
{% highlight XAML hl_lines="3 5" %}
{% highlight XAML hl_lines="2 3 5" %}

<kanban:SfKanban x:Name="kanban"
SortingMappingPath="Priority"
Expand All @@ -41,35 +41,68 @@ This example demonstrates how card positions are updated based on sorting config
ColumnMappingPath="Category">
<kanban:SfKanban.CardTemplate>
<DataTemplate>
<Border Background="#F3CFCE" BorderBrush="Black" BorderThickness="1" CornerRadius="8" Padding="8">
<Border Background="#F3CFCE"
BorderBrush="Black"
BorderThickness="1"
CornerRadius="8"
Padding="8">
<Grid ColumnSpacing="8">
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="Auto" />
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<StackPanel Grid.Row="0" Grid.ColumnSpan="2" Orientation="Horizontal"
Spacing="4" VerticalAlignment="Center" Height="20">
<TextBlock Text="•" FontSize="14" FontWeight="Bold" Foreground="Orange"
VerticalAlignment="Center" HorizontalAlignment="Center" />
<TextBlock Text="{Binding Priority}" FontSize="14" FontWeight="Bold" Foreground="Orange"
VerticalAlignment="Center" HorizontalAlignment="Left" Height="20" />
<StackPanel Grid.Row="0"
Grid.ColumnSpan="2"
Orientation="Horizontal"
Spacing="4"
VerticalAlignment="Center"
Height="20">
<TextBlock Text="•"
FontSize="14"
FontWeight="Bold"
Foreground="Orange"
VerticalAlignment="Center"
HorizontalAlignment="Center" />
<TextBlock Text="{Binding Priority}"
FontSize="14"
FontWeight="Bold"
Foreground="Orange"
VerticalAlignment="Center"
HorizontalAlignment="Left"
Height="20"/>
</StackPanel>
<TextBlock Grid.Row="1" Grid.ColumnSpan="2" Text="{Binding Title}" FontWeight="Bold"
FontSize="14" HorizontalAlignment="Center" VerticalAlignment="Center" Margin="5" />
<TextBlock Grid.Row="2" Grid.ColumnSpan="2" Text="{Binding Description}" FontSize="12"
TextWrapping="WrapWholeWords" HorizontalAlignment="Center" VerticalAlignment="Center" Margin="5" />
<TextBlock Grid.Row="1"
Grid.ColumnSpan="2"
Text="{Binding Title}"
FontWeight="Bold"
FontSize="14"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="5"/>
<TextBlock Grid.Row="2"
Grid.ColumnSpan="2"
Text="{Binding Description}"
FontSize="12"
TextWrapping="WrapWholeWords"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="5"/>
</Grid>
</Border>
</DataTemplate>
</kanban:SfKanban.CardTemplate>
<kanban:KanbanColumn HeaderText="Open" Categories="Open"/>
<kanban:KanbanColumn HeaderText="In Progress" Categories="In Progress"/>
<kanban:KanbanColumn HeaderText="Done" AllowDrag="False" Categories="Done"/>
<kanban:KanbanColumn HeaderText="Open"
Categories="Open"/>
<kanban:KanbanColumn HeaderText="In Progress"
Categories="In Progress"/>
<kanban:KanbanColumn HeaderText="Done"
Categories="Done"
AllowDrag="False"/>
<kanban:SfKanban.DataContext>
<local:SortingViewModel/>
</kanban:SfKanban.DataContext>
Expand Down Expand Up @@ -121,23 +154,23 @@ public class SortingViewModel
public ObservableCollection<CardDetails> Cards { get; set; }
}

N>
* To apply sorting after a drop operation, handle the `CardDrop` event and explicitly call the `RefreshKanbanColumn` method. This ensures the column updates to reflect the new card order based on the defined sorting logic.
* When using a custom data model, the default card UI is not applicable. To render the card content, you must define a custom `DataTemplate` using the `CardTemplate` property.

{% endhighlight %}
{% endtabs %}

N>
* To apply sorting after a drop operation, handle the [CardDrop](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_CardDrop) event and explicitly call the [RefreshKanbanColumn](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_RefreshKanbanColumn_System_String_) method. This ensures the column updates to reflect the new card order based on the defined sorting logic.
* When using a custom data model, the default card UI is not applicable. To render the card content, you must define a custom `DataTemplate` using the [CardTemplate](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_CardTemplate) property.

### Index-Based Sorting

The index-based approach in the Kanban control allows cards to be dropped at precise positions within a column. Upon dropping, the card's index is updated based on the index of the previous card. Additionally, the index of the next card is incremented relative to the drop position to maintain continuous ordering.

N> The `SortingMappingPath` property must be mapped to a valid numeric property name from the `ItemsSource` to enable index-based sorting updates.
N> The [SortingMappingPath](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingMappingPath) property must be mapped to a valid numeric property name from the [ItemsSource](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_ItemsSource) to enable index-based sorting updates.

The following code example illustrates how cards numeric property updated using the index-based sorting approach.

{% tabs %}
{% highlight XAML hl_lines="2 3" %}
{% highlight XAML hl_lines="2 3 5" %}

<kanban:SfKanban x:Name="kanban"
SortingMappingPath="Index"
Expand All @@ -146,35 +179,66 @@ The following code example illustrates how cards numeric property updated using
ColumnMappingPath="Category">
<kanban:SfKanban.CardTemplate>
<DataTemplate>
<Border Background="#F3EADC" BorderBrush="Black" BorderThickness="1" CornerRadius="8" Padding="8">
<Border Background="#F3EADC"
BorderBrush="Black"
BorderThickness="1"
CornerRadius="8"
Padding="8">
<Grid ColumnSpacing="8">
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="Auto" />
<ColumnDefinition Width="*" />
<ColumnDefinition Width="Auto"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<StackPanel Grid.Row="0" Grid.ColumnSpan="2" Orientation="Horizontal"
VerticalAlignment="Center" HorizontalAlignment="Right" >
<TextBlock Text="Rank #" FontSize="14" FontWeight="Bold" Foreground="#026B6E"
VerticalAlignment="Center" HorizontalAlignment="Center" />
<TextBlock Text="{Binding Index}" FontSize="14" FontWeight="Bold" Foreground="#026B6E"
VerticalAlignment="Center" HorizontalAlignment="Center" />
<StackPanel Grid.Row="0"
Grid.ColumnSpan="2"
Orientation="Horizontal"
VerticalAlignment="Center"
HorizontalAlignment="Right">
<TextBlock Text="Rank #"
FontSize="14"
FontWeight="Bold"
Foreground="#026B6E"
VerticalAlignment="Center"
HorizontalAlignment="Center"/>
<TextBlock Text="{Binding Index}"
FontSize="14"
FontWeight="Bold"
Foreground="#026B6E"
VerticalAlignment="Center"
HorizontalAlignment="Center"/>
</StackPanel>
<TextBlock Grid.Row="1" Grid.ColumnSpan="2" Text="{Binding Title}" FontWeight="Bold"
FontSize="14" HorizontalAlignment="Center" VerticalAlignment="Center" Margin="5" />
<TextBlock Grid.Row="2" Grid.ColumnSpan="2" Text="{Binding Description}" FontSize="12"
TextWrapping="WrapWholeWords" HorizontalAlignment="Center" VerticalAlignment="Center" Margin="5" />
<TextBlock Grid.Row="1"
Grid.ColumnSpan="2"
Text="{Binding Title}"
FontWeight="Bold"
FontSize="14"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="5"/>
<TextBlock Grid.Row="2"
Grid.ColumnSpan="2"
Text="{Binding Description}"
FontSize="12"
TextWrapping="WrapWholeWords"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Margin="5"/>
</Grid>
</Border>
</DataTemplate>
</kanban:SfKanban.CardTemplate>
<kanban:KanbanColumn HeaderText="Open" Categories="Open"/>
<kanban:KanbanColumn HeaderText="In Progress" Categories="In Progress"/>
<kanban:KanbanColumn HeaderText="Done" AllowDrag="False" Categories="Done"/>
<kanban:KanbanColumn HeaderText="Open"
Categories="Open"/>
<kanban:KanbanColumn HeaderText="In Progress"
Categories="In Progress"/>
<kanban:KanbanColumn HeaderText="Done"
Categories="Done"
AllowDrag="False"/>
<kanban:SfKanban.DataContext>
<local:SortingViewModel/>
</kanban:SfKanban.DataContext>
Expand Down Expand Up @@ -231,5 +295,5 @@ public class SortingViewModel
{% endtabs %}

N>
* The Index-based sorting can be achieved at the sample level after a drag-and-drop action. To implement this handle the `CardDrop` event, access the items in the target column using `e.TargetColumn.Items`, and update the numeric field used for sorting to maintain a continuous order. Finally, call `RefreshKanbanColumn` method to update the UI with the new order.
* To disable sorting logic, avoid assigning a value to the `SortingMappingPath` property. This ensures that card positions remain static and reflect the order of the `ItemsSource` collection, making it suitable for scenarios where sorting is not required or is managed externally.
* The Index-based sorting can be achieved at the sample level after a drag-and-drop action. To implement this handle the [CardDrop](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_CardDrop) event, access the items in the target column using `e.TargetColumn.Items`, and update the numeric field used for sorting to maintain a continuous order. Finally, call [RefreshKanbanColumn](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_RefreshKanbanColumn_System_String_) method to update the UI with the new order.
* To disable sorting logic, avoid assigning a value to the [SortingMappingPath](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_SortingMappingPath) property. This ensures that card positions remain static and reflect the order of the [ItemsSource](https://help.syncfusion.com/cr/winui/Syncfusion.UI.Xaml.Kanban.SfKanban.html#Syncfusion_UI_Xaml_Kanban_SfKanban_ItemsSource) collection, making it suitable for scenarios where sorting is not required or is managed externally.