Getting Started

This section provides a quick overview for working with the SfDataGrid for Xamarin.Forms. Walk through the entire process of creating a real world of this control.

Assembly deployment

After installing Essential Studio for Xamarin, find all the required assemblies in the installation folders {Syncfusion Essential Studio Installed location}\Essential Studio\16.3.0.29\Xamarin\lib.

Eg: C:\Program Files (x86)\Syncfusion\Essential Studio\16.3.0.29\Xamarin\lib.

NOTE

Assemblies can be found in an unzipped package location in Mac.

NuGet configuration

To install the required NuGet for the SfDataGrid control in the application, configure the NuGet packages of the Syncfusion components.

Refer to the following KB to configure the NuGet packages of the Syncfusion components:

How to configure package source and install Syncfusion NuGet packages in an existing project?

The following NuGet package should be installed to use the SfDataGrid control in the application.

Project Required package
Xamarin.Forms Syncfusion.Xamarin.SfDataGrid

Adding SfDataGrid Reference

Syncfusion Xamarin components are available in nuget.org. To add SfDataGrid to your project, open the NuGet package manager in Visual Studio, and search for Syncfusion.Xamarin.SfDataGrid, and then install it.

Configure DataGrid using NuGet package

To know more about obtaining our components, refer to these links: Mac and Windows. Also, if you prefer to manually refer the assemblies instead of NuGet, refer to this link to know about the dependent assemblies for SfDataGrid.

To export the SfDataGrid to Excel and PDF formats, search for Syncfusion.Xamarin.SfGridConverter in the NuGet package manager, and then install it.

Configure DataGrid with exporting functionalities using NuGet

If you prefer to manually refer the assemblies instead of NuGet for the using the exporting functionalities of SfDataGrid, refer to this link to know about the dependent assemblies for exporting SfDataGrid.

IMPORTANT

Starting with v16.2.0.x, if you reference Syncfusion assemblies from trial setup or from the NuGet feed, you also have to include a license key in your projects. Please refer to this link to know about registering Syncfusion license key in your Xamarin application to use our components.

NOTE

When there is a mismatch of Xamarin NuGet packages between the sample and the SfDataGrid assemblies, an error Could not load type Xamarin.Forms.ElementTemplate will occur. Refer to the ReadMe to know the software requirements of the Syncfusion controls.

NOTE

When there is a mismatch between the Syncfusion NuGet packages among the projects, System.IO.FileLoadException will occur. To overcome this exception, install the same version of the SfDataGrid assemblies in all the projects.

Launching the SfDataGrid on each platform

To use the SfDataGrid inside an application, each platform application must initialize the SfDataGrid renderer. This initialization step varies from platform to platform and is discussed in the following sections:

Android

The Android launches the SfDataGrid without any initialization and is enough to only initialize the Xamarin.Forms Framework to launch the application.

iOS

To launch the SfDataGrid in iOS, call the SfDataGridRenderer.Init() in the FinishedLaunching overridden method of the AppDelegate class after the Xamarin.Forms Framework initialization and before the LoadApplication is called as demonstrated in the following code example:

  • c#
  • public override bool FinishedLaunching(UIApplication app, NSDictionary options)
    {
        
        global::Xamarin.Forms.Forms.Init ();
        Syncfusion.SfDataGrid.XForms.iOS.SfDataGridRenderer.Init();
        LoadApplication (new App ());
        
    }

    Universal Windows Platform (UWP)

    To launch the SfDataGrid in UWP, call the SfDataGridRenderer.Init() in the MainPage constructor before the LoadApplication is called as demonstrated in the following code example.

  • c#
  • public MainPage()
    {
        
        Syncfusion.SfDataGrid.XForms.UWP.SfDataGridRenderer.Init();
        LoadApplication (new App ());
        
    }

    Release mode issue in UWP platform

    The known Framework issue in UWP platform is the custom controls will not render when deployed the application in Release Mode. It can be resolved by initializing the SfDataGrid assemblies in App.xaml.cs in UWP project as in the following code snippet.

  • c#
  • // In App.xaml.cs
    
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        
    
        rootFrame.NavigationFailed += OnNavigationFailed;
            
        // you should add `using System.Reflection;`
        List<Assembly> assembliesToInclude = new List<Assembly>();
    
        //Now, add all the assemblies your app uses
        assembliesToInclude.Add(typeof(Syncfusion.SfDataGrid.XForms.UWP.SfDataGridRenderer).GetTypeInfo().Assembly);
        assembliesToInclude.Add(typeof(Syncfusion.SfNumericTextBox.XForms.UWP.SfNumericTextBoxRenderer).GetTypeInfo().Assembly);
    
        // replaces Xamarin.Forms.Forms.Init(e);        
        Xamarin.Forms.Forms.Init(e, assembliesToInclude);
            
             
    }

    Create a simple SfDataGrid

    This section explains how to create a SfDataGrid and configure it. The SfDataGrid control can be configured entirely in C# code or using XAML markup. This is how the final output will look like on iOS, Android, and Windows Phone devices.

    A simple DataGrid

    You can download the entire source code of this demo for Xamarin.Forms from here.

    In this walk through, a new application can be created that contains the SfDataGrid which includes the following topics:

    Creating the project

    Create a new BlankApp (Xamarin.Forms.Portable) application in Xamarin Studio or Visual Studio for Xamarin.Forms.

    Adding SfDataGrid in Xamarin.Forms

    1. Add the required assembly references to the pcl and renderer projects as discussed in the Assembly deployment section.

    2. Import the SfDataGrid control namespace as xmlns:syncfusion="clr-namespace:Syncfusion.SfDataGrid.XForms;assembly=Syncfusion.SfDataGrid.XForms in XAML Page.

    3. Set the SfDataGrid control as content to the ContentPage.

    <?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:GettingStarted;assembly=GettingStarted"
                 xmlns:syncfusion="clr-namespace:Syncfusion.SfDataGrid.XForms;assembly=Syncfusion.SfDataGrid.XForms" 
                 x:Class="GettingStarted.Sample">
    
        <ContentPage.Content>
            <syncfusion:SfDataGrid x:Name="dataGrid" />
        </ContentPage.Content>
    </ContentPage>
    using Syncfusion.SfDataGrid.XForms;
    using Xamarin.Forms;
    
    namespace GettingStarted
    {
        public class App : Application
        {
            SfDataGrid dataGrid;
            public App()
            {
                dataGrid = new SfDataGrid();
                MainPage = new ContentPage { Content = dataGrid };
            }
        }
    }

    Create DataModel for the SfDataGrid

    The SfDataGrid is a data-bound control. Hence, a data model should be created to bind it to the control.

    Create a simple data source as shown in the following code example in a new class file. Save it as OrderInfo.cs file:

  • c#
  • public class OrderInfo
    {
        private int orderID;
        private string customerID;
        private string customer;
        private string shipCity;
        private string shipCountry;
    
        public int OrderID {
            get { return orderID; }
            set { this.orderID = value; }
        }
    
        public string CustomerID {
            get { return customerID; }
            set { this.customerID = value; }
        }
    
        public string ShipCountry {
            get { return shipCountry; }
            set { this.shipCountry = value; }
        }
    
        public string Customer {
            get { return this.customer; }
            set { this.customer = value; }
        }
    
        public string ShipCity {
            get { return shipCity; }
            set { this.shipCity = value; }
        }
    
        public OrderInfo (int orderId, string customerId, string country, string customer, string shipCity)
        {
            this.OrderID = orderId;
            this.CustomerID = customerId;
            this.Customer = customer;
            this.ShipCountry = country;
            this.ShipCity = shipCity;
        }
    }

    NOTE

    If you want your data model to respond to property changes, implement INotifyPropertyChanged interface in your model class.

    Create a model repository class with OrderInfo collection property initialized with required number of data objects in a new class file as shown in the following code example and save it as OrderInfoRepository.cs file:

  • c#
  • public class OrderInfoRepository
    {
        private ObservableCollection<OrderInfo> orderInfo;
        public ObservableCollection<OrderInfo> OrderInfoCollection {
            get { return orderInfo; }
            set { this.orderInfo = value; }
        }
    
        public OrderInfoRepository ()
        {
            orderInfo = new ObservableCollection<OrderInfo> ();
            this.GenerateOrders ();
        }
    
        private void GenerateOrders ()
        {
            orderInfo.Add (new OrderInfo (1001, "Maria Anders", "Germany", "ALFKI", "Berlin"));
            orderInfo.Add (new OrderInfo (1002, "Ana Trujillo", "Mexico", "ANATR", "Mexico D.F."));
            orderInfo.Add (new OrderInfo (1003, "Ant Fuller", "Mexico", "ANTON", "Mexico D.F."));
            orderInfo.Add (new OrderInfo (1004, "Thomas Hardy", "UK", "AROUT", "London"));
            orderInfo.Add (new OrderInfo (1005, "Tim Adams", "Sweden", "BERGS", "London"));
            orderInfo.Add (new OrderInfo (1006, "Hanna Moos", "Germany", "BLAUS", "Mannheim"));
            orderInfo.Add (new OrderInfo (1007, "Andrew Fuller", "France", "BLONP", "Strasbourg"));
            orderInfo.Add (new OrderInfo (1008, "Martin King", "Spain", "BOLID", "Madrid"));
            orderInfo.Add (new OrderInfo (1009, "Lenny Lin", "France", "BONAP", "Marsiella"));
            orderInfo.Add (new OrderInfo (1010, "John Carter", "Canada", "BOTTM", "Lenny Lin"));
            orderInfo.Add (new OrderInfo (1011, "Laura King", "UK", "AROUT", "London"));
            orderInfo.Add (new OrderInfo (1012, "Anne Wilson", "Germany", "BLAUS", "Mannheim"));
            orderInfo.Add (new OrderInfo (1013, "Martin King", "France", "BLONP", "Strasbourg"));
            orderInfo.Add (new OrderInfo (1014, "Gina Irene", "UK", "AROUT", "London"));
        }
    }

    Binding data to the SfDataGrid

    To bind the data source to the SfDataGrid, set the SfDataGrid.ItemsSource property as follows. You can bind the data source of the SfDataGrid either from XAML or in code.

    The following code example binds the collection created in previous step to SfDataGrid.ItemsSource property.

    <?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:GettingStarted;assembly=GettingStarted"
                 xmlns:syncfusion="clr-namespace:Syncfusion.SfDataGrid.XForms;assembly=Syncfusion.SfDataGrid.XForms" 
                 x:Class="GettingStarted.Sample">
    
        <ContentPage.BindingContext>
            <local:OrderInfoRepository x:Name="viewModel" />
        </ContentPage.BindingContext>
    
        <ContentPage.Content>
            <syncfusion:SfDataGrid x:Name="dataGrid"
                                   ItemsSource="{Binding OrderInfoCollection}">
            </syncfusion:SfDataGrid>
        </ContentPage.Content>
    </ContentPage>
    OrderInfoRepository viewModel = new OrderInfoRepository ();
    dataGrid.ItemsSource = viewModel.OrderInfoCollection;

    Run the application to render the following output.

    DataGrid with default appearance

    Defining columns

    By default, the SfDataGrid automatically creates columns for all the properties in the data source. The type of the column generated depends on the type of data in the column. When the columns are auto-generated, handle the SfDataGrid.AutoGeneratingColumn event to customize or cancel the columns before they are added to the columns collection in the SfDataGrid.

    The columns can be manually defined by setting the SfDataGrid.AutoGenerateColumns property to false and by adding the GridColumn objects to the SfDataGrid.Columns collection. It can be done from both XAML and code. The following code example illustrates this:

    <syncfusion:SfDataGrid x:Name="dataGrid"
                ColumnSizer="Star"
                AutoGenerateColumns="False"
                ItemsSource="{Binding OrderInfoCollection}">
    
        <syncfusion:SfDataGrid.Columns x:TypeArguments="syncfusion:Columns">
            <syncfusion:GridTextColumn HeaderText="Order ID" 
                                       MappingName="OrderID" />
            <syncfusion:GridTextColumn HeaderText="Customer ID"
                                       MappingName="CustomerID" />
            <syncfusion:GridTextColumn MappingName="Customer" />
            <syncfusion:GridTextColumn HeaderText="Ship Country"
                                       MappingName="ShipCountry" />
        </syncfusion:SfDataGrid.Columns>
    </syncfusion:SfDataGrid>
    dataGrid.AutoGenerateColumns = false;
    
    GridTextColumn orderIdColumn = new GridTextColumn ();
    orderIdColumn.MappingName = "OrderID";
    orderIdColumn.HeaderText = "Order ID";
    
    GridTextColumn customerIdColumn = new GridTextColumn ();
    customerIdColumn.MappingName = "CustomerID";
    customerIdColumn.HeaderText = "Customer ID";
    
    GridTextColumn customerColumn = new GridTextColumn ();
    customerColumn.MappingName = "Customer";
    customerColumn.HeaderText = "Customer";
    
    GridTextColumn countryColumn = new GridTextColumn ();
    countryColumn.MappingName = "ShipCountry";
    countryColumn.HeaderText = "Ship Country";
    
    dataGrid.Columns.Add (orderIdColumn);
    dataGrid.Columns.Add (customerIdColumn);
    dataGrid.Columns.Add (customerColumn);
    dataGrid.Columns.Add (countryColumn);

    Sorting

    The SfDataGrid allows sorting on its data by setting the SfDataGrid.AllowSorting property to true.

    <syncfusion:SfDataGrid AllowSorting="True" />
    dataGrid.AllowSorting = true;

    Run the application and touch the header cell to sort the data and the following output will be displayed.

    DataGrid with sorting applied

    Sorting can also be configured by adding the column to the SfDataGrid.SortColumnDescriptions collection as follows.

    <syncfusion:SfDataGrid.SortColumnDescriptions>
        <syncfusion:SortColumnDescription ColumnName="CustomerID" />
    </syncfusion:SfDataGrid.SortColumnDescriptions>
    dataGrid.SortColumnDescriptions.Add (new SortColumnDescription () { ColumnName = "CustomerID" });

    Grouping

    The SfDataGrid allows grouping a column by adding the column to the SfDataGrid.GroupColumnDescriptions collection as follows.

    <syncfusion:SfDataGrid.GroupColumnDescriptions>
        <syncfusion:GroupColumnDescription ColumnName="ShipCountry" />
    </syncfusion:SfDataGrid.GroupColumnDescriptions>
    dataGrid.GroupColumnDescriptions.Add (new GroupColumnDescription () { ColumnName = "ShipCountry" });

    Run the application to render the following output.

    DataGrid with grouping applied

    Selection

    The SfDataGrid allows selecting the row or rows by setting the SfDataGrid.SelectionMode property. You can set the SfDataGrid.SelectionMode property to single, multiple, single deselect, or none. Information about the row or rows selected can be tracked using the SfDataGrid.SelectedItem and SfDataGrid.SelectedItems properties.

    The selection operations can be handled with the help of the SelectionChanging and SelectionChanged events of the SfDataGrid.

    Launching the SfDataGrid inside a StackLayout

    The StackLayout positions the child element one after the other. They are adding either horizontally or vertically. Space of the StackLayout depends on the HorizontalOptions and VerticalOptions properties are set. But by default, the StackLayout will try to use the entire screen.

    The SfDataGrid control can be loaded inside any layout such as Grid, StackLayout, etc., When loading SfDataGrid inside a StackLayout, set the Horizontal and/or VerticalOptions of the SfDataGrid and its parent to “LayoutOptions.FillAndExpand” based on the orientation of the container in which the SfDataGrid is loaded.

    Refer to the following code example to load the SfDataGrid control inside a StackLayout. The VerticalOptions of the StackLayout and the SfDataGrid alone is set as “FillAndExpand” as the default orientation of the StackLayout is vertical.

    <ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
                 xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                 xmlns:local="clr-namespace:GridInForms"
                 xmlns:sfgrid="clr-namespace:Syncfusion.SfDataGrid.XForms;assembly=Syncfusion.SfDataGrid.XForms"
                 x:Class="GridInForms.MainPage">
      <ContentPage.BindingContext>
        <local:ViewModel x:Name="viewModel"/>
      </ContentPage.BindingContext>
      <ContentPage.Content>
        <StackLayout VerticalOptions="FillAndExpand">
            <SearchBar Placeholder="UserName" TextChanged="searchBar_TextChanged" />
            <sfgrid:SfDataGrid x:Name="dataGrid"
                           ColumnSizer="Star"
                           ItemsSource="{Binding OrderInfoCollection}"
                           VerticalOptions="FillAndExpand" />
        </StackLayout>
      </ContentPage.Content>
    </ContentPage>
    namespace GettingStarted
    {
        public partial class MainPage : ContentPage
        {
            private StackLayout stackLayout;
            private SfDataGrid dataGrid;
            private ViewModel viewModel;
            private SearchBar searchBar;
            public MainPage()
            {
                InitializeComponent();
                stackLayout = new StackLayout();
                dataGrid = new SfDataGrid();
                viewModel = new ViewModel();
                searchBar = new SearchBar();
                searchBar.Placeholder = "UserName";
                dataGrid.ItemsSource = viewModel.OrdersInfo;
                dataGrid.ColumnSizer = ColumnSizer.Star;
                stackLayout.VerticalOptions = LayoutOptions.FillAndExpand;
                stackLayout.HorizontalOptions = LayoutOptions.FillAndExpand;
                stackLayout.Children.Add(searchBar);
                stackLayout.Children.Add(dataGrid);
                this.Content = stackLayout;
            }
        }
    }

    Refer to the following screenshot for the outcome.

    DataGrid inside a StackLayout

    NOTE

    In case, if the orientation of the StackLayout is horizontal, set the HorizontalOptions instead. In some cases, set both the “VerticalOptions” and “HorizontalOptions” of the SfDataGrid based on its parent.

    Loading the SfDataGrid with customized height and width

    The SfDataGrid can be load with specific height and width inside different layouts using the SfDataGrid.HeightRequest and SfDataGrid.WidthRequest properties.

    The following code example illustrates how this can be done.

    <ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
                 xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                 xmlns:local="clr-namespace:GridInForms"
                 x:Class="GridInForms.MainPage"
                 xmlns:sfgrid="clr-namespace:Syncfusion.SfDataGrid.XForms;assembly=Syncfusion.SfDataGrid.XForms" >
    
        <ContentPage.BindingContext>
            <local:ViewModel x:Name="viewModel"/>
        </ContentPage.BindingContext>
        
            <sfgrid:SfDataGrid x:Name="dataGrid"
                               ItemsSource="{Binding OrdersInfo}"
                               HeightRequest="290"
                               WidthRequest="200"
                               VerticalOptions="CenterAndExpand"
                               HorizontalOptions="Center"/>
        
    </ContentPage>
    public MainPage()
    {
        InitializeComponent();
        viewModel = new ViewModel();
        dataGrid = new SfDataGrid();
        dataGrid.ItemsSource = viewModel.OrdersInfo;
        dataGrid.HeightRequest = 290;
        dataGrid.WidthRequest = 200;
        dataGrid.VerticalOptions = LayoutOptions.CenterAndExpand;
        dataGrid.HorizontalOptions = LayoutOptions.Center;
        this.Content = dataGrid;
    }

    The following screenshot shows how the SfDataGrid is loaded with specific height and width with VerticalOptions and HorizontalOptions.

    DataGrid with customized height and width

    NOTE

    Set the HorizontalOptions and VerticalOptions for the grid accordingly.

    Linker issue in Xamarin.Forms.iOS

    There are some known Framework issues in Xamarin.Forms.iOS platform.

    When creating the SfDataGrid in Xamarin.Forms with Linker behavior in iOS renderer project as “Link Framework SDKs only”, sometimes System.MethodMissingException or No method Count exists on type System.Linq.Queryable exception will be thrown.

    The above exceptions can be resolved by using the following workaround:

    Workaround:

    The above exceptions can be resolved in two ways.

    1. By setting LinkerBehavior as “Do not Link”.
    2. By setting custom linker argument in iOS renderer project as in the following screenshot.

    DataGrid with linker settings