The goal of this book is to focus on how to apply best practices and patterns to mobile apps built with Xamarin.Forms, and not on the actual Xamarin.Forms toolkit and API itself. The best way to achieve this goal is to build an app end to end, applying new concepts in each chapter.
Therefore, the goal of this chapter is to simply put together the basic structure of a Xamarin.Forms mobile app code base, which will serve as a foundation that we can build from throughout the rest of this book.
In this chapter, we will do the following:
In the next chapter we'll introduce the Model-View-ViewModel (MVVM) pattern and add data bindings to the user interface we create in this chapter. From there we will build upon the app and its architecture, introducing best practices and patterns for things like platform-specific API dependencies, dependency injection, remote data access, authentication, and unit testing. But, just like the beginning of many new mobile projects, we will start with an idea.
We will create a travel app named TripLog and, as the name suggests, it will be an app that will allow its users to log their travel adventures. Although the app itself will not solve any real-world problems, it will have features that will require us to solve real-world architecture and coding problems. The app will take advantage of several core concepts, such as list views, maps, location services, and live data from a RESTful API, and we will apply patterns and best practices throughout this book to implement these concepts.
Before we get started, it is important to understand the requirements and features of the TripLog app. We will do this by quickly defining some of the high-level things this app will allow its users to do:
The following screenshots show some of the iOS and Android screens of the app we will be creating. The first screenshot shows the initial screen running on iOS with the list of all the user's trip log entries. The middle screenshot shows the trip log detail screen using native maps. The last screenshot shows the screen that lets users add new trip log entries running on Android:
Figure 1: The TripLog app as it will appear at the end of the book
To start off the new TripLog mobile app project, we will need to create the initial solution architecture. We can also create the core shell of our app's user interface by creating the initial screens based on the basic features we have just defined.
We will start things off by creating a brand new, blank Xamarin.Forms solution within Visual Studio by performing the following steps:
Figure 2: Xamarin.Forms new project setup in Visual Studio (step 1 of 3)
TripLog
, and ensure that Use .NET Standard is selected for the Shared Code option, as shown in the following screenshot:You can use either .NET Standard or a Shared Library for the code sharing option when creating a new Xamarin.Forms project. There are benefits to both but we will use .NET Standard, as it lends itself better to the architecture patterns and testability objectives of this book.
Figure 3: Xamarin.Forms new project setup in Visual Studio (step 2 of 3)
Figure 4: Xamarin.Forms new project setup in Visual Studio (step 3 of 3)
Figure 5: The TripLog solution in Visual Studio
There will be a single .NET Standard project and two platform-specific projects, as follows:
If you are using Visual Studio for Mac, you will only get an iOS and an Android project when you create a new Xamarin.Forms solution. To include a Windows (UWP) app in your Xamarin.Forms solution, you will need to use Visual Studio for Windows. Although the screenshots and samples used throughout this book are demonstrated using Visual Studio for Mac, the code and concepts will also work in Visual Studio for Windows. Refer to the Preface of this book for further details on software and hardware requirements that need to be met to follow along with the concepts in this book.
You'll notice a file in the core library named App.xaml
, which includes a code-behind class in App.xaml.cs
named App
that inherits from Xamarin.Forms.Application
. Initially, the App
constructor sets the MainPage
property to a new instance of a ContentPage
named MainPage
that simply displays some default text.
The first thing we will do in our TripLog app is build the initial views, or screens, required for our UI, and then update that MainPage
property of the App
class in App.xaml.cs
.
If you expand the Dependencies
> NuGet
folder within the main TripLog project, and the Packages
folder in each of the platform projects in the solution, you will see that Xamarin.Forms is a NuGet package that is automatically included when we select the Xamarin.Forms project template. It is possible that the included NuGet packages need to be updated. Update the Xamarin.Forms NuGet packages in each of the projects within the solution to the latest version available.
New for Third Edition!
In this edition of Mastering Xamarin.Forms we will take advantage of some of the new features and capabilities of Xamarin.Forms 4. To do this, we will require a minimum stable version of 4.3 of the Xamarin.Forms NuGet package.
The main page of the app will serve as the entry point into the app and will display a list of existing trip log entries. Our trip log entries will be represented by a data model named TripLogEntry
. Models are a key pillar in the MVVM pattern and data binding, which we will explore more in Chapter 2, MVVM and Data Binding; however, in this chapter, we will create a simple class that will represent the TripLogEntry
model.
Let's now start creating the main page by performing the following steps:
MainPage.xaml
and its code-behind file, MainPage.xaml.cs
, from the TripLog project. We will create our own MainPage
.Views
to the root of the TripLog project. This folder will be where app pages in the application live.ContentPage
to the Views
folder in the TripLog project and name it MainPage
.MainPage
property of the App
class in App.xaml.cs
to a new instance of Xamarin.Forms.NavigationPage
whose root is a new instance of TripLog.MainPage
that we just created:using Xamarin.Forms;
using TripLog.Views;
namespace TripLog
{
public partial class App : Application
{
public App()
{
InitializeComponent();
MainPage = new NavigationPage(new MainPage());
}
// ...
}
}
Notice how we are wrapping our MainPage
with a NavigationPage
. By doing this, we automatically get native components for navigating between pages.
Models
.Models
folder named TripLogEntry
.TripLogEntry
class with auto-implemented properties representing the attributes of an entry:public class TripLogEntry
{
public string Title { get; set; }
public double Latitude { get; set; }
public double Longitude { get; set; }
public DateTime Date { get; set; }
public int Rating { get; set; }
public string Notes { get; set; }
}
CollectionView
control. We will use a DataTemplate
to describe how the model data should be displayed in each of the rows in the CollectionView
using the following XAML in the ContentPage.Content
tag in MainPage.xaml
:<ContentPage
xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TripLog.Views.MainPage"
Title="TripLog">
<ContentPage.Content>
<CollectionView x:Name="trips"
SelectionMode="Single">
<CollectionView.ItemTemplate>
<DataTemplate>
<Grid Padding="10">
<Grid.ColumnDefinitions>
<ColumnDefinition Width="1*" />
<ColumnDefinition Width="3*" />
</Grid.ColumnDefinitions>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
</Grid.RowDefinitions>
<Label Grid.RowSpan="2"
Text="{Binding Date, StringFormat='{0:MMM d}'}" />
<Label Grid.Column="1"
Text="{Binding Title}"
FontAttributes="Bold" />
<Label Grid.Column="1"
Grid.Row="1"
Text="{Binding Notes}" />
</Grid>
</DataTemplate>
</CollectionView.ItemTemplate>
</CollectionView>
</ContentPage.Content>
</ContentPage>
MainPage.xaml.cs
, we will populate the CollectionView ItemsSource
with a hardcoded collection of TripLogEntry
objects. In the next chapter, we will move this collection to the page's data context (that is, its ViewModel
), and in Chapter 6, API Data Access, we will replace this hardcoded data with data from a live Azure backend:public partial class MainPage : ContentPage
{
public MainPage()
{
InitializeComponent();
var items = new List<TripLogEntry>
{
new TripLogEntry
{
Title = "Washington Monument",
Notes = "Amazing!",
Rating = 3,
Date = new DateTime(2019, 2, 5),
Latitude = 38.8895,
Longitude = -77.0352
},
new TripLogEntry
{
Title = "Statue of Liberty",
Notes = "Inspiring!",
Rating = 4,
Date = new DateTime(2019, 4, 13),
Latitude = 40.6892,
Longitude = -74.0444
},
new TripLogEntry
{
Title = "Golden Gate Bridge",
Notes = "Foggy, but beautiful.",
Rating = 5,
Date = new DateTime(2019, 4, 26),
Latitude = 37.8268,
Longitude = -122.4798
}
};
trips.ItemsSource = items;
}
}
At this point, we have a single page that is displayed as the app's main page. If we debug the app and run it in a simulator, emulator, or on a physical device, we should see the main page showing the list of log entries we hardcoded into the view, as shown in the following screenshot:
Figure 6: The TripLog main page
In Chapter 2, MVVM and Data Binding, we will refactor this quite a bit as we implement MVVM and leverage the benefits of data binding.
The new entry page of the app will give the user a way to add a new log entry by presenting a series of fields to collect the log entry details. There are several ways to build a form to collect data in Xamarin.Forms. You can simply use a StackLayout
and present a stack of Label
and Entry
controls on the screen, or you can also use a TableView
with various types of ViewCell
elements. In most cases, a TableView
will give you a very nice default, platform-specific look and feel. However, if your design calls for a more customized aesthetic, you might be better off leveraging the other layout options available in Xamarin.Forms. For the purpose of this app, we will use a TableView
.
There are some key data points we need to collect when our users log new entries with the app, such as title, location, date, rating, and notes. For now, we will use a regular EntryCell
element for each of these fields. We will update, customize, and add things to these fields later in this book. For example, we will wire the location fields to a geolocation service that will automatically determine the location. We will also update the date field to use an actual platform-specific date picker control. For now, we will just focus on building the basic app shell.
In order to create the new entry page that contains a TableView
, perform the following steps:
ContentPage
to the Views
folder in the TripLog project and name it NewEntryPage
.TableView
that will represent the data entry form on the page:<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TripLog.Views.NewEntryPage"
Title="New Entry">
<ContentPage.Content>
<TableView Intent="Form">
<TableView.Root>
<TableSection>
<EntryCell Label="Title" />
<EntryCell Label="Latitude"
Keyboard="Numeric" />
<EntryCell Label="Longitude"
Keyboard="Numeric" />
<EntryCell Label="Date" />
<EntryCell Label="Rating"
Keyboard="Numeric" />
<EntryCell Label="Notes" />
</TableSection>
</TableView.Root>
</TableView>
</ContentPage.Content>
</ContentPage>
Now that we have created the new entry page, we need to add a way for users to get to this new screen from the main page. We will do this by adding a New button to the main page's toolbar. In Xamarin.Forms, this is accomplished by adding a ToolbarItem
to the ContentPage.ToolbarItems
collection and wiring up the ToolbarItem.Clicked
event to navigate to the new entry page, as shown in the following XAML:
<!-- MainPage.xaml -->
<ContentPage
xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TripLog.Views.MainPage"
Title="TripLog">
<ContentPage.ToolbarItems>
<ToolbarItem Text="New" Clicked="New_Clicked" />
</ContentPage.ToolbarItems>
<ContentPage.Content>
<!-- ... -->
</ContentPage.Content>
</ContentPage>
// MainPage.xaml.cs
public partial class MainPage : ContentPage
{
// ...
void New_Clicked(object sender, EventArgs e)
{
Navigation.PushAsync(new NewEntryPage());
}
}
In Chapter 3, Navigation, we will build a custom service to handle navigation between pages and will replace the Clicked
event with a data-bound ICommand ViewModel
property, but for now, we will use the default Xamarin.Forms navigation mechanism.
When we run the app, we will see a New button on the toolbar of the main page. Clicking on the New button should bring us to the new entry page, as shown in the following screenshot:
Figure 7: The TripLog new entry page
We will need to add a save button to the new entry page toolbar so that we can save new items. For now, this button will just be a placeholder in the UI that we will bind an ICommand
to in Chapter 2, MVVM and Data Binding. The save button will be added to the new entry page toolbar in the same way the New button was added to the main page toolbar. Update the XAML in NewEntryPage.xaml
to include a new ToolbarItem
, as shown in the following code:
<ContentPage>
<ContentPage.ToolbarItems>
<ToolbarItem Text="Save" />
</ContentPage.ToolbarItems>
<!-- ... -->
</ContentPage>
When we run the app again and navigate to the new entry page, we should now see the Save button on the toolbar, as shown in the following screenshot:
Figure 8: The TripLog new entry page with Save button
When a user clicks on one of the log entry items on the main page, we want to take them to a page that displays more details about that particular item, including a map that plots the item's location. Along with additional details and a more in-depth view of the item, a detail page is also a common area where actions on that item might take place, such as editing the item or sharing the item on social media. The detail page will take an instance of a TripLogEntry
model as a constructor parameter, which we will use in the rest of the page to display the entry details to the user.
In order to create the entry detail page, perform the following steps:
ContentPage
to the Views
folder in the TripLog project and name it DetailPage
.DetailPage
class in DetailPage.xaml.cs
to take a TripLogEntry
parameter named entry, as shown in the following code:using Xamarin.Forms;
using TripLog.Models;
// ...
public partial class DetailPage : ContentPage
{
public DetailPage(TripLogEntry entry)
{
// ...
}
}
Map
control in the next step.DetailPage.xaml
to include a Grid
layout to display a Map
control and some Label
controls to display the trip's details, as shown in the following code:<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps"
x:Class="TripLog.Views.DetailPage">
<ContentPage.Content>
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="4*" />
<RowDefinition Height="Auto" />
<RowDefinition Height="1*" />
</Grid.RowDefinitions>
<maps:Map x:Name="map" Grid.RowSpan="3" />
<BoxView Grid.Row="1" BackgroundColor="White"
Opacity=".8" />
<StackLayout Padding="10" Grid.Row="1">
<Label x:Name="title"
HorizontalOptions="Center" />
<Label x:Name="date"
HorizontalOptions="Center" />
<Label x:Name="rating"
HorizontalOptions="Center" />
<Label x:Name="notes"
HorizontalOptions="Center" />
</StackLayout>
</Grid>
</ContentPage.Content>
</ContentPage>
DetailPage.xaml.cs
, to center the map and plot the trip's location. We also need to update the Label
controls on the detail page with the properties of the entry
constructor parameter:using Xamarin.Forms;
using Xamarin.Forms.Maps;
using TripLog.Models;
// ...
public DetailPage(TripLogEntry entry)
{
InitializeComponent();
map.MoveToRegion(MapSpan.FromCenterAndRadius(
new Position(entry.Latitude,
entry.Longitude),
Distance.FromMiles(.5)));
map.Pins.Add(new Pin
{
Type = PinType.Place,
Label = entry.Title,
Position = new Position(entry.Latitude, entry.Longitude)
});
title.Text = entry.Title;
date.Text = entry.Date.ToString("M");
rating.Text = $"{entry.Rating} star rating";
notes.Text = entry.Notes;
}
ItemTapped
event of the CollectionView
on the main page to pass the tapped item over to the entry detail page that we have just created, as shown in the following code:<!-- MainPage.xaml -->
<CollectionView x:Name="trips"
SelectionMode="Single"
SelectionChanged="Trips_SelectionChanged">
<!-- ... -->
</CollectionView>
// MainPage.xaml.cs
public partial class MainPage : ContentPage
{
// ...
async void Trips_SelectionChanged(object s, SelectionChangedEventArgs e)
{
var trip = (TripLogEntry)e.CurrentSelection.FirstOrDefault();
if (trip != null)
{
await Navigation.PushAsync(new DetailPage(trip));
}
// Clear selection
trips.SelectedItem = null;
}
}
AndroidManifest.xml
file in the Android project:<application android:label="TripLog.Android">
<meta-data
android:name="com.google.android.maps.v2.API_KEY"
android:value="YOUR-MAPS-API-KEY-HERE" />
</application>
There are some additional steps required for Google Maps to work in the Android app. You can read more about how to properly set everything up in the Xamarin.Forms Map documentation at https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/map.
Xamarin.Forms.Maps
library in each platform-specific startup class (AppDelegate
for iOS and MainActivity
for Android) using the following code:// in iOS AppDelegate
global::Xamarin.Forms.Forms.Init();
Xamarin.FormsMaps.Init();
LoadApplication(new App());
// in Android MainActivity
global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
Xamarin.FormsMaps.Init(this, savedInstanceState);
LoadApplication(new App());
Now, when we run the app and tap on one of the log entries on the main page, it will navigate us to the details page to see more detail about that particular log entry, as shown in the following screenshot:
Figure 9: The TripLog entry detail page
In this chapter, we built a simple three-page app with static data, leveraging the most basic concepts of the Xamarin.Forms toolkit. We used the default Xamarin.Forms navigation APIs to move between the three pages, which we will refactor in Chapter 3, Navigation, to use a more flexible, custom navigation approach.
Now that we have built the foundation of the app, including the basic UI for each page within the app, we'll begin enhancing the app with better architecture design patterns, live data with offline syncing, nicer looking UI elements, and tests. In the next chapter, we will introduce the MVVM pattern and data binding to the app to enforce a separation between the user interface layer and the business and data access logic.