SDK Guides
...
Swift
Tutorials in Swift

UIKit: Task App Quickstart

This quickstart provides step-by-step instructions for using UIKit to create a task app in Xcode, which consists of the following:

Prerequisites

  • Ditto account and access credentials
  • iOS 13 (or later)
  • macOS 11 (or later)
  • Xcode 15 (or later)

For instructions on creating your account and obtaining your credentials, see Onboarding.

Creating a New App in Xcode

1

Click File, and then select New Project.

2

In the Choose a template for your new project modal, select App and then click Next.

Document image

3

In the Choose options for your new project modal, enter information as appropriate and then click Next.

The following are merely suggestions; enter any information in the form that you desire.

The following steps provide suggested values for the form; however, you can enter any information you desire:

  1. For Product Name, type "Tasks".
  2. For Team, select None.
  3. For Organization Identifier, type "live.ditto".
  4. For Interface, select Storyboard.
  5. For Life Cycle, select AppKit App Delegate.
  6. For Language, select Swift.
Document image


Adding Permissions to the Info.plist

For Ditto to access available networking capabilities, such as Bluetooth Low Energy, configure your project's user control and privacy permissions by doing the following:

iOS restricts access...

iOS restricts access to some Ditto functionality by default for the sake of user control and privacy as of the release of iOS 13 and Xcode 11.

To ensure access to all platform capabilities, you must configure your app to request all the permissions it needs to sync.

These requests occur once at the initiation of the sync process.

By default, Ditto activates Bluetooth, triggering an automatic permission prompt for your end users.

Ditto attempts to use your device's available networking capabilities to locate and sync with other app users. This includes standard Wi-Fi, also referred to as Local Area Network (LAN), and peer-to-peer functionality such as Apple Wireless Direct Link (AWDL) and Bluetooth Low Energy.

For more information, see Ditto Basics > Sync Concepts.

In addition, since iOS 14, Apple requires iOS device end users grant permissions to use the LAN to discover devices.

  • Privacy — Local Network Usage Description
  • Privacy — Bluetooth Peripheral Usage Description
  • Privacy — Bluetooth Always Usage Description
  • A Bonjour service


Creating UI Elements

Create elements for your interface, including a top navigation bar, a task list, and an element for entering the task name:

1

Click File > New and then select File from the list.

2

From the Choose a template for your new file modal, select Cocoa Touch Class and then click Next.

Document image

3

From the Choose options for your new file modal, enter the following:

  1. For Class, type "TaskTableViewController".
  2. For Subclass of, select UITableViewController.
  3. For Language, select Swift.
Document image

4

Delete your project's default view controller file by right-clicking ViewController.swift from the left navigator area and selecting Delete.

5

Verify that your project structure appears as follows:

Document image


Configuring the Storyboard

Once you've created your UI elements, open your project's Main.storyboard file located in the left navigator area and then do the following to set up your storyboard:

1

In the storyboard editor that appears, right-click the ViewController.swift file and select Delete from the list.

Document image

2

Add a UINavigationController into the storyboard.

  1. Click the circle with a square in it icon in the top right to display your list of UI elements and search for UINavigationController
  2. Click to add it to the storyboard.
  3. Click on the "Root View Controller Scene" and navigate the right hand menu to declare the UITableViewController as a custom class of TasksTableViewController.
Document image

3

This created a UINavigationController and a root view controller based on UITableViewController, but it needs to be configured to work with our TasksTableViewController.swift file:

Click on the "Root View Controller Scene" and navigate to the menu on the right to declare the UITableViewController as a custom class of TasksTableViewController:

4

Ensure that the "Navigation Controller Scene" is the initial view controller for our app, so click on it and navigate to the menu on the right to set this property:

Document image

5

Now we need to customize the UITableViewController to include the add task button. Click on the "Root View Controller Scene" and then click the "Circle with square" icon in the top right to add a UIBarButtonItem , search for "Bar Button Item" and drag it onto the top right corner of the UINavigationBar. Finally, configure the bar item to use the "System Item" "Add" in the right-hand menu:

Document image

6

The last configuration is to adjust the name in the navigation bar to "Tasks", click on the "Root View Controller" text and navigate to the menu on the right to adjust the name:

Document image


Connecting the UI

1

Declare a function that will called when the user clicks on the add icon in the navigation bar. To do so, click the "Show Assistant Editor" button in the top right so that our storyboard and TaskTableViewController.swift file are both displayed:

Document image

2

Now, right-click on the add button and drag it into the class implementation of TasksTableViewController just above the numberOfSections() function:

Document image

3

Name the function didClickAddTask and adjust the type to UIBarButtonItem and click connect. You should now have a function that is wired up to be called whenever that button is clicked:

Document image

4

Finally, we will need to configure UITableView in TasksTableViewController and as part of this, we need to provide a "Table view cell reuse identifier", so let's configure our storyboard cell to include an identifier. Click on the "Prototype Cells" area in your view and navigate the right-hand menu to display the configuration for the "Table View Cell" and insert taskCell as the identifier:

Document image


Setting Up the TasksTableViewController

First, we need to add some variables that will be created on viewDidLoad of the TasksTableViewController so adjust the class to match this code:

Swift


Let's break down what this code does. First, we create the variables needed and then initialize them in viewDidLoad() . To enable background synchronization, we need to call startSync() which allows you to control when synchronization occurs. For this application we want it to run the entire time the app is in use.

Swift


After setting up the variables and starting Ditto, we then use Ditto's key API to observe changes to the database by creating a live query in the setupTaskList() function. This allows us to set the initial state of the UITableView after the query is immediately run and then subsequently get callbacks for any new data changes that occur locally or that were synced from other devices:

Note, that we are using the observe API in Ditto. This API performs two functions. First, it sets up a local observer for data changes in the database that match the query and second it creates a subscription for the same query that will be used to request this data from other devices. For simplicity, we are using this combined API, but you can also call them independently. To learn more, see the Observing Changes section in the documentation.

Swift


Adding a Task

To allow the user to create a task we want to display an alert view in response to clicking the add bar item. Add the following code to the didClickAddTask() function we added earlier:

Swift


Take note that this logic is using the Ditto insert() API to create a task document. Ditto's API is designed around JSON-compatible documents which are organized into collections:

Swift


Configuring the UITableView to Display Task List​

To ensure the UITableView can display the tasks, we need to configure it. Adjust your TasksTableViewController to include the following code (these functions were already created when the file was generated by Xcode):

Swift


Earlier, we created the tasks array which is the data source to the UITableView. This code configures the UITableView to use this array and then configures the table view cell to display the task text and a checkmark on whether it is complete or not.

Editing Tasks

1

Select the task to complete:

When the user selects the task in the table view, we want to mark the task completed. Adjust your TasksTableViewController to include the following code (these functions were already created when the file was generated by Xcode):

Swift


This action makes use of Ditto's Update method where we are able to find the existing task and set the isCompleted value to the opposite of its current value.

2

Swipe to delete task:

Finally, we want to allow the user to delete a task by swiping the row in the table view. Adjust your TasksTableViewController to include the following code (this function was already created when the file was generated by Xcode):

Swift

3

Build and Run!

You now have a fully functioning to-do app. Build and run it on the simulator or devices and observe the automatic data sync provided by Ditto.