What is Xamarin

We can’t just create an android project and start writing C# in it. That would be crazy! Right? We need some kind of wrapper or framework for that. You may have heard of a JavaScript framework called Cordova which allow you to write cross platform mobile apps using the web stacks (HTML, CSS, JavaScript). Likewise, now we can also make cross platform apps with C# using Xamarin framework. Xamarin provides three solution templates to build mobile apps,

Why Xamarin.Forms

I am using Xamarin.Forms for the demo which I’ll demonstrate soon. Reason behind choosing Xamarin.Forms is I am a windows phone developer (guilty of charge) which means I already know XAML. Other than that I’m a huge fan of code sharing which means I like to write code once and get it working in all the possible platforms. If you want to know more about Xamarin, you can go to their official site from this link.

What are we Building

Xamarin.Forms is a great choice for building data driven apps. So let’s make one. Let’s make an app which will show all the characters from STAR WARS movies in a ListView. I found a free API online from where I can get all the movie characters in a JSON format from this link.

Building the App

Open up the Xamarin Studio. Create a new Xamarin.Forms app. Give your app a name. You can keep the Identifier as it is. If you are on a MAC, you will have the iOS checkbox enabled for you. Since I’m on Windows I can only target the Android platform. Select portable or shared class library in the Shared Code section. Finish the next steps.

Building the App

click next

After you create the solution, you will have three projects in your solution. One for the shared code (starwars), one for the android app and last one as the name goes is a UI testing project for you app. Just set the starwars.Droid as a startup project and run your app.

startup project

Let’s discuss some of the basics of this skeleton app. So where this “Welcome to Xamarin Forms!” is coming from? If you go to the startwars.cs file, you will see the exact reason of this magic! In the App() constructor, we have set the MainPage (the starting page) property to a newly instantiated ContentPage. This is one of many built in classes that Xamarin gives us to build the UI of our app. Everything else inside ContentPage is self-explanatory. We added a StackLayout to the Content property. StackLayout is used to place your controls in a stack on the ContentPage. The StackLayout itself is vertically centered ( VerticalOptions = LayoutOptions.Center ) on the page. We have Label which is used for showing raw text as child to the StackLayout. And the text is aligned in the center ( XAlign = TextAlignment.Center ) of the Label. I’ve mapped the whole code to the output layout so that you have a good understanding on what is happening.

layout

We can add a standalone ContentPage in the project and mimic all these things with XAML, so right click and add a new file to the shared project. Select the “Forms ContentPage Xaml” from the list. Since this is where I’ll show all the STAR WARS characters, so I named it SWCharacters.

Forms ContentPage Xaml

After adding we’ll have a XAML document with a connected C# code behind.

XAML document

If you notice carefully, you will see that we have a ContentPage and the Content node set up for us. Time to add the other pieces we are missing.

ContentPage

As you can see, I have added the equivalent XAML markup for the view. Now, we can remove all the codes attached to the MainPage property and attach a new instance of our newly created ContentPage. Save everything and give your app a spin. You will have the same result as before.

result

Enough with the basics. Let’s get back to our app. We need to make a HTTP call to the API to get all the characters. To do that we need to add the Microsoft HTTP Client Libraries package. We also need the Json.NET which will help us parsing raw JSON data to class objects. Search and add both of those in your project from Nuget (Select the shared project > Go to “Project” menu from top menu bar > Add Nuget Packages).

Add Nuget Packages

Go to the SWCharacters code behind (SWCharacters.cs) and add these lines of code given below,

  1. public ObservableCollection<People> Peoples { get; set; }
  2. private HttpClient _client;
  4. private const string PeopleDataUrl = "http://swapi.co/api/people";
  6. public SWCharacters ()
  7. {
  8. InitializeComponent ();
  9. Peoples = new ObservableCollection<People>();
  10. }
  12. public async Task GetAllCharacters()
  13. {
  14. try
  15. {
  16. _client = new HttpClient();
  17. var response = await _client.GetStringAsync(PeopleDataUrl);
  19. if (!string.IsNullOrEmpty(response))
  20. {
  21. var data = JsonConvert.DeserializeObject<RootObject>(response);
  22. foreach (var people in data.Peoples)
  23. {
  24. Peoples.Add(people);
  25. }
  26. }
  27. }
  28. catch (Exception)
  29. {
  30. await DisplayAlert("Error", "Something went wrong", "Ok");
  31. }
  32. }
  33. private async void PeopleButton_OnClicked(object sender, EventArgs e)
  34. {
  35. GetAllCharacters();
  36. }
I’ve grabbed all the characters through a HTTP ‘GET’ call to swapi.co/people and serialized into a ObservableCollection (an extended version of the List class in C#) of people objects using Json.Net’s JsonConvert.DeserializeObject.

Here is the serialized object class that I was talking about. The attribute ([JsonObject("Result")], [JsonProperty("results")] are used only for giving those class and property a generic name.

People.cs
  1. [JsonObject("Result")]
  2. public class People
  3. {
  4. public string name { get; set; }
  5. public string height { get; set; }
  6. public string mass { get; set; }
  7. public string hair_color { get; set; }
  8. public string skin_color { get; set; }
  9. public string eye_color { get; set; }
  10. public string birth_year { get; set; }
  11. public string gender { get; set; }
  12. public string homeworld { get; set; }
  13. public string created { get; set; }
  14. public string edited { get; set; }
  15. public string url { get; set; }
  16. }
  18. public class RootObject
  19. {
  20. public int count { get; set; }
  21. public string next { get; set; }
  22. public object previous { get; set; }
  24. [JsonProperty("results")]
  25. public List<People> Peoples { get; set; }
  26. }
Now, you can ask me where I got this class from. It’s really easy to generate class objects for serialization. I went to the swapi website and initiated a request to their API. I copied the JSON result. Then I went to this site and pasted my JSON to get the appropriate class objects. See the images below,

swapi

JSON

I’ve created a class file in my project and paste those two classes inside that. I’m done here. You can see a PeopleButton_OnClicked event in the SWCharacters.cs. That’s because I wanted to initiate the HTTP call only when I click on that button from the UI. Here is new XAML markup for the app that creates the button.
  1. <ContentPage.Content>
  2. <StackLayout VerticalOptions="Center">
  3. <Button x:Name="PeopleButton" Text="Get People" Clicked="PeopleButton_OnClicked"></Button>
  4. </StackLayout>
  5. </ContentPage.Content>
Now if you run the project and click on the button, you will get the people data from the API. The button is only for checking whether we have a successful call to the API or not. I’ve placed some debug points and check if everything’s okay or not.

get people

code

Next we will replace the button with a ListView control and attached its ItemSource property to our ObservableCollection of people. Replace your previous XAML markup with the following:
  1. <ContentPage.Content HorizontalOptions="FillAndExpand" VerticalOptions="FillAndExpand">
  2. <StackLayout>
  3. <ListView x:Name="PeopleListView" HasUnevenRows="True">
  4. <ListView.ItemTemplate>
  5. <DataTemplate>
  6. <ViewCell>
  7. <ViewCell.View>
  8. <Grid Padding="5">
  9. <Grid.RowDefinitions>
  10. <RowDefinition Height="Auto"></RowDefinition>
  11. <RowDefinition Height="Auto"></RowDefinition>
  12. </Grid.RowDefinitions>
  14. <Label Text="{Binding name}" FontSize="16" Grid.Row="0"></Label>
  15. <Label Text="{Binding height}" Grid.Row="1"></Label>
  16. </Grid>
  17. </ViewCell.View>
  18. </ViewCell>
  19. </DataTemplate>
  20. </ListView.ItemTemplate>
  21. </ListView>
  22. </StackLayout>
  23. </ContentPage.Content>
So, we have a ListView instead of the button we previously had. To set the look and feel of the items added to the ListView, we have ListView.ItemTemplate. To be able to bind controls inside a ListView.ItemTemplate to appropriate list item’s properties, we have DataTemplate. ViewCell in one of the many Cell controls of Xamarin. ViewCell is used just for showing raw data, you can use EntryCell if you want textbox control as a part of your list item. I’ve placed another Grid layout inside ViewCell.View and lastly added two Labels. One of the Label is bound to the name propety of the character while the second one is bound to the height property. The new code behind looks like the following,
  1. public partial class SWCharacters : ContentPage
  2. {
  4. public ObservableCollection<People> Peoples { get; set; }
  5. private HttpClient _client;
  7. private const string PeopleDataUrl = "http://swapi.co/api/people";
  9. public SWCharacters ()
  10. {
  11. InitializeComponent ();
  12. Peoples = new ObservableCollection<People>();
  13. GetAllCharacters();
  14. }
  16. public async Task GetAllCharacters()
  17. {
  18. try
  19. {
  20. _client = new HttpClient();
  21. var response = await _client.GetStringAsync(PeopleDataUrl);
  23. if (!string.IsNullOrEmpty(response))
  24. {
  25. var data = JsonConvert.DeserializeObject<RootObject>(response);
  26. foreach (var people in data.Peoples)
  27. {
  28. Peoples.Add(people);
  29. }
  31. PeopleListView.ItemsSource = Peoples;
  32. }
  33. }
  34. catch (Exception)
  35. {
  36. DisplayAlert("Error", "Something went wrong", "Ok");
  37. }
  38. }
  39. }
Since I’ve removed the button from the view, so I also deleted the event handler associated with that and initiated the HTTP request from the main constructor. Again I’ve bound the ItemSource property of our ListView to the observable collection I talked about (PeopleListView.ItemsSource = Peoples;). Now if you run this project, after a while you will get the character list with the name and height property shown on the respective labels.

respective labels

What you should be concerned of

To make this demo project simple and easy to understand I’ve done some things against the rules. Like I called an asynchronous process from the constructor, which is definitely bad! You can search the web and follow the best practices in writing asynchronous code. Again, write whole lot of code in the XAML code behind. Basically in real life you would follow pattern like MVVM which will omit these codes from the UI backend and make your app unit testable.

Downloading and running the App

Download the solution as a zip format. Unzip and open it in your Xamarin Studio. I’ve removed all the packages .dll files from the project. So you will need to restore the packages. Just like you added a nuget package in the project, restore the packages from the option right below it.

What’s Next

These were some of the basic building apps with Xamarin Forms. Consider this as a “Hello World” program. Download the project and add some more functionalities like a detail page for a specific character, add a loading indicator to allow user to know that you are downloading stuffs from the internet. Again play with the APIs available on the swapi website and make full-fledged STAR WARS fan app. You can find a whole lot of control available for you to use here. Follow Xamarin’s API documentation if you stuck anywhere. Have fun and I’ll see you in the next post. Bye bye geeks!