Creating a Simple iOS Client for Relativity Server

Today I want to talk about how to create a simple iPhone client application for Relativity server using the DataAbstract for Xcode templates. Though the focus will be on Xcode 4, the same mechanisms can be applied to Xcode 3.

Going through a set of actions, we will use a DataAbstract iOS Application template to create an application with several views representing a Master/Detail relation.

Let’s start with the first step.

Creating a new project using a DataAbstract iOS Application template

Open your Xcode application and perform the File>New>New project… command.
In the opened sheet, choose the RemObjects Software category from the iOS templates section and select the Data Abstract iOS Application template.

[](http://blogs.remobjects.com/wp-content/uploads/2011/09/1.-iOS-client-for-Relativity.-Choosing-template.png)Specify the product name and don’t forget to set the *Talk to Relativity Server* option. [](http://blogs.remobjects.com/wp-content/uploads/2011/09/2.-iOS-client-for-Relativity.-Configuring-template.png)Finally, select the destination folder for your new project and press the Create button. Your new project should now be open: [](http://blogs.remobjects.com/wp-content/uploads/2011/09/3.-iOS-client-for-Relativity.-Just-created-project.png)Let’s take a few seconds to review what you have at the moment. You should have a compilable application (with some warnings – we will review them a bit later) that has an *AppDelegate* class and a *RootViewController* with its **xib**. There should also be a *DataAccess* class, which will be responsible for all manipulation with data. The new project also has all the necessary linker flags and properly configured paths as shown in the screen-shot below: [](http://blogs.remobjects.com/wp-content/uploads/2011/09/4.-iOS-client-for-Relativity.-Build-settings.png)Implementation of the iOS client

Now you can compile the application, after which you will see a set of warnings:

[](http://blogs.remobjects.com/wp-content/uploads/2011/09/6.-iOS-client-for-Relativity.-Warnings.png)These warnings were generated by the template system to highlight places that require adjusting or proper implementation to get your application working. Let’s walk through all of them and eliminate them one by one.

1. Adjusting the connection configuration

First, let’s change some defaults in the generated DataAccess class to specify the Relativity server URL, domain and schema. For this example, let’s assume that you have the Relativity server running on a Windows computer with the IP 192.168.0.150.

Open the DataAccess.m file and specify the proper URL for the Relativity server, domain and schema.
You can comment the warning there, since we are done with it (as shown below).

2. Defining tables you want to work with

Since the DataAccess class encapsulates all functionality needed for working with data, you need to define your tables there. Let’s define them as retain properties. See the code below:

Don’t forget to add the proper *@syntesize* directive and release the properties in the *dealloc* method in the *DataAccess.m* file. 3. Implementing the initial loading of data

Now let’s implement the method for the initial loading of data from the Relativity server.
Locate the downloadData method of the DataAccess class and add the following code:

**Note: **Our templates contain various vital tips and explanations on how to use a particular method. Please carefully review this kind of information, it can be very useful.

**Note **that we used a synchronous call to *getDataTables* here, because the whole *downloadData* method will be executed in a background thread (i.e. asynchronously).

4. Adding briefcase support to your application

In order to allow your application to work in offline mode, you need to persist downloaded data somewhere on the device. Let’s use the DABriefcase functionality for this.
Locate the loadDataFromBriefcase: and saveDataToBriefcase: methods in the DataAccess class and implement them as shown below:

5. Extending the Orders table with lookup and calculated fields

Let’s look at the orders table structure. It only has a minimal set of the fields like id, client id, date and status. That’s not a lot and it would be be great to see (for example) the customer name instead of its ID and the total sum for the given order (which could be calculated from the OrderDetails table). Toachieve this, you’ll have to add lookup and calculated fields to the Orders table. Locate the setupData method of the DataAccess class and add the following implementation:

6. Checking the login and password stuff in your Application delegate

Relativity server provides secured services protected by login and password. Thus, when asking for data the first time, a SessionNotFound exception will be raised on the Relativity side to tells you that you need to login to the Relativity domain first. When you log in to it, it will be able to find your registered session and allow you to proceed. The iOS client application can catch this kind of exception and provide a login operation in the background, and, after successful login, it will repeat the last failed request. When you open the PCTradeClientAppDelegate.h file you will see that this class supports the DataAccessDelegate protocol, which has a needLogin:password: method that will be used for obtaining the proper login and password.
Since you are mostly using default settings, you can leave the already generated method untouched. It should look like this:

7. Implementing the RootViewController

You can now configure the root view to show the list of clients:

Open the RootViewController.m file and locate the myTable method that specifies the main data table for the whole current view. Since the default name myTable is a bit nondescript, let’s use the Refactoring>Rename option to rename it viewData.
Now add the following implementation:

Also, let’s give the root view a more meaningful title. By default, the root view is called “Root View”. Let’s change it to something more appropriate: Add a string define with the title and use it in the viewDidLoad method as shown below: Now you can compile the project and see the results in the iPhone simulator; it should look something like this: [](http://blogs.remobjects.com/wp-content/uploads/2011/09/5.-iOS-client-for-Relativity.-First-draft-application.png)8. Adding a detail view “Orders”

As next step, let’s implement the detail view that will show orders for each particular client.
First, add a new UITableViewController class with its xib file.

[](http://blogs.remobjects.com/wp-content/uploads/2011/09/7.-iOS-client-for-Relativity.-Add-Orders-view-controller.png)Make sure that your controller is based on the *UITableViewController* class. [](http://blogs.remobjects.com/wp-content/uploads/2011/09/8.-iOS-client-for-Relativity.-Add-Orders-view-controller2.png)The controller will take the *DADataTableRow* instance with the client info and then obtain and show a list of orders for the given client.

Our OrdersViewController.h will have something like the following:

9. Obtaining an orders list for a given client

Now you need to hook on the moment when the client row will be set as the clientRow property and obtain the list of orders. Let’s write a custom setter method for this:

Now is a good time for adding the *ordersForClientID:* method inside our *DataAccess* class. Its implementation is rather simple. Since the *DataAccess* already has the whole orders table, your task will be to extract only the orders for the given client. Let’s use NPredicate for this: Finally, let’s implement what you want to expose in the clients list. Locate the method and implement it as shown below: 10. Implementing the data presentation for the orders view

Now let’s form an appropriate representation of the data for each customer order with minimal effort, meaning that we avoid creating custom cells for this table and just use one of predefined styles provided by Apple.

Locate and open the tableView:cellForRowAtIndexPath: method of the OrdersViewController.m file and change it like this:

Here I should note that we used *UITableViewCellStyleValue1* as the cell style, which allows us to compose the main text label with the order date at the left side and the detail label with order total at the right label of the cell. Also please note that the *OrderSum* field is the calculated field you have added earlier.

I propose to improve the cell view for your root view a bit and show the client’s phone as detail information. Locate the tableView:cellForRowAtIndexPath: method in the RootViewController.m file and change it to something like this:

Let’s compile and test our application. It should show the “Our Clients” view with a list of clients, and when you tap on a particular client it will switch to the Orders view which will show orders for the tapped client.

Looks good, doesn’t it? But there’s still one thing to improve: for clients without any orders, it shows an empty orders view. But there is an easy way to change that.

11. Final adjustments.

Let’s define whether the given client has any orders, and if it does, let’s add a disclosure button for this cell, so you will know if there is an orders view to show for the given customer or not.

To do this, let’s add another calculated field to your clientsTable as shown below:

Now, you can analyze this field value and make a decision whether to draw a disclosure button to the cell in the RootViewController. In conclusion, you will need to move the implementation of the loading orders view from *tableView:didSelectRowAtIndexPath: * to *tableView:accessoryButtonTappedForRowWithIndexPath:*. And that’s all. Compile and run the resulting application. You should have something like the following: [](http://blogs.remobjects.com/wp-content/uploads/2011/09/9.-iOS-client-for-Relativity.-Result.png)In my next blog post, I’ll show you how to further improve this application and add the ability to edit and save data.

Thanks