SDK Guides
...
Tutorials in Swift
SwiftUI: ToDo App Quickstart
this quickstart provides step by step instructions for using swiftui to create a task app in xcode, which consists of the following high level steps /#creating a new app in xcode /#configuring ditto docid 7s yuqda8iomoqeu4ygnw /#editing tasks prequisites ditto account and access credentials ios 13 (or later) macos 11 (or later) https //apps apple com/us/app/xcode/id497799835 15 (or later) for instructions on creating your account and obtaining your credentials, see docid\ hk2s3ld8sj ti5snxwkq1 creating a new app in xcode click file , and then select new project in the choose a template for your new project modal, select app and then click next in the choose options for your new project modal, enter the following 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 for product name , type "todo" for team , select from apple developer account teams for organization identifier , enter your org identifier, typically reverse domain, e g "live ditto" for interface , select swiftui for life cycle , select swift ui app for language , select swift xcode new project modal configuring ditto add ditto sdk package click on the todo project at the top level of the project navigator to display the project configuration ui select the todo project in the projects and targets list in the editor then select the package dependencies tab click add package dependency (plus button) at the bottom of the packages list in the add package modal window, in the search bar, enter the dittoswiftpackage url github com/getditto/dittoswiftpackage in the dependency rule field, select "up to next major" from the dropdown menu, and type in "4 5 0" in the version field xcode add package modal add both dittoobjc and dittoswift libraries xcode add package libraries modal create dittomanager from file menu > new > file, select swift file template, then click next button name the new file dittomanager swift import dittoswift initialize the ditto variable instance with an online playground identity using the app id of the app that you have created on the portal we are using an onlineplayground setup, which should suffice for this tutorial however, you should never deploy an app with this configuration to a production environment like the apple app store we will implement dittomanager as a singleton for the convenience of its availability throughout the app swift import dittoswift import foundation class dittomanager { var ditto ditto static var shared = dittomanager() init() { ditto = ditto( identity onlineplayground( appid ditto app id, token ditto playground token ) ) } } todo tasks create a todo struct ditto is a document database, which represents all its rows in the database as json like structures with key/value properties in this tutorial, we will define each todo task like so { " id" "123abc", "body" "get milk", "iscompleted" true "isdeleted" false } ditto documents have a flexible structure, like json, and in swift, dql queries return a dittoqueryresult , which has an items array property containing a dittoqueryresultitem for each match we can access the key/value pairs of those items with the item value property it is a common practice to create a data model structure to more conveniently work with the app's business logic and to leverage swift's type safety let's do that now create a new swift file called todo swift in your project add import dittoswift to the top of the file create a todo struct and a dd the matching properties let id string , let body string , and let iscompleted bool to the struct the type of dittoqueryresultitem value is \[string any?] , which contains the matching key/value pairs we will use to initialize the struct add the init(value \[string any?]) constructor which will take an argument of the result item value type add an extension to the struct declaring conformance with the identifiable protocol, and implement var id string to return the id key string the identifiable protocol is required to uniquely identify todo instances in the foreach component in swiftui's list view it may seem confusing to implement both id and id in the same struct to clarify, id is a property of the underlying dittodocument uniquely identifying it in the ditto database, and the struct's id property uniquely identifies the struct instance for the swiftui view todo swift // 1 import dittoswift // 2 struct todo codable { let id string let body string var iscompleted bool var isdeleted bool // 3 init(value \[string any?]) { id = value\[" id"] as! string body = value\["body"] as! string iscompleted = value\["iscompleted"] as? bool ?? false isdeleted = value\["isdeleted"] as? bool ?? false } } // 4 extension todo identifiable { var id string { return id } } later in the tutorial we will see how to register a ditto store observer that will return the result of a query whenever there is a change in the database documents matching the query create a taskslistscreen view when we generated the project, xcode created a default contentview which we will delete, and then create the taskslistscreen to replace it, which will show the list of the views create a new swiftui view view by clicking file > new > swiftui view named "taskslistscreen" , and i mport dittoswift at the top of the file create a ditto property of type ditto in the body block, add a navigationview with a list child view we will fill out the contents of the list in the next section add a navigationtitle modifier on the end of the list to display a title on the navigation bar then add a trailing navigation "plus" button in a navigationbaritems modifier we will implement the button action later and finally, stub in a sheet modifier that we will use to present an editscreen , which we will create later taskslistscreen swift import swiftui // 1 import dittoswift struct taskslistscreen view { // 2 let ditto ditto var body some view { // 3 navigationview { list { } // 4 navigationtitle("tasks swiftui") // 5 navigationbaritems(trailing button(action { }, label { image(systemname "plus") })) // 6 sheet(ispresented constant(false), content { }) } } } delete contentview\ swift right click contentview\ swift in the xcode navigator pane select "delete" from the menu click "move to trash" from the action sheet set tasklistscreen as main view in todoapp swift replace contentview with the tasklistscreen in the windowgroup swift import swiftui @main struct todoapp app { var body some scene { windowgroup { taskslistscreen() } } } in the last part of the tutorial we implemented the start of a taskslistscreen view to display a list of todo tasks create a taskrow view each row of the tasks list will be represented by a swiftui view called todorow which takes in a todo task instance and two action closures which we will use later if task iscompleted is true , we will show a filled circle icon and a strikethrough style for the body text if task iscompleted is false , we will show an open circle icon when the user taps the circle icon, we will call the ontoggle (( task task) > void)? , we will reverse the iscompleted from true to false or false to true if the user taps the text , we will call a onclickbody (( task task) > void)? we will use this to navigate an editscreen (we will create this later) for brevity, we will skip discussions on styling as it's best to see the code snippet below we've also included a taskrow previews that allows you to see the end result with some test data quickly taskrow\ swift import swiftui struct taskrow view { let task task var ontoggle (( task task) > void)? var onclickbody (( task task) > void)? var body some view { hstack { // 2 image(systemname task iscompleted ? "circle fill" "circle") renderingmode( template) foregroundcolor( accentcolor) ontapgesture { ontoggle?(task) } if task iscompleted { text(task body) // 2 strikethrough() ontapgesture { onclickbody?(task) } } else { // 3 text(task body) ontapgesture { onclickbody?(task) } } } } } struct taskrow previews previewprovider { static var previews some view { list { taskrow(task task(body "get milk", iscompleted true)) taskrow(task task(body "do homework", iscompleted false)) taskrow(task task(body "take out trash", iscompleted true)) } } } create a taskslistscreenviewmodel in the world of swiftui, the most important design pattern is the mvvm, which stands for model view viewmodel mvvm strives to separate all data manipulation (model and viewmodel) and data presentation (ui or view) into distinct areas of concern when it comes to ditto, we recommend that you never include references to edit ditto in view\ body all interactions with ditto for upsert , update , find , remove and observe should be within a viewmodel the view should only render data from observable variables from the viewmodel and only the viewmodel should make direct edits to these variables typically we create a viewmodel per screen or per page of an application for the taskslistscreen we need some functionality like showing a realtime list of task objects triggering an intention to edit a task triggering an intention to create a task clicking an icon to toggle the icon from true to false or false to true in swiftui we create a view model by inheriting the observableobject the observableobject allows swiftui to watch changes to certain variables to trigger view updates intelligently to learn more about observableobject we recommend this excellent https //www hackingwithswift com/quick start/swiftui/how to use observedobject to manage state from external objects create a file called taskslistscreenviewmodel swift in your project add an init constructor to pass in a ditto ditto instance and store it in a local variable create two @published variables for tasks and i spresentingeditscreen @published variables are special variables of an observableobject if these variables change, swiftui will update the view accordingly any variables that are not decorated with @published can change but will be ignored by swiftui we also add a normal variable, private(set) var tasktoedit task? = nil when a user is attempting to edit a task, we need to tell the view model which task the user would like to edit this does not need to trigger a view reload, so it's a simple variable here's where the magic happens as soon as the taskslistscreenviewmodel is initialized, we need to observe all the tasks by creating a live query to prevent the livequery from being prematurely deallocated, we store it as a variable in the observe callback, we convert all the documents into task objects and set it to the @published tasks variable every time to observe fires, swiftui will pick up the changes and tell the view to render the list of tasks we will add an eviction call to the initializer that will remove any deleted documents from the collection add a function called toggle() when a user clicks on a task's image icon, we need to trigger reversing the iscompleted state in the function body we add a standard call to find the task by its id and attempt to mutate the iscompleted property add a function called clickedbody when the user taps the taskrow 's text field, we need to store that task and change the ispresentingeditscreen to true this will give us enough information to present a sheet in the taskslistscreenviewmodel to feed to the editscreen in the previous setup of the taskslistscreen , we added a navigationbaritem with a plus icon when the user clicks this button we need to tell the view model that it should show the editscreen so we've set the ispresentingeditscreen property to true however, because we are attempting to create a task , we need to set the tasktoedit to nil because we don't yet have a task taskslistscreenviewmodel swift class taskslistscreenviewmodel observableobject { // 3 // highlight start @published var tasks = \[task]\() @published var ispresentingeditscreen bool = false // highlight end // 4 // highlight next line private(set) var tasktoedit task? = nil let ditto ditto // 5 // highlight start var livequery dittolivequery? var subscription dittosubscription? init(ditto ditto) { self ditto = ditto self subscription = ditto store\["tasks"] find("!isdeleted") subscribe() self livequery = ditto store\["tasks"] find("!isdeleted") observelocal(eventhandler { docs, in self tasks = docs map({ task(document $0) }) }) //6 ditto store\["tasks"] find("isdeleted == true") evict() } // highlight end // 7 // highlight start func toggle(task task) { self ditto store\["tasks"] findbyid(task id) update { mutabledoc in guard let mutabledoc = mutabledoc else { return } mutabledoc\["iscompleted"] set(!mutabledoc\["iscompleted"] boolvalue) } } // highlight end // 8 // highlight start func clickedbody(task task) { tasktoedit = task ispresentingeditscreen = true } // highlight end // 9 // highlight start func clickedplus() { tasktoedit = nil ispresentingeditscreen = true } // highlight end } render taskrow in a foreach within the taskslistscreen now we need to update our taskslistscreen to properly bind any callbacks, events, and data to the taskslistscreenviewmodel back in the taskslistscreen view, we need to construct our taskslistscreenviewmodel and store it as an @observedobject this @observedobject tells the view to watch for specific changes in the viewmodel variable we will need to store our ditto object to pass to the editscreen later in our body variable, find the list and add foreach(viewmodel tasks) { task in taskrow(task task, ontoggle { task in viewmodel toggle(task task) }, onclickbody { task in viewmodel clickedbody(task task) } ) } this will tell the list to iterate over all the viewmodel tasks and render a taskrow in each of the taskrow children, we need to bind the ontoggle and onclick callbacks to the viewmodel methods bind the plus button to the viewmodel clickedplus event now we need to present a sheet which will activate based on the $viewmodel ispresentingeditscreen variable notice how we added the $ before viewmodel sheet can edit the ispresentingeditscreen once it's dismissed, so we need to treat the variable as a bidirectional binding we've also included a taskslistscreen previews so that you can add some test data and see the result in a live view taskslistscreen swift struct taskslistscreen view { // 2 // highlight next line let ditto ditto // 1 // highlight start @observedobject var viewmodel taskslistscreenviewmodel init(ditto ditto) { self ditto = ditto self viewmodel = taskslistscreenviewmodel(ditto ditto) } // highlight end var body some view { navigationview { list { // 3 // highlight start foreach(viewmodel tasks) { task in taskrow(task task, ontoggle { task in viewmodel toggle(task task) }, onclickbody { task in viewmodel clickedbody(task task) } ) } // highlight end } navigationtitle("tasks swiftui") navigationbaritems(trailing button(action { // 4 // highlight next line viewmodel clickedplus() }, label { image(systemname "plus") })) // 5 // highlight start sheet(ispresented $viewmodel ispresentingeditscreen, content { editscreen(ditto ditto, task viewmodel tasktoedit) }) // highlight end } } } // 6 // highlight start struct taskslistscreen previews previewprovider { static var previews some view { taskslistscreen(ditto ditto()) } } // highlight end notice that we do not have to manipulate the tasks value directly executing the update query on dittostore will automatically fire the storeobserver to update the tasks you can always trust dittostoreobserver to immediately update the @published var tasks with changes there is no reason to poll or force reload ditto will automatically handle the state changes and swiftui will pick these changes up automatically editing tasks our final screen will be the editscreen and its viewmodel the editscreen will be in charge of 3 functions editing an existing creating a deleting an existing creating the editscreenviewmodel like before, we need to create an editscreenviewmodel for the editscreen since we've already gone over the concepts of mvvm, we will go a bit faster the editscreenviewmodel needs to be initialized with ditto and an optional task task? value if the task value is nil we need to set the candelete variable to false this means that the user is attempting create a new task we will use this value to show a delete button in the editscreen later we will store the id string? from the task parameter and use it later in the save() function we need two @published variables to bind to a textfield and toggle swiftui views for the task's iscompleted and body values if the task == nil , we will set some default values like an empty string and a false iscompleted value when the user wants to click a save button , we need to save() and handle either an upsert or update function appropriately if the local id variable is nil , we assume the user is attempting to create a task and will call ditto's upsert function otherwise, we will attempt to update an existing task with a known id finally if a delete button is clicked, we attempt to find the document and call remove editscreenviewmodel swift import swiftui import dittoswift class editscreenviewmodel observableobject { @published var candelete bool = false // 2 // highlight start @published var body string = "" @published var iscompleted bool = false // highlight end // 1 // highlight start private let id string? private let ditto ditto init(ditto ditto, task task?) { self id = task? id self ditto = ditto candelete = task != nil body = task? body ?? "" iscompleted = task? iscompleted ?? false } // highlight end // 3 // highlight start func save() { if let id = id { // the user is attempting to update ditto store\["tasks"] findbyid( id) update({ mutabledoc in mutabledoc?\["iscompleted"] set(self iscompleted) mutabledoc?\["body"] set(self body) }) } else { // the user is attempting to upsert try! ditto store\["tasks"] upsert(\[ "body" body, "iscompleted" iscompleted, "isdeleted" false ]) } } // highlight end // 4 // highlight start func delete() { guard let id = id else { return } ditto store\["tasks"] findbyid( id) update { doc in doc?\["isdeleted"] set(true) } } // highlight end } create the editscreen like the taskslistscreen swift in the previous section, we will create an editscreen swift this screen will use swiftui's form and section wrapper an textfield which we use to edit the task body a switch which is used to edit the task iscompleted a button for saving a task a button for deleting a task in the editscreen we need to add a @environment(\\ presentationmode) private var presentationmode in swiftui views house some environment variables because the taskslistscreen presened the editscreen as a sheet , we need a way to dismiss the current screen if the user taps any of the buttons to learn more about environment , https //developer apple com/documentation/swiftui/environment to dismiss the current screen we can call self presentationmode wrappedvalue dismiss() like before, store the editscreenviewmodel as an observedobject pass the task task? and the ditto instance to properly initialize the editscreenviewmodel now the viewmodel should know if the user is attempting a creation or update flow we now can bind the textfield for the $viewmodel body and toggle to the $viewmodel iscompleted notice the $ , this allows swiftui fields to bi directionally edit these @published values and trigger efficient view reloading bind the save button's action handler to the viewmodel save() function and dismiss the view whenever the user clicks the save button, they will save the current data and return back to the taskslistscreen if the viewmodel candelete is true , we can show a delete button notice how we don't need the $ since we are only reading the value once moreover, we do not need to tell swiftui to re render on candelete since it will never change during the editscreen 's life cycle bind the delete button's action to the viewmodel delete() function and dismiss the view finally we add a editscreen previews so that you can easily watch the view's final rendering as you develop editscreen swift struct editscreen view { // 1 // highlight next line @environment(\\ presentationmode) private var presentationmode // 2 // highlight start @observedobject var viewmodel editscreenviewmodel init(ditto ditto, task task?) { viewmodel = editscreenviewmodel(ditto ditto, task task) } // highlight end var body some view { navigationview { form { section { // 3 // highlight start textfield("body", text $viewmodel body) toggle("is completed", ison $viewmodel iscompleted) // highlight end } section { button(action { // 4 // highlight start viewmodel save() self presentationmode wrappedvalue dismiss() // highlight end }, label { text(viewmodel candelete ? "save" "create") }) } // 5 // highlight next line if viewmodel candelete { section { button(action { // 6 // highlight start viewmodel delete() self presentationmode wrappedvalue dismiss() // highlight end }, label { text("delete") foregroundcolor( red) }) } } } navigationtitle(viewmodel candelete ? "edit task" "create task") navigationbaritems(trailing button(action { self presentationmode wrappedvalue dismiss() }, label { text("cancel") })) } } } // 7 // highlight start struct editscreen previews previewprovider { static var previews some view { editscreen(ditto ditto(), task task(body "get milk", iscompleted true)) } } // highlight end run the app! https //docs ditto live/ios/tutorial/swift/edit screen#4 4 run the app congratulations you have successfully created a task app using ditto!