Getting Started using NucliOS IGGridView with Xamarin.iOS

Following up on the theme of getting these Xamarin posts cleaned up, I need to address the IGGridView post as well. Hopefully this will be a better help than that post! If you are a Xamarin.iOS developer that wants to add some flair to the data presentation in your app, we have you covered with the Xamarin.iOS bindings for NucliOS. This post focuses on using the IGGridView control to add a basic data grid to your application. As a bonus, I’ll also show you how to use the Xamarin.Mobile Contacts API to access the Address Book with this cross-platform API.

Using IGGridView with Xamarin.iOS

IGGridView is an iOS layout control that is very flexible and will allow you to create a wide variety of grid-based layouts. The most common use case for the control is as a standard data grid. This post will help you get started using the IGGridView in that context. The app that will be built loads the contacts in the iOS device’s address book and displays the first name, last name, and email address for each of them. The app looks like this:

The data is populated using 100 random data points with values between 5.0 and 45.0. When the Refresh button is tapped, the data will be regenerated and the data points will smoothly animate to their new locations. Let’s get started!

Step 1: Creating the project

Start by creating a Single View iPad application by clicking on “New…” under Solution and configure the project as shown in the following screenshot:

This will set up a project that uses a single view (i.e. no navigation) which is all we need for this simple sample. A ViewController with a XIB file will be created to represent the view. Unlike the first post in the series, we won’t need to customize the XIB file. Since we only need the IGGridView, we will add our user interface from code.

Step 2: Adding and configuring the IGGridView

The first thing we need to do is add a reference to the IG.dll which is found in /Developer/Infragistics/NucliOS 2013 Volume 2/MonoTouch on your machine. To do this, right-click on References and chose “Edit references…”. Go to the .NET Assembly tab and navigate to the IG.dll as shown here:

Now open up the NucliOSGridViewAddressBookViewController.cs file and add the following using statement:

using Infragistics;

Next, add fields for an IGGridView and a IGGridViewDataSourceHelper.

IGGridView _gridView;
IGGridViewDataSourceHelper _dsh;

The IGGridView is our data grid and the IGGridViewDataSourceHelper will help manage the data that is displayed within the grid. The data source helper is capable of auto-generating columns based on the properties on the objects contained in its Data property. Using an IGGridViewDataSourceHelper or one of its derivatives also shields you from having to write a lot of boilerplate code. Your time is too valuable for that so use the helpers when you can!

Add the following code to the ViewDidLoad method in the view controller to set the background color, create an autoresizing IGGridView, and add it to the view controller’s view:

this.View.BackgroundColor = UIColor.White;

_gridView = new IGGridView(this.View.Bounds, IGGridViewStyle.IGGridViewStyleDefault);
_gridView.AutoresizingMask = UIViewAutoresizing.All;    

this.View.Add(_gridView);

We will further customize the data grid once we have our data, but first we need to get that set up.

Step 3: Setting up the address book data

The data grid in the sample application will display the contents of the device’s address book. So, we need to get access to that data. The easiest (and most cross-platform) way to do this in a Xamarin.iOS project is by using the Xamarin.Mobile Contacts API. The Component Store within Xamarin Studio is the easiest way to get started with this. Right-click on the “Components” node under your project and click “Edit Components…” and then click the “Get More Components” button. Find the Xamarin.Mobile component which should look like this:

Add the component to your app. The “Getting Started” section for the component contains the code we need to use the API for what we need to do. Instead of adding the Contact objects from Xamarin.Mobile, we’ll create a lightweight wrapper object that contains only the properties we actually need to display. Add the following class after the closing brace of the view controller:

public class AddressBookItem : NSObject
{
    [Export("FirstName")]
    public String FirstName {get; set;}
    [Export("LastName")]
    public String LastName {get; set;}
    [Export("Email")]
    public String Email {get; set;}
    [Export("LastInitial")]
    public String LastInitial {get; set;}
}

Now that we have our wrapper object we can access the address book and build up our list of AddressBookItem objects. The following code sets up a list of contacts and then iterates over the address book to populate it.

Add the following code after the fields for the grid view and data source helper at the top of the class:

List   _contacts;

Add this code to the ViewDidLoad method:

_contacts = new List ();

var book = new AddressBook ();
var permission = await book.RequestPermission ();

if (!permission) {
    // In a shipping application, you'll want to do something to handle
    // the fact that your user did not give you permission to access the 
    // Address Book.
    Console.WriteLine ("Permission denied by user or manifest");
    return;
}

// Using Xamarin.Mobile, we can perform Linq operations over
// the Address Book entries.  Here we order by Contact.LastName
foreach (Contact contact in book.OrderBy (c => c.LastName)) {
    // Create an AddressBookItem (defined below) for each contact
    // to expose only what we need for the grid...
    AddressBookItem bookItem = new AddressBookItem();
    bookItem.FirstName = contact.FirstName;
    bookItem.LastName = contact.LastName;
    if(contact.Emails.Count () > 0)
        bookItem.Email = contact.Emails.FirstOrDefault().Address;
    else
        bookItem.Email = "";
    bookItem.LastInitial = contact.LastName.Substring(0, 1);
    _contacts.Add(bookItem);
}

SetupGrid();

The SetupGrid() method will take this data and set it up to be displayed in the data grid.

Step 4: Configure the data grid

Now that we have a list of contacts, we are ready to display them in our IGGridView. Although the data source helper we are using is capable of auto-generating the columns for us, we will create our column definitions manually. This is so that we can customize the header text that will appear in the header for each column. The SetupGrid() method will create column definitions and add them to the data source helper. The data will be grouped by the first initial of the last name which will automatically create sections for us. Add the following code to the view controller class:

void SetupGrid ()
{
    // We'll manually create the column definitions so that we can customize
    // the header text for each.  The string passed into the constructor is the
    // property name on the object to use for the column.
    IGGridViewColumnDefinition FirstNameColumn = new IGGridViewColumnDefinition("FirstName");
    FirstNameColumn.HeaderText = "First";
    IGGridViewColumnDefinition LastNameColumn = new IGGridViewColumnDefinition("LastName");
    LastNameColumn.HeaderText = "Last";
    IGGridViewColumnDefinition EmailColumn = new IGGridViewColumnDefinition("Email");
    EmailColumn.HeaderText = "Email";
    
    // We're using the basic IGGridViewDataSourceHelper
    // since our data will be displayed in a standard datagrid
    _dsh = new IGGridViewDataSourceHelper();
    
    // Since we are manually creating columns, turn off auto-generation
    _dsh.AutoGenerateColumns = false;
    _dsh.Data = _contacts.ToArray();
    
    // Add the ColumnDefinitions to the DataSource
    _dsh.ColumnDefinitions.Add(FirstNameColumn);
    _dsh.ColumnDefinitions.Add(LastNameColumn);
    _dsh.ColumnDefinitions.Add(EmailColumn);
    
    // We'll group on the first initial of the LastName
    _dsh.GroupingKey = "LastInitial";
    
    // Set the DataSource
    _gridView.DataSource = _dsh;
    
    // Turn off empty rows
    _gridView.EmptyRows = false;
    
    // Update the data!
    _gridView.UpdateData();
}

And that’s it. The application is ready to go. Run it and you should see your contacts in an IGGridView grouped into sections.

Summary

This post showed you how to set up a basic data grid to display contacts from the address book on the device. In future posts I’ll show you how to customize the grid and also interact with the contents.

You can download the solution here: NucliOSGridViewAddressBook.zip

Contact

If you want to comment or reach out to me, the best place to do that is on Twitter @brentschooley. I can also be reached via email at bschooley@infragistics.com.