Just like the beginning of many new mobile projects, we will start with an idea.
We will create a travel app named TripLog and, like 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:

• View existing log entries (online and offline)
• Add new log entries with the following data:
  • Title
  • Location using GPS
  • Date
  • Notes
  • Rating
• Sign into the app

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: 


1. In Visual Studio, click on File | New Solution. This will bring up a series of dialog screens that will walk you through creating a new Xamarin.Forms solution. On the first dialog, click on App on the left-hand side, under the Multiplatform section, and then select Blank Forms App, as shown in the following screenshot:

2. On the next dialog screen, enter the name of the app, TripLog, ensure that Use Portable Class Library is selected for the Shared Code option, and that Use XAML for user interface files option is checked, as shown in the following screenshot:

3. On the final dialog screen, simply click on the Create button, as follows:

After creating the new Xamarin.Forms solution, you will have several projects created within it, as shown in the following screenshot:

There will be a single portable class library project and two platform-specific projects, as follows:

• TripLog: This is a portable class library project that will serve as the core layer of the solution architecture. This is the layer that will include all our business logic, data objects, Xamarin.Forms pages, and other non-platform-specific code. The code in this project is common and not specific to a platform, and can therefore, be shared across the platform projects.
• TripLog.iOS: This is the iOS platform-specific project containing all the code and assets required to build and deploy the iOS app from this solution. By default, it will have a reference to the TripLog core project. 

• TripLog.Droid: This is the Android platform-specific project containing all the code and assets required to build and deploy the Android app from this solution. By default, it will have a reference to the TripLog core project.

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 TripLogPage 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 Packages folder within each of the 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. Ensure that you update them in each of the projects within the solution so that you are using the latest version of Xamarin.Forms.

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 Model-View-ViewModel (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 us now start creating the main page by performing the following steps:

1. First, add a new Xamarin.Forms XAML ContentPage to the core project and name it MainPage.

2. Next, update the 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:

      public App()
      {
          InitializeComponent();
          MainPage = new NavigationPage(new MainPage());
      }

3. Delete TripLogPage.xaml from the core project as it is no longer needed.
4. Create a new folder in the core project named Models.
5. Create a new empty class file in the Models folder named TripLogEntry.
6. Update the 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; }
      }

7. Now that we have a model to represent our trip log entries, we can use it to display some trips on the main page using a ListView control. We will use a DataTemplate to describe how the model data should be displayed in each of the rows in the ListView 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.MainPage"
          Title="TripLog">
          <ContentPage.Content>
              <ListView x:Name="trips">
                  <ListView.ItemTemplate>
                      <DataTemplate>
                          <TextCell Text="{Binding Title}" 
                                    Detail="{Binding Notes}" />
                      </DataTemplate>
                  </ListView.ItemTemplate>
              </ListView>
          </ContentPage.Content>
      </ContentPage>

8. In the main page's code-behind, MainPage.xaml.cs, we will populate the ListView ItemsSource with a hard-coded 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 hard-coded 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(2017, 2, 5),
                      Latitude = 38.8895,
                      Longitude = -77.0352
                  },
                  new TripLogEntry
                  {
                      Title = "Statue of Liberty",
                      Notes = "Inspiring!",
                      Rating = 4,
                      Date = new DateTime(2017, 4, 13),
                      Latitude = 40.6892,
                      Longitude = -74.0444
                  }, 
                  new TripLogEntry
                  {
                      Title = "Golden Gate Bridge",
                      Notes = "Foggy, but beautiful.",
                      Rating = 5,
                      Date = new DateTime(2017, 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 hard-coded into the view, as shown in the following screenshot.

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:

1. First, add a new Xamarin.Forms XAML ContentPage to the core project and name it NewEntryPage.
2. Update the new entry page using the following XAML to build the 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.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>
    <ContentPage.ToolbarItems>
        <ToolbarItem Text="New" Clicked="New_Clicked" /> 
    </ContentPage.ToolbarItems>
</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:

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:

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:

1. First, add a new Xamarin.Forms XAML ContentPage to the project and name it DetailPage.
2. Update the constructor of the DetailPage class in DetailPage.xaml.cs to take a TripLogEntry parameter named entry, as shown in the following code:

      public class DetailPage : ContentPage
      {
          public DetailPage(TripLogEntry entry) 
          {
              // ...
          } 
      }

3. Add the Xamarin.Forms.Maps NuGet package to the core project and to each of the platform-specific projects. This separate NuGet package is required in order to use the Xamarin.Forms Map control in the next step.
4. Update the XAML in 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.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>

5. Update the detail page's code-behind, 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:

      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;
      }

6. Next, we need to wire up the ItemTapped event of the ListView 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 -->
      <ListView x:Name="trips" ItemTapped="Trips_ItemTapped">
          <!-- ... -->
      </ListView>

      // MainPage.xaml.cs
      public MainPage()
      {
          // ...

          async void Trips_ItemTapped(object sender, ItemTappedEventArgs e)
          {
              var trip = (TripLogEntry)e.Item;
              await Navigation.PushAsync(new DetailPage(trip));

              // Clear selection
              trips.SelectedItem = null;
          }
      }

7. Finally, we will need to initialize the 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, bundle);
      Xamarin.FormsMaps.Init(this, bundle);
      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:

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.