VerticalStackList

[velocitysystems]

Summary

This control extends VerticalStackLayout + BindableLayout and provides support for item separators normally only available in a ListView. The control also dynamically allows data to be added/removed using the INotifyCollectionChanged events on an ObservableCollection<T>.

This allows for placement of this list within a parent ScrollView which is normally an 'anti-pattern' for a ListView or CollectionView. However this is a common design element in many UX designs i.e. inline lists.

Design

public class VerticalStackList : VerticalStackLayout
{
  public static readonly BindableProperty ItemsSourceProperty;
  public static readonly BindableProperty ItemTemplateProperty;
  public static readonly BindableProperty SeparatorColorProperty;
}

Usage

<VerticalStackList ItemsSource="{Binding ObservableItemsSource}" SeparatorColor="Gray">
  <VerticalStackList.ItemTemplate>
    <DataTemplate x:DataType="models:FooType">
      <Label Text="{Binding Foo}" />
    </DataTemplate>
  </VerticalStackList.ItemTemplate>
</VerticalStackList>

Output
For strings: "Foo", "Bar" result would be:

"Foo"
--- Separator ---
"Bar"

Note: I already have a fully-built version of this control. I wanted to submit this as a feature proposal since I think it would make a worthy addition to the toolkit.

[bijington]

Firstly thank you for the proposal, I like the idea of simplifying the code that developers have to write in order to achieve their goals and this looks to help there.

I have a couple of questions:

1. I understand that ListView/CollectionView is notoriously buggy but they do offer things like virtualisation to perform well when there is a large number of items in the list. Do you have any idea of performance for this approach? Would there be a recommended maximum number of items/ItemTemplate complexity before we would have to recommend developers not use this?
2. In your implementation do you have anything specific to the VerticalStackLayout control or could this be applied to other layout controls?
3. A slight extension to the above question, could there be a way of extending the BindableLayout class to also allow providing the separator design? Perhaps even a SeparatorTemplate to make it further customisable?

[velocitysystems]

Thanks @bijington. In answer to your questions:

1. This control is not intended to be a replacement for ListView or CollectionView. Specifically it is intended for when neither of these controls are suitable for use-case i.e. one or more inline lists which are displayed inside a parent element. The parent element itself may then be wrapped in a ScrollView. It goes against design guidelines to embed a virtualized, scrollable collection as an inline element and give it a fixed height so it doesn't scroll internally - this is the intended application. Of course since the collection is not virtualized, it would not be recommended for complex item templates or very large collections.
2. No - there is nothing specific to the VerticalStackLayout. In fact this could be used with a HorizontalStackLayout or another other layout which support use of BindableLayout.
3. I had considered this but feel this may be a 'long-shot' gaining acceptance by the MAUI team. Of course this would eliminate the need for this control and would be a great addition for the future, but I wasn't counting on this being possible at this time. Plus, I needed an immediate solution.

[stephenquan]

At the core, your issue is really about customizable separators. In the case of custom vertical separators this can be done now by including the separators with your DataTemplate with an appropriate IsVisible trigger:

<VerticalStackLayout>
    <BindableLayout.ItemsSource>
        <x:Array Type="{x:Type x:String}">
            <x:String>Item 1</x:String>
            <x:String>Item 2</x:String>
            <x:String>Item 3</x:String>
        </x:Array>
    </BindableLayout.ItemsSource>
    <BindableLayout.ItemTemplate>
        <DataTemplate x:DataType="x:String">
            <VerticalStackLayout>
                <BoxView x:Name="separator" HeightRequest="2" Color="Grey">
                    <BoxView.Triggers>
                        <DataTrigger Binding="{Binding .}" TargetType="BoxView" Value="Item 1">
                            <Setter Property="IsVisible" Value="False" />
                        </DataTrigger>
                    </BoxView.Triggers>
                </BoxView>
                <Label Text="{Binding .}" />
            </VerticalStackLayout>
        </DataTemplate>
    </BindableLayout.ItemTemplate>
</VerticalStackLayout>

Note: The code snippet above uses hard-coded lists and constants to contribute to the discussion in a succinct manner. It has obvious flaws, particularly a lack of generalization.

[velocitysystems]

Thanks @stephenquan. I'm aware of this as an option however the goal is to provide a control which handles this 'out-of-the-box' so the separator does not need to be included in the DataTemplate. This shifts responsibility for the separator to the layout and not the consumer of the control.

[velocitysystems]

Perhaps a better name for this would be InlineListLayout which better fits the purpose and objective.

[velocitysystems]

The separator could also be provided to the control as a separate bindable property i.e. SeparatorTemplate.

[pictos]

I would say this is so easy to implement in a project, as shown by @stephenquan, that we shouldn't implement it here. Adding features to this lib will add overhead on maintainers, because it's one more feature, API to support and care about, I recommend this article to take a sense of what I'm saying

[velocitysystems]

@pictos I respectfully disagree. The proposed solution by @stephenquan requires that item models have a property to control the visibility of the separator. The proposed design shifts this responsibility to the layout itself in the same way the ListView control works in MAUI/Xamarin.Forms.

If I have an app with 30+ inline lists I don't want to have to implement logic and boilerplate just for controlling separator visibility.

[pictos]

My point is not about the solution provided by @stephenquan, but how trivial is to add a separator in that context. And there are others way to implement that without polluting the model.

I would say that your solution is very niche, you create a control to abstract the separator, since the actual BindableLayout.ItemsSource already has support for INCC. And you extend it from VerticalStackLayout, what if I want to implement another layout or orientation?

For me, what Maui already offers is enough for devs to do it.

And don't get me wrong, I see value on implementing a control that will abstract that part and make the implementors life easier, but I can't see this solution fitting in this toolkit.

[velocitysystems]

That makes sense - which is why it may be best to advocate for SeparatorTemplate to be added to BindableLayout.
See my comments below.

[velocitysystems]

I agree with @bijington that ideally this should be baked into BindableLayout in MAUI.
Maybe that's the conclusion here? If BindableLayout had a SeperatorTemplate property then this whole proposal is moot.

[stephenquan]

@velocitysystems the DataTrigger intended to demonstrate that we can turn off the separator for the first item in the list. Certainly, there are better ways to achieve this, for instance I have an upcoming enhancement to the MultiMathExpressionConverter which could be used instead of the DataTrigger.

As to whether the code belongs in the DataTemplate or not. Ultimately, it has to, because you need to make a decision on how each item in your list is being rendered, i.e. vertical vs horizontal vs bottom-up vs right-to-left. Also, you need to generalize between BindableLayout, ListView, CollectionView, ... To date, we have been making linear 1-D representation assumptions. What if a 2-D grid layout with horizontal and vertical separators is required? These factors would go beyond adding a mere SeparatorTemplate property.

Presently, the CommunityToolkit does have a DockLayout https://learn.microsoft.com/en-us/dotnet/communitytoolkit/maui/layouts/docklayout which would be the closest thing to a customizable/generalizable separator view (i.e. either an application of the DockLayout or the creation of a new component whose design is a derivative of DockLayout).

The DockLayout together with the upcoming MultiMathExpressionConverter PR will look like this:

<VerticalStackLayout BindableLayout.ItemsSource="{Binding MyItems, Source={Reference vm}}">
    <BindableLayout.ItemTemplate>
        <DataTemplate x:DataType="x:String">
            <toolkit:DockLayout>
                <BoxView
                    toolkit:DockLayout.DockPosition="Top"
                    HeightRequest="2"
                    Color="Grey"
                    IsVisible="{MultiBinding {Binding .},
                                             {Binding MyItems[0], Source={Reference vm}},
                                             Converter={StaticResource MultiMathExpressionConverter},
                                             ConverterParameter='x0 != x1'}"/>
                <Label Text="{Binding .}" />
            </toolkit:DockLayout>
        </DataTemplate>
    </BindableLayout.ItemTemplate>
</VerticalStackLayout>

Alternatively, you could consider using DataTemplateSelector https://learn.microsoft.com/en-us/dotnet/api/microsoft.maui.controls.datatemplateselector?view=net-maui-8.0 where one DataTemplate is used only for the first item in the list and the remaining items will use a default DataTemplate.

Here's another solution involving ContentView. We provide two ControlTemplates. One ControlTemplate without the separator (for the first item), the other ControlTemplate with the separator for all other items. By using ContentPresenter, the user can supply their own visual element for rendering their item:

<VerticalStackLayout BindableLayout.ItemsSource="{Binding MyItems, Source={Reference vm}}">
    <VerticalStackLayout.Resources>
        <ResourceDictionary>
            <ControlTemplate x:Key="first">
                <ContentPresenter />
            </ControlTemplate>
            <ControlTemplate x:Key="default">
                <toolkit:DockLayout>
                    <BoxView toolkit:DockLayout.DockPosition="Top" HeightRequest="2" Color="Grey" />
                    <ContentPresenter />
                </toolkit:DockLayout>
            </ControlTemplate>
        </ResourceDictionary>
    </VerticalStackLayout.Resources>
    <BindableLayout.ItemTemplate>
        <DataTemplate>
            <ContentView ControlTemplate="{StaticResource first}">
                <ContentView.Triggers>
                    <DataTrigger
                        Binding="{MultiBinding {Binding},
                                               {Binding MyItems[0], Source={Reference vm}},
                                               Converter={StaticResource MultiMathExpressionConverter},
                                               ConverterParameter='x0 != x1'}"/>
                        TargetType="ContentView"
                        Value="True">
                        <Setter Property="ControlTemplate" Value="{StaticResource default}" />
                    </DataTrigger>
                </ContentView.Triggers>
                <Label Text="{Binding .}" />
            </ContentView>
        </DataTemplate>
    </BindableLayout.ItemTemplate>
</VerticalStackLayout>

[velocitysystems]

Created feature request to add SeparatorTemplate to BindableLayout in MAUI.