In my previous post Styles in Xamarin Forms I demonstrated creating a simple styles using XAML Style objects. However, as of version 3.0 of Xamarin Forms, you can also use CSS (Cascading Style Sheet) files/syntax to define your styles.

XAML Style is quite a verbose way of defining styles but if you’re used to WPF or UWP it’s probably something you’re quite happy with. If, however, you come from a web background you’ll probably be used to CSS files instead. Now you can use similar syntax to define your styles for Xamarin Forms (3.0 or above).

If you create a standard mobile application in Visual Studio you’ll get a simple ContentPage based application – as per the previous post we’re going to start off by simply defining a Lime green background for our ContentPage’s.

Now simply add a CSS file (mine’s named Styles.css) to your solution and set it’s Build Action to Embedded resource and place the following into the file

^ContentPage {
     background-color: Lime;
}

Note: the CSS is case insensitive, but I’ve stuck to using the case associated with the controls/page here.

Notice the use of the ^ followed by the base type. If you read my previous post Styles in Xamarin Forms, you’ll notice that this is equivalent to an implicit style. i.e. it’s applied to anything of the type ContentPage.

To use this style we need to add the following to our ContentPage XAML

<ContentPage.Resources>
   <StyleSheet Source="Styles.css" />
</ContentPage.Resources>

Note: you do NOT need to add any namespace to use the StyleSheet (or at least I didn’t at the time of writing). if Visual Studio or Resharper suggests you need to add a namespace, just ignore it.

Now if you run your application you’ll be presented with the Lime background ContentPage.

If you’re used to CSS you’ll know that you can also declare an id (the equivalent of an explicit style) to your CSS. Let’s change our CSS to this following

#ContentStyle {
     background-color: Lime;
 }

Now we can assign this to either the StyleId or it will fallback to using x:Name (if no StyleId is set) on our control. For example

StyleId="ContentStyle"

or if you prefer you can simply use the x:Name (remember no StyleId should exist)

x:Name="ContentStyle"

We can also declare our CSS using CLASS selectors such as

.ContentStyle {
     background-color: Lime;
}

Now we would use the StyleClass attribute on our ContentPage instead of StyleId or x:Name, i.e.

StyleClass="ContentStyle"

Finally, we can also declare CSS for child elements, so for example CSS for the Label which is a child of a StackLayout would look like this

StackLayout Label {
    background-color: Lime;
}

See Selector reference for more on selector syntax, which also demonstrated setting style for direct child objects etc.

References

Styling Xamarin.Forms apps using Cascading Style Sheets (CSS)
Styling Xamarin.Forms Apps with CSS

Like WPF and UWP, Xamarin Forms supports the ability to “style” your application controls.

We can explicitly apply styles by creating a style with a key and explicitly assigning that style to a control. Alternatively we can implicitly apply styles be declaring the type (only) that the style applies to.

Let’s just do something very simple and make our ContentPage a rather bright Lime colour.

Explicit Style

After creating a mobile application within Visual Studio (which will default to using a ContentPage) simply add the following to the App.xaml, within the Application.Resources element.

<ResourceDictionary>
   <Style x:Key="ContentStyle" TargetType="ContentPage" >
      <Setter Property="BackgroundColor" Value="Lime" />
   </Style>
</ResourceDictionary>

In this example, we’ve declared the x:Key as ContentStyle. This is an explicit style in that, to use it, we need to set the Style property on the ContentPage that we want to apply this style to.

Open the MainPage.xaml (or any other ContentPage xaml files you have) and add the following as an attribute to the ContentPage

Style="{StaticResource ContentStyle}"

If you run the application you’ll be presented with a ContentPage with a bright Lime background colour.

If you’ve come from using WPF or UWP you’ll know you can also declare styles to the resource of your page’s so they’re scoped solely to that page. The App.xaml is globally scoped.

Implicit Style

Now, if all our ContentPage objects were to use this style, we might prefer to not have to assign the style each time. Instead we can change our App.xaml Style to look like this

<Style TargetType="ContentPage" ApplyToDerivedTypes="True">
   <Setter Property="BackgroundColor" Value="Lime" />
</Style>

Notice, we’ve removed the x:Key and added the ApplyToDerivedTypes. Now remove the Style attribute from your, previously created, ContentPage and run the application again and you’ll see the Style is automatically applied to all ContentPage objects.

Note: You can use TargetType=”{x:Type ContentPage}”, this more verbose way of declaring the TargetType is not required.

The ListView (as probably expected) allows us to display a list of data items, just like WPF/XAML we can alter the list item (or ViewCell) to display a custom view of our data, including images, buttons etc.

Bind to the ItemsSource property

For some unknown reason, I continually forget that the property used to bind our list of items to on a ListView is ItemsSource, not BindingContext, so just putting this note to myself Bind to the ItemsSource.

Okay back to the post…

Basic use of the ListView

In the case where we have a list of items, such as strings, then we can simply use

<ListView ItemsSource="{Binding Items}" />

assuming we have a view model which exposes an Items property which is a collection (i.e. ObservableCollection or the likes).

Displaying more complex items

As you’d probably expect, if you’re trying to display a non-primitive type, you can override the class ToString method to return a string representation of the data, for example if we’re trying to display for the type SlightlyLessBasicItemViewModel

public class SlightlyLessBasicItemViewModel
{
   public string Key { get; set; }
   public string Value { get; set; }

   public override string ToString()
   {
      return $"{Key} : {Value}";
   }
}

However, it’s also likely that we’ll want to formatting, images. buttons etc. into a list view item at which point we need to create our own item template.

If we assume we have a view model with an Items collection of SlightlyLessBasicItemViewModel we might like to display our row/cell with the key in bold and the value italic, for example we would use something like

<ListView ItemsSource="{Binding Items}">
   <ListView.ItemTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" VerticalOptions="Center">
               <Label Text="{Binding Key}" FontAttributes="Bold" />
               <Label Text="{Binding Value}" FontAttributes="Italic" />
             </StackLayout>
          </ViewCell>
       </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

Grouping

The ListView supports grouping, i.e. displaying something slightly different to indicate that the items belong to a group. Let’s create the following

public class GroupViewModel : 
   ObservableCollection<SlightlyLessBasicItemViewModel>
{
   public string GroupName { get; set; }
}

Now our main view model will return an Items collection of GroupViewModel types, each GroupViewModel will act as a separate header (and bind to the GroupName for the group heading) and the items will then be displayed beneath each grouping name in the ListView.

All we need to do to our XAML is add IsGroupingEnabled=”True” and then tell the List view to display the GroupName using GroupDisplayBinding=”{Binding GroupName}”. For completeness, here’s the full XAML for this

<ListView ItemsSource="{Binding Items}" 
      IsGroupingEnabled="True"
      GroupDisplayBinding="{Binding GroupName}">
   <ListView.ItemTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" VerticalOptions="Center">
               <Label Text="{Binding Key}" FontAttributes="Bold" />
               <Label Text="{Binding Value}" FontAttributes="Italic" />
            </StackLayout>
         </ViewCell>
      </DataTemplate>
   </ListView.ItemTemplate>
</ListView>

We can also add the GroupShortNameBinding binding to add to the jump list for jumping to specific parts of our list.

Ofcourse it’s also likely we’re want to override the cell that displays the group. To do this we override the GroupHeaderTemplate (we no longer need the GroupDisplayBinding if we’re taking over the displaying of it). So for example here’s out new group header template displayed in bright green

<ListView ItemsSource="{Binding Items}" 
      IsGroupingEnabled="True">
   <ListView.ItemTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" VerticalOptions="Center">
               <Label Text="{Binding Key}" FontAttributes="Bold" />
               <Label Text="{Binding Value}" FontAttributes="Italic" />
            </StackLayout>
         </ViewCell>
      </DataTemplate>
   </ListView.ItemTemplate>
   <ListView.GroupHeaderTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" VerticalOptions="Center">
               <Label Text="{Binding GroupName}" TextColor="Chartreuse"/>
            </StackLayout>
         </ViewCell>
      </DataTemplate>
   </ListView.GroupHeaderTemplate>
</ListView>

Headers and Footers

Along with groupings we can define headers (displayed as you’d expect at the top of the list view) and footers (yes, these are displayed at the end of the list view). Again, like groupings, we can create/use the default look and feel or override it, so here’s an example with the default look and feel (as our ListView XAML’s getting rather large I’ll show an abridge version to just show the changes here, source for this post will be available on my GitHub repos).

Note: I’m not going to change the view model (the GroupingViewModel) used in this example but instead hard code the header and footer, ofcourse you can data bind to these from your view model just as we’ve done for groups etc.

<ListView ItemsSource="{Binding Items}" 
   IsGroupingEnabled="True" 
   Header="---Header---"
   Footer="---Footer---">
</ListView>

Now let’s override our templates to customise the display of our header and footer. Remove the text only from the Header and Footer attributes. We’ll need the attributes still to tell the ListView to display a header and footer. Then we added our HeaderTemplate and FooterTemplate, for example

<ListView ItemsSource="{Binding Items}" 
   IsGroupingEnabled="True" 
   Header="" Footer="">
<!-- other content -->
   <ListView.GroupHeaderTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" VerticalOptions="Center">
               <Label Text="{Binding GroupName}" TextColor="Chartreuse"/>
            </StackLayout>
         </ViewCell>
      </DataTemplate>
   </ListView.GroupHeaderTemplate>
   <ListView.HeaderTemplate>
      <DataTemplate>
         <StackLayout Orientation="Horizontal">
            <Label Text="---" TextColor="Crimson" />
            <Label Text="Header" TextColor="DarkOrange"/>
            <Label Text="---" TextColor="Crimson" />
         </StackLayout>
      </DataTemplate>
   </ListView.HeaderTemplate>
   <ListView.FooterTemplate>
      <DataTemplate>
         <StackLayout Orientation="Horizontal">
            <Label Text="---" TextColor="Orange" />
            <Label Text="Footer" TextColor="Crimson"/>
            <Label Text="---" TextColor="Orange" />
         </StackLayout>
      </DataTemplate>
   </ListView.FooterTemplate>
</ListView>

Different (or uneven) row heights

In some situations we might want the ListView to display rows with different heights. By default all rows will have the same height, we simply need to set HasUnevenRows=”True” in the ListView and then, assuming our ItemTemplate expands to fit the data it’s given, we’ll get rows of differing sizes.

This example is slightly contrived to save creating another view model, so we’ll make the changes to the ItemTemplate to support larger labels and also to expand so when the label wraps the row expands. Here’s the changes to the ListView

<ListView ItemsSource="{Binding Items}" 
     IsGroupingEnabled="True" Header="" Footer="" 
     HasUnevenRows="True">
   <ListView.ItemTemplate>
      <DataTemplate>
         <ViewCell>
            <StackLayout Orientation="Horizontal" 
               VerticalOptions="StartAndExpand">
               <Label Text="{Binding Key}" FontAttributes="Bold" FontSize="24"/>
               <Label Text="{Binding Value}" FontAttributes="Italic" FontSize="24"/>
            </StackLayout>
         </ViewCell>
      </DataTemplate>
   </ListView.ItemTemplate>
<!-- other content -->
</ListView>

Pull to refresh

A paradigm used in mobile list views is the idea of pulling the list view to refresh it, for example maybe the list view displays a list of email messages, instead of automatically updating the list the user might see an indicator which says more messages are pending, then the user pulls the list to refresh/update the view.

To add such functionality we need to add the IsPullToRefreshEnabled=”True” to the ListView itself and then we’ll need our view model to supply a RefreshCommand and also a boolean property to tell the UI when the refresh has completed.

So let’s go back to a very basic list view and view model. Here’s my view model

public class PullToRefereshViewModel : ViewModel
{
   public PullToRefereshViewModel()
   {
      RefreshCommand = new ActionCommand(() =>
      {
         Items.Add(DateTime.Now.ToString());
         IsRefreshing = false;
      }); 
   }

   [CreateInstance]
   public ExtendedObservableCollection<string> Items
      => GetProperty<ExtendedObservableCollection<string>>();

   public ICommand RefreshCommand { get; }

   public bool IsRefreshing
   {
      get => GetProperty<bool>();
      set => SetProperty(value);
   }
}

Note: I’m using my Presentations.Core view model code which hopefully is fairly obvious.

Here’s the list view

<ListView ItemsSource="{Binding Items}" 
   IsPullToRefreshEnabled="True" 
   RefreshCommand="{Binding RefreshCommand}"
   IsRefreshing="{Binding IsRefreshing}"/>

When the user pulls the ListView down, it (assuming IsPullToRefreshEnabled is true and the supplied RefreshCommand CanExecute is true) will set IsRefreshing to true and display a activity/busy indicator. It will then call the ICommand assigned to RefreshCommand. However after the command completes the IsRefreshing will need to be set to false to hide the activity/busy indicator. It sort of feels like this should happen automatically when the command finishes, but seems it’s down to the view model to reset this flag.

Note: It’s important that the IsRefreshing is set to false or you’ll be stuck the busy indicator being displayed. Therefore, it’s probably best to put the code to reset IsRefreshing into a finally block if there’s chances of exceptions in the refresh command code.

Context Menu/Actions

We can add a context menu/action to the cell of a listview, for example a Delete option when the cell is tapped the option to delete the selected cell should appear.

We’ll extend the “Pull to Refresh” example by adding an ItemTemplate and changing the view model a little. Here’s the ItemTemplate

<ListView.ItemTemplate>
   <DataTemplate>
      <ViewCell>
         <ViewCell.ContextActions>
            <MenuItem Text="Delete" 
               Command="{Binding DeleteCommand}" 
               IsDestructive="True" />
          </ViewCell.ContextActions>
          <StackLayout>
             <Label Text="{Binding Value}" VerticalOptions="Center" />
          </StackLayout>
      </ViewCell>
   </DataTemplate>
</ListView.ItemTemplate>

Note: the use of IsDestructive=”True” has significance on iOS devices, only a single action can have this set to true.

In this example we need to move away from using a collection of strings for the ItemSource and have a class with a DeleteCommand on it, hence in the example above the cell label binds to a Value property on this new class. Here’s one possible way of implementing the view model for this along with the replacement for the PullToRefreshViewModel

public class ItemViewModel : ViewModel
{
   private readonly ContextMenuViewModel _parent;
   
   public ItemViewModel(ContextMenuViewModel parent, string value)
   {
      _parent = parent;
      Value = value;
      DeleteCommand = new ActionCommand<ItemViewModel>(s =>
      {
         _parent.Items.Remove(this);
      });
   }

   public ICommand DeleteCommand { get; }

   public string Value
   {
      get => GetProperty<string>();
      set => SetProperty(value);
   }

   public class ContextMenuViewModel : ViewModel
   {
      public ContextMenuViewModel()
      {
         RefreshCommand = new ActionCommand(() =>
         {
            Items.Add(new ItemViewModel(this, DateTime.Now.ToString()));
            IsRefreshing = false;
         });
      }

      [CreateInstance]
      public ExtendedObservableCollection<ItemViewModel> Items
         => GetProperty<ExtendedObservableCollection<ItemViewModel>>();

      public ICommand RefreshCommand { get; }

      public bool IsRefreshing
      {
         get => GetProperty<bool>();
         set => SetProperty(value);
      }
}

Note: there are several ways we might want this sort of code to work, this is just one example.

Code for the samples

Code for the samples listed, can be found at GitHub https://github.com/putridparrot/blog-projects/tree/master/ListViewExamples