Skip to end of metadata
Go to start of metadata

In this tutorial, you'll learn how to create a simple CRM app that fetches data from WebAPI with the help of AppFramework and creating shared domain models between the server and the client. You will also be able to add, delete or edit customers with Floating Action Buttons as well swipe gestures. At the end of this tutorial, you should have the following result:

Prerequisite

Before starting the walkthrough, it is recommended that you have followed these walkthroughs in order:

It is also recommended that you have read through these conceptual topics in order to get a better understanding:

To use this walkthrough, you will need to use at least Crosslight version 5.0.5000.538 in order to achieve the desired result. You'll also need to have installed Visual Studio 2012 or higher with Mobile Studio properly installed.

Let's get started. 

Preparing the Project

First, create a Blank Crosslight app using Crosslight Project Wizard. Set the project name as SimpleCRM. 

Creating WebApi and DomainModels Project

Next, we're going to create the shared domain models that can be used for both the client and the server. In this tutorial we will use MDF as well as the LDF files from SimpleCRM sample that you can download from this link: http://git.intersoftsolutions.com/projects/CS/repos/app-simplecrm/browse/SimpleCRM.WebApi/App_Data. Download all 4 files. We're going to create the models from these MDF files with the help of WebAPI EDM Extensions which is pre-installed to your Visual Studio once you've successfully installed Mobile Studio. Follow these steps in order. 

Adding New WebAPI Project

To add a new WebAPI project, right-click on your solution and select Add, New Project.

In the next dialog that appears, choose ASP.NET Web Application.

Add a new WebApi project to your solution and name it SimpleCRM.WebApi. In the next dialog, choose Web API.

Copy over CrosslightDb.mdf as well as CrosslightDb_log.ldf from the files you've downloaded earlier into the SimpleCRM.WebApi/App_Data folder.

Adding DomainModels Project

Next, we're going to add the DomainModels project that will hold the shared models between the server and the client. Right-click on your solution, choose Add, New Project. From the dialog that appears, choose Intersoft Crosslight Domain Models project under Intersoft Solutions, Mobile. Give the project the name SimpleCRM.DomainModels. Click OK.

In the next dialog choose, ADO.NET Entity Data Model and give it a name of SimpleCRMModel.

In the next dialog, configure the connection to your imported CrosslightDb.mdf file.

In the next screen, you'll be prompted to choose the EntityFramework version you would like to use. Choose Entity Framework 5.0.

Select all tables when prompted to choose your database objects.

Hit Finish.

Your EDMX is now ready. Now we're going to take advantage of the Intersoft WebAPI EDM Extension to generate the shared models. With the EDMX file still in focus, press F4 on your keyboard. When the Properties tab is opened, set the Intersoft WebAPI Enabled to True and Code Generation Version to V4.

Save the EDMX file. You may be prompted several times for the code generator template to start generating the domain models. Hit OK on all dialogs that appear. Your entity data model, model, repository and controller will be generated automatically. If you not familiar with the concept of domain models and repository, check out this article: Design Pattern Overview.

Preparing NuGet Packages

Before we can start working with the project, we'll need to fix the Crosslight references first. Follow these steps to properly configure your project with Crosslight NuGet packages. On your solution, perform right-click, then choose Manage Package for Solution.

In the next dialog that appears, search for Intersoft.Crosslight and install/update them to all of your projects.

Next, install/update Intersoft.Crosslight.Android.v7 NuGet package and install it onto the SimpleCRM.Android project.

Next, install Intersoft.AppFramework to all of your projects.

Next, install Intersoft.Data.WebApi.v4 to SimpleCRM.WebApi project.

Next, install Intersoft.Crosslight.Service.ImageLoader to SimpleCRM.Core project.

Lastly, install Microsoft.BCL.Async to SimpleCRM.Core project.

Testing WebApi Controller

Before we proceed, it is recommended to test our WebApi controller to ensure everything works correctly. But first, you need to configure the following files in the WebApi project as follows.

Modify WebApiConfig.cs in App_Start folder to looks like the following. This will configure the URL routing for our WebAPI server to use the pattern: data/{controller}/{action}.

Next, open Global.asax.cs and use the following code. This will register the required initializers, routings and services for your WebAPI application.

Then, open applicationhost.config inside .vs/config (this is a hidden folder, you might need to show all files from Windows Explorer). Add the following bindings to applicationhost.config in the your website node.

The binding above is required so that your WebApi is accessible from your local network. You might also need to disable Windows Firewall to ensure that the WebApi controller is accessible from your local network. To test WebApi controller, right click at controllers folders, and select View in Browser. Then change localhost to your ip address. To access controllers, use this format:

{IPAddress}:port/data/{ControllerClassName}/{ControllerMethodsName}. For example : http://192.168.10.30:19119/data/CrosslightDb/Customers.

To find your IP address and the port of your WebApi server, simply run the WebApi server on your local machine in a separate VS instance. 

Congratulations, you've successfully created the WebApi server for your application.

Preparing Images in WebApi

In this sample, we will use some images as customer photos to be displayed in a list. Follow these steps to prepare the images in the WebApi project. Add the code inside CrosslightDbController class in SimpleCRM.WebApi/Controllers folder:

Then create a new class, called CRMController.Partial.cs inside the SimpleCRM.WebApi/Controllers folder: This will allow for images to be saved later during add/edit operation.

CRMController.Partial.cs

Create a new folder called images folder inside the SimpleCRM.WebApi project. Download and extract this file inside the newly created folder. Your final project structure should look like this:

  • SimpleCRM.WebApi
    • images

Don't forget to all files's BuildAction to EmbeddedResource in the Properties pane, also ensure that you can have the write permission enabled to the folder, or else, the images cannot be saved.

Configuring App Service

Next, we'll want to modify the AppService.cs file to include various settings needed for this application. Open up AppService.cs file inside SimpleCRM.Core/Infrastructure folder and use the following code.

The above code contains additional services that are needed for this sample to work properly, such as the RestClient, repositories and the additional services.

Creating List Page

Let's begin creating the customer list page. Follow these steps. Create a new empty class called CustomerQueryDefinition.cs inside SimpleCRM.Core/Models folder. This QueryDefinition will define how the list will be sorted when it first loads. As seen in the code below, when the list loads, it will be sorted based on the customer's FirstName. The Includes allows for additional nested properties to be accessed when obtaining the CustomerAddress. The AddFilter method adds the filters whenever search is executed.

CustomerQueryDefinition.cs

Next, create a new empty class called Customer.Partial.cs inside SimpleCRM.Core/DomainModels folder and use the following code. This is just a simple partial class for the Customer class. The IgnoreDataMemberAttribute tells the JSON serializer to skip the marked properties when it is sent over the wire.

Customer.Partial.cs

Then, create a new file called CustomerAddress.Partial.cs inside SimpleCRM.Core/DomainModels folder and use the following code. The following class simply provides a better experience when editing the customer. When the CountryId is changed, the City property is automatically nulled since it won't be valid anymore whenever the Country is changed.

CustomerAddress.Partial.cs

After we've finished creating the models, let's proceed by creating the ViewModel inside the Core project. Create a new Crosslight Data List View Model class and give it a name of CustomerListViewModel.cs and put it inside SimpleCRM.Core/ViewModels folder. This class contains nothing except for the Title which will be displayed when the screen loads, as well as providing the previously created FilterQuery and ViewQuery for this screen.

CustomerListViewModel.cs

Now that you have the ViewModel ready, let's proceed by creating a new BindingProvider called CustomerListBindingProvider.cs inside the SimpleCRM.Core/BindingProviders folder. Here, we bind the list with the ID TableView to the corresponding properties in the ViewModel. The built-in list views in Crosslight are automatically given a name of TableView

CustomerListBindingProviders.cs

Open up AppService.cs inside SimpleCRM.Core/Infrastructure folder and change the RootViewModel to CustomerListViewModel.

Now that we've finished preparing the Core section, let's move on by creating the Android view counterpart to display these list of customers.

Preparing the Android Project

To begin with, create a new AppActivity.cs inside the SimpleCRM.Android project and use the following code. This will be needed as the main container for the first view.

AppActivity.cs

Next, create a new Crosslight Material RecyclerView Fragment inside SimpleCRM.Android/Fragments folder. Use the following code. Here, we simply provided the RecyclerViewFragment to display the list of customers. 

CustomerListFragment.cs

Next, copy the following item_placeholder.png file inside the SimpleCRM.Android/Resources/Drawable folder.

Run the project, and you should get the following result.

 

Enabling Pull to Refresh

To enable pull to refresh, simply provide this code to CustomerListViewModel constructor:

After that you can refresh the list by performing a pull gesture to the list view.

Enabling Incremental Loading

To enable incremental loading, simply add set the EnableIncrementalLoading property and provide the IncrementalLoadingSize to CustomerListViewModel's constructor:

CustomerListViewModel.cs

This will limit the file size query to 20 items per page, which will considerably reduce the loading time and data payload if the number of items is large.

Enabling Search

Follow these steps to enable search. Change the parent class for CustomerListFragment from RecyclerViewFragment to SearchableRecyclerViewFragment. Then, add this code to Initialize methods of CustomerListFragment.

Then, add the following methods to CustomerListViewModel.

Run the application and now you can search the customers based on their names.

Adding and Updating Data

Now that you've successfully enabled search on Recycler View Fragment, follow these steps to add and update data. Create a new empty class named CityQueryDefinition.cs in SimpleCRM.Core/Models folder and use the following code.

Next, add CustomerFormMetadata.cs in Simple.CRM/Models folder and use the following code. This will be used as the form metadata (Crosslight Form Builder) for the Add/Edit screen.

Next, add a new Crosslight Data List View Model named CityListViewModel.cs inside SimpleCRM.Core/ViewModels folder.

Next, add another Crosslight Data List View Model named CountryListViewModel inside SimpleCRM.Core/ViewModels folder.

Next, add a new Crosslight Data Detail View Model named CustomerDetailViewModel inside SimpleCRM.Core/ViewModels folder.

Let's provide the editor view model for editing the customer. Create a new Crosslight Data Editor View Model inside SimpleCRM.Core/ViewModels folder called CustomerEditorViewModel.

To provide the add functionality in the list, add this method in CustomerListViewModel.

 

Next, add a new empty class called CustomerRepostiory.partial.cs inside SimpleCRM.Core/Models folder.

Add the following code to CustomerListBindingProvider inside SimpleCRM.Core/BindingProviders folder.

Add a new Crosslight Binding Provider file inside SimpleCRM.Core/BindingProviders and name it CustomerDetailBindingProvider.cs.

Next, add a new layout inside SimpleCRM.Android/Resources/layout folder called view_image_layout.axml. The layout simply contains a TextView to show the customer's name as well as an ImageView to show the customer's photo.

Then add a new Crosslight Material Fragment called ViewImageFragment. This is just a Fragment that will be used to display the customer's photo when we tap on View Larger Image button in the FormFragment.

Add a new Crosslight Material Form Fragment called CustomerEditFragment inside SimpleCRM.Android/Fragments folder. The FormFragment contains nothing except for the Save button which we've placed as the bar items.

Add the following code to the Initialize method in CustomerListFragment inside SimpleCRM.Android/Fragments folder. This will add the Floating Action Button to your fragment which will allow you to add a new customer.

Now you should be able to add and edit the list of customers.

Deleting Data

Now you've successfully enabled add and edit data to your customer list. Let's proceed by adding the delete functionality. Add this code to CustomerListBindingProvider inside SimpleCRM.Core/BindingProviders folder.

Then, in the Initialize method in CustomerListFragment, add the following code.

Now you can delete any customers by performing long-click on a list.

Using Swipe Gesture for Additional Editing Actions

In this section, we're going to learn how to add swipe gestures to enable additional editing actions. Follow these steps to enable swipe gestures. Open up CustomerListFragment.cs inside SimpleCRM.Android/Fragments folder and add the following code to the Initialize method.

Then, open up CustomerListBindingProvider.cs inside SimpleCRM.Android/Fragments folder and add the following code.

Lastly, add this method inside CustomerListViewModel.cs inside SimpleCRM.Core/ViewModels folder.

The following image shows the result after you've run the project.

 

Preparing the iOS Project

Now that you've finished the Android project, let's move on to the iOS project. Basically, all you have to do is just prepare the views for the iOS project, since you've prepared the Core project with all the ViewModels and BindingProviders. Begin by creating a new Crosslight iOS Table View Controller for iPhone, give it a name of CustomerListViewController.cs. Use the following code.

From the code above, we've configured how our table view should look like and we've also configured the Toolbar, Footer as well as registering the necessary views. If you run the project now you should get the following result.

Swipe gestures should work as well.

Next, create a new Crosslight Form View Controller, give it a name of CustomerEditViewController. This ViewController will act as the add/edit view when adding/editing a customer. Use the following code.

Now you should be able to add/edit a customer, shown in the following shot.

Lastly, we're going to create a simple Crosslight View Controller for iPhone. Give it a name of PhotoDetailViewController. Use the following code.

Then, move the PhotoDetailViewController.xib to the Views folder. Open the file in Xcode Interface Builder. Provide the following layout.

Give the Label an outlet called NameLabel and the ImageView an outlet called ImageView. When run, you should get the following result.

Conclusion

Congratulations! You already learn how to create a simple, yet full-fledged CRM application that fetches data from WebApi controller complete with CRUD functionalities and swipe gestures.

Sample

You can also find the resulting sample here: SimpleCRM.zip . Simply open this sample with Xamarin Studio or Visual Studio and run the project.