Getting Started: Learn
Work through the iOS tutorial to create the To-Do client app shown below:
This document contains the following sections:
Configure the Akula Server
Before you can complete this tutorial, you must have already configured the Akula Server and the ToDo server app. For more information, see Configuring the Akula Server for the Samples and Tutorials.
iOS SDK system requirements
To develop iOS client apps, your development environment must meet the following system requirements:
- Mac OS
- Xcode 4
- Java JDK 7
Install and configure the iOS tutorial app project
The source code for To-Do Tutorial app ships with the Akula Client SDK for iOS in the Verivo_Akula_SDK_v1.0.0.zip file.
To install the tutorial project:
- Locate the iOS\Samples\ToDo\ToDo Tutorial directory in the location where you unzipped the Verivo_Akula_SDK_v1.0.0.zip file. If you have not done so already, download the Akula Client SDK for iOS from Downloads.
- Copy the ToDo Tutorial directory to a location on your machine where you store your projects.
- Create a directory named frameworks under the ToDo Tutorial directory.
Locate the iOS\Akula.framework directory in the location where you unzipped the Verivo_Akula_SDK_v1.0.0.zip file.
Copy the Akula.framework into your ToDo Tutorial/frameworks folder.
Open the ToDoTutorial.xcodeproj file in Xcode.
In the Project Navigator pane, highlight the project to reveal the project settings.
- Select ToDoTutorial under Targets.
Select the Build Phases tab.
Expand the Link Binary With Libraries section, and select its + button.
In the window that opens, select the Add Other button.
Navigate to your ToDo Tutorial/frameworks folder, and select Akula.framework.
Click the Open button.
- Build the app. It should build without error.
Configure the connection to the Akula Server
To build the iOS client app, you have to edit the source code so that the client app references your Akula Server.
To edit the source code:
- In Xcode, open the ToDoConstants.h file.
Modify the following line to specify the location of the ToDo server app on your Akula Server:
#define kBase_URL @""
For example, if the server is running on your local machine, edit the line as shown below:
#define kBase_URL @""
Don't use localhost to reference the Akula Server. Use the IP address or DNS name of your machine.
- Save your changes and build the app.
The To-Do App project should now build without error (though you might still see warnings but those will be fixed later).
- Run the app. Because you have not added the log in functionality, you can log in with any user name and password.
Add log in functionality to the app
You authenticate users add log in functionality to the app. Users will then be required to log in with a valid username and password to access the app.
To log in, you need to obtain the username and password from the input boxes and represent them as an AKCredentials object. You then submit the credentials to the
method of the AKSession class. You also create asynchronous callback handlers notified when the log in operation succeeds or fails.
When you fill in the username and password fields in the To-Do app, and press the Login button, the
method sends an HTTP POST request containing your credentials to the Akula Server for authentication.
To add log in:
- Open ToDoTutorialDelegate.m.
Insert the code below after "TUTORIAL STEP 1" to initialize the connection to the ToDo app scope:
- Open ToDoLoginViewController.h.
Replace existing interface declaration with the declaration shown below to allow the class to become an AKSessionDelegate:
Open ToDoLoginViewController.m and find the
Insert the code below after "TUTORIAL STEP 1" to call the
loginWithCredentials:delegate:method of the AKSession class to perform the log in:
Scroll to the bottom of the file and insert the
loginSuccess:callback methods used by the
method after "TUTORIAL STEP 2". This method handles a successful log in to navigate to the next screen:
Scroll to the bottom of the file and insert the
loginFailure:callback method used by the
method after "TUTORIAL STEP 3". This methods displays a UIAlertView for a failed log in:
- Run the app.
- Try logging in with an invalid username/password, such as me/me. It should fail.
- Try logging in with a valid username/password, such as penny/penny. It should succeed.
Creating a data request
Create a data request to retrieve data from the backend data source. You use the ToDoAgent class to make the request. ToDoAgent extends the Akula AKServerAgent class to make an HTTP GET request to the Akula Server to retrieve the data.
The AKServerAgent class defines the following methods that you use to communicate with the Akula Server:
get:lets you make an HTTP GET request to the Akula Server to retrieve the list data.
post: lets you make an HTTP POST request to upload a new list item to the server.
put: lets you make an HTTP PUT request to update a list item.
- delete: lets you make an HTTP DELETE request to delete a list item.
To create a data request:
- Open ToDoAgent.m.
Copy the code below to implement each method in this class. In all the methods, the AKJSONHTTPResponseHandler provides the mechanism to respond after the request has finished.
- If you run the app, you won't see any data yet. Complete the next part of the tutorial to display the requested data.
Viewing request data
In this section, you add log out to the app, and display data returned from the Akula Server. The code first creates new models for the items in the list, and then displays the models.
To view request data:
- Open ToDoViewController.m.
getSelectedTaskID:, add the following code under "TUTORIAL STEP 1". Based on a selected row, this code returns a given model object.
reloadList:method, add the following code under "TUTORIAL STEP 2". This code creates an AKJSONHTTPResponseHandler object that takes an NSArray and creates model objects for each index. That handler is passed to the
getTasks: method of the ToDoAgent which is where the request is made.
handleLogout: method. Add the following code under "TUTORIAL STEP 3" and "TUTORIAL STEP 4". This code uses the
logout:method of the AKSession class to perform a synchronous log out request. The
logout:method sends an HTTP DELETE request to the Akula Server to deauthenticates the current user session from the Akula Server. If the request returns successfully, the app returns to the log in screen. In the event of an error, a UIAlertView is displayed with information regarding the error.
After "TUTORIAL STEP 4", add the following code:
Directly following the
handleLogout: method is the
tableView:cellForRowAtIndexPath: method. In this method, add the following code after "TUTORIAL STEP 5". This method provides some styling for each table view cell based on the properties of the model object.
tableView:commitEditingStyle:forRowAtIndexPath: method, add the following code after "TUTORIAL STEP 6". This snippet provides all the functionality to perform a 'swipe-to-delete' gesture for a particular list item. Create an AKJSONResponseHandler and pass that to the
removeTask:forHandler: method in the ToDoAgent class. When the request finished successfully, that task is removed from the list.
- Run the app and log in. You should now see tasks loaded.
Add editing to the To-Do app
The To-Do app lets users with the proper authorization create, edit, and delete list items. Selecting a task in the task list page opens the edit page, where you can modify and save updated task information or delete the task.
To add task editing:
- Open ToDoEditTaskViewController.m.
viewDidAppear: method, add the following code after "TUTORIAL STEP 1". In this code, you create an AKJSONResponseHandler object and pass it to the
getTask: method in the ToDoAgent class. When the request returns successfully, the UI elements on the screen are updated to displays the properties associated with the model.
datePickerValueChanged: method, add the following code after "TUTORIAL STEP 2". This code lets the
dueproperty on the model be updated when the date picker is changed.
saveButtonPressed: method and add the following code after "TUTORIAL STEP 3". This code first checks to see if a task already exists. If it does, the code performs an update on the existing model using
updateTask:forHandler:. If a model doesn't already exist, this code creates one by calling
createTask:forHandler:. Both of these actions require that an AKJSONResponseHandler be created and passed containing the actions to perform upon a successful and/or failed operation.
taskCompletionChanged: add the following code after "TUTORIAL STEP 4". This code sets the
completeproperty of this particular model. This method is triggered by the UISegmentedControl in the view.
handleAccessForbiddenOrDeniedError: method, add the following code after "TUTORIAL STEP 5". This code creates a pointer to an AKError object and then calls the
logoutmethod. This method is will create a UIAlertView in the case of an access denied or forbidden error returned from the server.
Add the following code after "TUTORIAL STEP 6" at the bottom of the class. This code contains implementations for request failure callbacks. THis method handles JSON dictionary objects and displays a UIAlertView with the error information.
- Run the app and log in with a username and password of "penny". You can now add, delete, and edit tasks.
Note that the user "leonard" does not have permissions to add or edit tasks, only to view them.
Understanding the Model object
While ToDoTask.m class does not contain any code snippets, it is important to understand that this implementation inherits from the AKBaseModel class. Each property in ToDoTask is represented as a key/value pair in the underlying data structure.