Items Collection

Display a highly performant list of views powered by JSON data and an item template.

Inherits from Sharpnado.CollectionView

About

At some point in your mobile development career... there will come a point in which you need to display a list of items, either horizontally or vertically. These items will all look the same and be powered from a singular data source (likely a Lava entity command).

Like most, your first attempt will likely look something like this:

<ScrollView> <!-- Usually in the layout, but I moved here for demo -->
    <StackLayout>
        {% for item in items %}
            <StackLayout>
                <Label Text="{{ item.Name }}" />
                <Label Text="{{ item | Attribute:'FavoriteColor' }}" />
            </StackLayout>
        {% endfor %}
    </StackLayout>
</ScrollView>

And who knows, maybe that is enough to get the job done and call it a day... Or maybe it isn't.

You may realize pretty quickly that with a lot of items, the performance starts to deteriorate. Most layouts simply aren't built to handle that many items generated in the form of raw XAML. If you've been in the game a while, you may have experimented with CollectionView or CarouselView, which are performant alternatives. The ItemsCollection (this) control is a friendlier, viable and stable alternative to both of those controls.

This control requires an item height (or width). This plays a big factor with performance. If you need a list with differently sized items, take a look at one of the alternatives listed above.

Properties

Collection View Layout

Usage

Let's get into the business... how can we display long lists (horizontally OR vertically) without killing performance and maintaining a smooth scroll experience? The answer can be achieved with four simple steps.

  1. Define your data source as JSON

  2. Bring your JSON into memory

  3. Create a single item template

  4. Set up your Items Collection container

Examples

Make sure to use Rock:ViewCell as the base of your template. This control has some special logic to make sure the views are properly dark mode responsive.

//- Load our JSON data from an entity command.
{%- capture people -%}
  [
    {%- person where:'LastName == "Decker"' -%}
    {
      "name": "{{ person.FirstName }} {{ person.LastName }}",
      "campus": "{{ person.Campus }}",
    }{%- unless forloop.last -%},{%- endunless -%}
    {%- endperson -%}
  ]
{%- endcapture -%}

<Grid>
    <Grid.Resources>
        //- Bring the JSON into memory.
        <Rock:FromJson x:Key="People">{{ people }}</Rock:FromJson>
        
        //- Define the item template for the list.
        <DataTemplate x:Key="PersonItem">
            <Rock:ItemViewCell>
                <Border StrokeShape="RoundRectangle 12"
                        StyleClass="px-16">
                    <Label Text="{Binding name}"
                           StyleClass="title2, text-interface-stronger"
                           VerticalTextAlignment="Center" />
                </Border>    
            </Rock:ItemViewCell>
        </DataTemplate>
    </Grid.Resources>

    //- List the items, with the in memory items.
    <Rock:ItemsCollection ItemHeight="75"
                          ItemSpacing="8"
                          CollectionPadding="16"
                          ItemsSource="{StaticResource People}"
                          ItemTemplate="{StaticResource PersonItem}">
    </Rock:ItemsCollection>
</Grid>

Last updated

⚙️ Powered by Rock RMS