Adding the SQLite NuGet Packages

The first thing you need to do is to add NuGet packages that allow you to work with SQLite databases. SQLite is already bundled in iOS and Android, so it is a convenient choice for local data access. By following the lessons learned in Chapter 2, add the NuGet package called SQLite.Net PCL to all the three projects in the solution. Figure 8-1 shows the appropriate NuGet package in the Add Packages dialog.

Figure 8-1. Adding the SQLite.Net PCL package

Once you have added the package to the three projects and before you start implementing data access, some minor changes are required to the Item class. In fact, the SQLite library exposes data annotation attributes that you can use to decorate class names and properties to define the table name, column names, identity, required columns, and some basic validation rules such as maximum string length. In Visual Studio, open the Item.cs file and add a using SQLite.Net.Attributes directive first. The next step is to decorate the class name with the Table attribute to specify a table name and define a property called Id that can be used as the identity column. This is the code you need to edit the Item class (the remaining code will be left unchanged):

[Table("Items")]
public class Item : INotifyPropertyChanged
{

    private int id;
    [PrimaryKey, AutoIncrement]
    public int Id
    {
        get
        {
            return id;
        }
        set
        {
            id = value;
            OnPropertyChanged();
        }
    }

    // The rest of the code is unchanged...
}

Decorating the class name with Table is optional. If not specified, the table will have the same name as the class. In this case, a table called Item would be generated, but a plural name is more consistent, so the Table attribute allows you to specify Items as the table name. The Id property is decorated with the PrimaryKey and AutoIncrement attributes, which set the column as the primary key and as the table identity with auto-increment, respectively. By default, column names reflect property names. You can use the Column attribute to define column names different from property names. Other common attributes are NotNull (marks a property as required), MaxLength (sets the maximum length for a string property), and Ignore (does not include the property as a column in the table).

Implementing the Dependency Service

To access the SQLite database from shared code, you need an instance of an object of type SQLiteConnection that exposes, among the others, the database path name and that allows for creating, querying, and deleting tables. This path name must be constructed in the iOS and Android projects, and both must return a SQLiteConnection object. To accomplish this, in the PCL project add a new interface called IDataAccess.cs. You can follow the same steps you saw to add a class, but in the New File dialog you will find an item called Empty Interface (see Figure 8-2).

Figure 8-2. Adding an interface

The code for the interface is simple and looks like the following:

using SQLite.Net;
namespace NewsReader
{
    public interface IDataAccess
    {
        SQLiteConnection DbConnection();
    }
}

The interface defines a method called DbConnection that returns an object of type SQLiteConnection. Platform-specific classes will need to expose their own implementation of the method. To accomplish this, add two files called DataAccess.cs, one in the Android project and one in the iOS project. The Android implementation looks like the following:

using System;
using System.IO;
using Xamarin.Forms;
using NewsReader.Droid;
using SQLite.Net;
using SQLite.Net.Platform.XamarinAndroid;

[assembly: Dependency(typeof(DataAccess))]
namespace NewsReader.Droid
{
    public class DataAccess : IDataAccess
    {
        public SQLiteConnection DbConnection()
        {
            string dbName = "newsreader.db3";
            string dbPath =
                Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Personal),
                             dbName);

            return
                new SQLiteConnection(new SQLitePlatformAndroid(),
                                     dbPath);
        }
    }
}

Platform-specific implementations of an interface that is used with the dependency service must be decorated with the Dependency attribute, which is actually applied at the namespace level with the assembly: enforcement to ensure that only one implementation will be used (and in the case of multiple implementations, the first one is used). As you can see, the class properly implements the interface by exposing the DbConnection method, whose body first retrieves the user’s personal folder path on Android and concatenates it (Path.Combine) with the database name, which I have called newsreader.db3 but that you can replace with a name of your choice. Finally, an instance of the SQLiteConnection object is returned, passing the target platform (SQLite.Net.Platform.XamarinAndroid.SQLitePlatformAndroid) and the database path name.

Similarly, you need an implementation on the iOS side, which looks as follows:

using System;
using System.IO;
using NewsReader;
using NewsReader.iOS;
using SQLite.Net;
using Xamarin.Forms;

[assembly: Dependency(typeof(DataAccess))]
namespace NewsReader.iOS
{
    public class DataAccess: IDataAccess
    {
        public SQLiteConnection DbConnection()
        {
            string dbName = "newreader.db3";
            string personalFolder =
                   Environment.GetFolderPath(Environment.SpecialFolder.Personal);

            string libraryFolder = Path.Combine(personalFolder, "..", "Library");
            string dbPath = Path.Combine(libraryFolder, dbName);

            return
                new SQLiteConnection(new SQLite.Net.Platform.XamarinIOS.SQLitePlatformIOS(),
                                     dbPath);
        }
    }
}

As you can see, there is a difference in how folders are handled in iOS. Here you have to construct the path of the local library, and then you concatenate it with the database name. The target platform is represented by the SQLitePlatformIOS type. Now you have two platform-specific implementations of a class that generate the path name of the database and that return an instance of SQLiteConnection. The next step is to add some logic to use a database for storing news. The very first time the app starts, it will download the news feed content from the Internet and will store the list of items in the database. This way, the next time the app starts, contents will be retrieved from the local database instead of downloading them again from the Internet, which improves perceived performance and offers offline contents. However, the user must be able to refresh the news list, for example, with the pull-to-refresh gesture. Having that said, open the ItemService.cs file and edit the QueryRssAsync method as follows (explanations will come shortly):

public static async Task<IEnumerable<Item>> QueryRssAsync(bool forceReload)
{
    SQLiteConnection database = DependencyService.Get<IDataAccess>().DbConnection();
    database.CreateTable<Item>();

    // if force reload or the table contains no item...
    if (forceReload == true || !database.Table<Item>().Any())
    {
        var client = new HttpClient();

        var data = await client.GetStringAsync(FeedUri);

        var doc = XDocument.Parse(data);
        var dcNS = XNamespace.Get("http://purl.org/dc/elements/1.1/");

        var query = (from video in doc.Descendants("item")
                     select new Item
                     {
                         Title = video.Element("title").Value,
                         Author = video.Element(dcNS + "creator").Value,
                         Link = video.Element("link").Value,
                         Thumbnail = GetThumbnail(video),
                         PublicationDate =
                             DateTime.Parse(video.Element("pubDate").Value,
                             System.Globalization.CultureInfo.InvariantCulture)                                                                                                                                                                                                                           
                     });

        client.Dispose();

        database.DropTable<Item>();
        database.CreateTable<Item>();
        database.InsertAll(query);

        return query;
    }
    else
    {
        return database.Table<Item>().AsEnumerable();
    }
}

The updated version of the method takes an argument of type bool, called forceUpload . If true, the method will reload contents from the Internet and save them into the database; if false, the method returns the list of Item objects stored in the database. Notice the first line of the method body: it declares a variable of type SQLiteConnection that receives the result of the invocation to the platform-specific implementation of the DbConnection method you saw before. To accomplish this, the code invokes the static DependencyService.Get method , which is a generic method and whose type parameter is the interface that you defined in the PCL project. With this approach based on IoC, you do not need to care about the platform your app is running on. The DependencyService class calls the appropriate platform-specific implementation of the interface and, in this case, of the DbConnection method. The DependencyService class crosses any barriers between Xamarin.Forms and native APIs, and therefore it allows you to do anything you could do with Xamarin.Android and Xamarin.iOS in terms of full API availability. The condition that forces the code to load data from the Internet is either forceUpload = true or that the database contains no items, regardless of the value of forceUpload. The Table generic method from the SQLiteConnection class allows you to interact with the table whose type is represented in the generic type parameter. In this case, Table<Item> allows you to interact with the table of Item objects. This method returns an object of type TableQuery<T>, which implements the IEnumerable<T> interface and therefore supports the LINQ extension method, such as Any, that is used to detect whether the table contains at least one object. So, if either forceUpload is true or Any returns false (which means no items), the code downloads the RSS feed content from the Internet. The code for this is unchanged. When the download completes, the code invokes other methods from the SQLiteConnection instance, such as DropTable (which deletes a table), CreateTable (which creates a table), and InsertAll (that inserts all the items in an IEnumerable collection into the database). Notice that DropTable and CreateTable are generic and require the type parameter that represents the table, the Item class in this case. InsertAll is not generic, and the SQLite library is intelligent enough to automatically resolve the type for the items in the collection, storing them in the proper table. The SQLiteConnection class exposes a large number of methods to work with both individual records and multiple records, such as Insert, InsertAll, Update, UpdateAll, Delete, and DeleteAll, and it also exposes methods to send SQL commands, such as CreateCommand, and methods to work with transactions, such as BeginTransaction and Commit. IntelliSense provides helpful tooltips when calling these methods. If instead forceUpdate is false and there is at least one record in the table, the code returns the collection of Item objects exposed by the Table method, converted into IEnumerable<Item> with AsEnumerable so that callers do not rely on a specialized type such as TableQuery. The next, simple code edit you need to do is in the ItemViewModel.cs class file, more specifically in the InitializeAsync method. The edit you need to do is to simply accept a parameter of type Boolean that is passed to the invocation of QueryRssAsync and that looks like this:

public async Task InitializeAsync(bool forceReload)
{
    if (IsBusy)
        return;

    IsBusy = true;

    try
    {
        var result = await ItemService.QueryRssAsync(forceReload);
        if (result != null)
        {
            this.Items = null;
            this.Items = new ObservableCollection<Item>(result);
        }
    }
    catch (Exception)
    {

        this.Items = null;
    }
    finally
    {
        IsBusy = false;
    }
}

Finally, you need to make a couple of edits in the NewsReaderPage.xaml.cs file. In fact, you need to add the same Boolean parameter to the LoadDataAsync method and pass true or false depending on whether the app is starting up or whether pull-to-refresh has been invoked by the user. The following code contains the few edits:

private async Task LoadDataAsync(bool forceReload)
{

    this.NewsActivity.IsVisible = true;
    this.NewsActivity.IsRunning = true;
    await this.viewModel.InitializeAsync(forceReload);
    this.RssView.ItemsSource = this.viewModel.Items;
    this.NewsActivity.IsVisible = false;
    this.NewsActivity.IsRunning = false;
}

protected override async void OnAppearing()
{
    base.OnAppearing();
    await LoadDataAsync(false);
}

private async void Handle_Refreshing(object sender, System.EventArgs e)
{
    await LoadDataAsync(true);
}

You have completed the implementation of the required code to store and load data against a SQLite database so that the contents are downloaded from the Internet only when the app is launched for the first time and only if the user pulls to refresh the ListView control. You can simply run the sample application and see how it benefits from the steps described in this section.

Adding Native Views to XAML

Xamarin.Forms allows developers to add native views directly into the XAML markup . This feature has been available only since a few versions, and it makes it really easy to use native visual elements. To demonstrate this feature, create a new blank Xamarin.Forms project called NativeViews .

In the XAML of the root page, you first need to add the following platform XML namespaces:

xmlns:ios="clr-namespace:UIKit;assembly=Xamarin.iOS;targetPlatform=iOS"
xmlns:androidWidget="clr-namespace:Android.Widget;assembly=Mono.Android;targetPlatform=Android"
xmlns:formsandroid=
"clr-namespace:Xamarin.Forms;assembly=Xamarin.Forms.Platform.Android;targetPlatform=Android"

Remember that you can choose a different name for the namespace identifier. As you can see, the first two namespaces point to the corresponding C# namespace that exposes native controls. The third namespace points to Xamarin.Forms and is required with Android widgets. Using native views is then really straightforward since you just need to declare the specific view for each platform you want to target, as follows:

<StackLayout>
    <ios:UILabel Text="Native Text" View.HorizontalOptions="Start"/>
    <androidWidget:TextView Text="Native Text"
                   x:Arguments="{x:Static formsandroid:Forms.Context}" />
</StackLayout>

In the previous example, the XAML markup is using a UILabel native label on iOS and a TextView native label on Android. Notice how you can assign properties the way you would with any other view. With Android widgets, you must supply the current Xamarin.Forms UI context, which is done with a special form of data binding that binds the static (x:Static) Forms.Context property to the view. You can interact with views in C# code as you would normally do, such as with event handlers.

Introducing Custom Renderers

Xamarin.Forms renders visual elements by leveraging native views and layouts on each platform, but it is limited to those properties that exist cross-platform. If you need further customizations, you are allowed to use native visual elements directly so that you can make all the customizations you need. Customizations at this level are not limited to layout, but they might also involve changing a view’s behavior.

To accomplish this, you use the so-called custom renderers . A custom renderer is a class that inherits from the class that maps the native view (the renderer) in Xamarin.Forms and that must be implemented in each platform project. Here you can edit the layout, override members (where possible), and change the behavior of the native view, which you will then be able to use in XAML. For a better understanding, let’s consider the following example, which requires you to create a new blank Xamarin.Forms project called CustomRenderers. Suppose you have an Entry view in Xamarin.Forms and you want the content of such an Entry to be automatically selected when the user taps the text box. Because the Xamarin.Forms Entry does not support this, you can create a custom renderer that works at the platform level. In the PCL project, add a new class called SelectableEntry, which inherits from Entry as follows:

using Xamarin.Forms;

namespace CustomRenderers
{
    public class SelectableEntry: Entry
    {

    }
}

Technically speaking, creating a class that inherits from the original view is not mandatory. However, any customizations you provide would affect all the views of the same type (Entry in this case), which is probably not the desired behavior. By creating a derived class, you can customize only this one and decide when to use the customized view or the original view. The next step is creating a class that extends the built-in renderer (called EntryRenderer in this case), and this must be done in both the iOS and Android projects. For example, the following code must be added to a class file in the iOS project (called SelectableEntryRenderer.cs) and demonstrates how to extend the EntryRenderer class by handling the EditingDidBegin event on the UITextField view and calling the PerformSelector method, passing an ObjCRuntime.Selector object that performs the selectAll selection over the text box:

using System;
using Xamarin.Forms;
using Xamarin.Forms.Platform.iOS;
using CustomRenderers;
using CustomRenderers.iOS;

[assembly: ExportRenderer(typeof(SelectableEntry), typeof(SelectableEntryRenderer))]
namespace CustomRenderers.iOS
{
    public class SelectableEntryRenderer : EntryRenderer
    {
        protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged(e);
            var nativeTextField = Control;
            nativeTextField.EditingDidBegin += (object sender, EventArgs eIos) =>
            {
                nativeTextField.PerformSelector(new ObjCRuntime.Selector("selectAll"),
                null, 0.0f);
            };
        }
    }
}

Notice the ExportRenderer attribute : it says that objects of type SelectableEntry will be rendered through objects of type SelectableEntryRenderer. In Android, the logic is pretty similar, so you have to add a SelectableEntryRenderer.cs file to the Android project and write the following code:

using System;
using Xamarin.Forms;
using Xamarin.Forms.Platform.Android;
using CustomRenderers;
using CustomRenderers.Droid;

[assembly: ExportRenderer(typeof(SelectableEntry), typeof(SelectableEntryRenderer))]
namespace CustomRenderers.Droid
{
    public class SelectableEntryRenderer: EntryRenderer
    {
        protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged(e);
            if (e.OldElement == null)
            {
                var nativeEditText = (global::Android.Widget.EditText)Control;
                nativeEditText.SetSelectAllOnFocus(true);
            }
        }
    }
}

In the case of Android, the view is an object of type EditText, and the customization is done by invoking its SetSelectAllOnFocus method . At this point, you can simply add a SelectableEntry view to your XAML as follows:

<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:local="clr-namespace:CustomRenderers"
    x:Class="CustomRenderers.CustomRenderersPage">

    <StackLayout Orientation="Vertical" Padding="20">
        <Label Text="Enter some text:"/>

        <local:SelectableEntry x:Name="MyEntry"
         HorizontalOptions="FillAndExpand"/>
    </StackLayout>
</ContentPage>

The local XML namespace is automatically available in the page declaration. You will see that IntelliSense will help you select the view from the list of objects exposed by the local namespace, and the XAML editor’s behavior is the same as with other views. If you now run the application, you will see how the text in the SelectableEntry view will be automatically selected with a tap (see Figure 8-4).

Figure 8-4. The custom renderer in action

In summary, with custom renderers you can modify the layout and behavior of a view, and you can then use the view in XAML like any other Xamarin.Forms control.

Introducing Effects

Sometimes you just need to customize some layout properties of a view, without the need to change its behavior. To accomplish this, Xamarin.Forms has the concept of an effect. At a higher level, an effect can be thought of as a simplified custom render that is limited to customizing layout properties. An effect is a class that inherits from PlatformEffect and that must be implemented in all the platform projects. For the next example, I will be extending the CustomRenderers project created previously.

Suppose you want to change the background color for some native views. In the iOS project, add a file called BackgroundEffect.cs and the following code:

using System;
using CustomRenderers.iOS;
using UIKit;
using Xamarin.Forms;
using Xamarin.Forms.Platform.iOS;

[assembly: ResolutionGroupName("MyEffects")]
[assembly: ExportEffect(typeof(BackgroundEffect), "BackgroundEffect")]
namespace CustomRenderers.iOS
{
    public class BackgroundEffect: PlatformEffect
    {
        private UIColor originalColor;
        protected override void OnAttached()
        {
            try
            {
                originalColor = Control.BackgroundColor;
                Control.BackgroundColor = UIColor.FromRGB(204, 153, 255);
            }
            catch
            {
                // Cannot set property on attached control
            }
        }

        protected override void OnDetached()
        {
            try
            {
                Control.BackgroundColor = originalColor;
            }
            catch
            {

            }
        }
    }
}

An effect definition first requires you to specify a resolution group name. This can be considered as the collection of effects your new class belongs to. Then, with the ExportEffect attribute , you specify the type you are exporting and a name that will be used in shared code for resolving the effect. You then need to override both the OnAttached and OnDetached methods. The first one is called when the effect is assigned to a view, and the second one is called when the effect is removed from the view. In the case of iOS, the background color of a view is an object of type UIColor. For Android, the logic is similar, so you still need a code file called BackgroundEffect.cs in the Android project, with the following code:

using System;
using Android.Graphics.Drawables;
using Xamarin.Forms;
using Xamarin.Forms.Platform.Android;
using CustomRenderers.Droid;

[assembly: ResolutionGroupName("MyEffects")]
[assembly: ExportEffect(typeof(BackgroundEffect), "BackgroundEffect")]
namespace CustomRenderers.Droid
{
    public class BackgroundEffect : PlatformEffect
    {
        private Android.Graphics.Color originalColor;

        protected override void OnAttached()
        {
            try
            {
                originalColor = (Control.Background as ColorDrawable).Color;
                Control.SetBackgroundColor(Android.Graphics.Color.LightGreen);
            }
            catch
            {
                // Cannot set property on attached control
            }
        }

        protected override void OnDetached()
        {
            Control.SetBackgroundColor(originalColor);
        }
    }
}

In Android, the background color of a control is an object of type Drawable. At a deeper level of inheritance, it is actually of type ColorDrawable, so a cast is required to access its Color property, whose value is stored for reverting to the original color when OnDetached is called. Then a simple invocation to SetBackgroundColor allows for changing the background color. The next, easy step is to add a class to the PCL project that acts as a bridge between the user interface and the platform-specific effect definitions. Add a class file called BackgroundEffect.cs with the following code:

using System;
using Xamarin.Forms;

namespace CustomRenderers
{
    public class BackgroundEffect: RoutingEffect
    {
        public BackgroundEffect(): base("MyEffects.BackgroundEffect")
        {
        }
    }
}

This class inherits from RoutingEffect, which provides the infrastructure to expose effects to the user interface. Notice how the constructor of the base class is invoked, passing a string that contains the resource group name and the effect name. The final step is consuming the effect in XAML. For example, you can apply the effect to the SelectableEntry view defined previously, as follows:

<local:SelectableEntry x:Name="MyEntry"
 HorizontalOptions="FillAndExpand">
    <local:SelectableEntry.Effects>
        <local:BackgroundEffect/>
    </local:SelectableEntry.Effects>
</local:SelectableEntry>

Obviously, you can apply effects to any supported view. Effects must be added to the Effects collection as in the code shown earlier. As you add the effect, the previewer in Visual Studio will automatically render the layout change. You are not limited to using effects in XAML because they also can be added in C# code. In this case, the code you write would look like this:

MyEntry.Effects.Add (Effect.Resolve ("MyEffects.BackgroundEffect"));

Effects is a .NET collection, and therefore you can invoke the Add method to add an effect. Notice that an effect is not referred to as an object, so you must resolve the effect by calling Effect.Resolve and passing a string that is made of the resource group name and the effect name. With a limited effort, you have been able to change the layout of visual elements without the need to implement a custom renderer, which is instead preferred when you need to change also the behavior of controls.