GO FURTHER, FASTER: Try the Swift Career Accelerator today! >>

Creating a custom property wrapper using DynamicProperty

It’s not hard to make a basic property wrapper, but if you want one that automatically updates the body property like @State you need to do some extra work. In this article I’ll show you exactly how it’s done, as we build a property wrapper capable of reading and writing documents from our app’s container.

This is a free sample from Hacking with Swift+, a subscription that delivers high-quality tutorials as both articles and videos. Click here to find out more >

Watch the video here, or read the article below

Reading and writing

We’re going to approach this property wrapper in two passes: a first pass able to read and write values, and a second pass that’s able to project a binding as well.

First, the easy part: we’re going to create a new property wrapper struct called Document that will store its value as a string, and also a URL pointing to the file it’s modifying. Because we’ll want to modify the text value over time, we’ll mark with the @State property wrapper so SwiftUI will look after it for us.

Start with this:

@propertyWrapper struct Document {
    @State private var value = ""
    private let url: URL
}

In order to be a valid property wrapper, our Document struct needs to have a wrappedValue property that stores the actual value we’re working with. In our case we already have that in value, but we made that private for a reason: when we interact with this property wrapper we want to add some extra work so that our new value gets written to disk automatically.

So, our wrappedValue property will be computed: when we’re reading it we’ll just send back value, but when we’re writing we’ll save it to wherever our file URL is then update value.

Now, we need a little bit of SwiftUI magic here, because if we have a setter for wrappedValue then we’ll be modifying the struct we’re inside and that will cause problems. Fortunately, we’re not actually changing the Document struct: we’re using @State, so we’re bypassing the struct entirely and having SwiftUI store the value. So, rather than making a regular setter, we can instead make a nonmutating setter, because our underlying struct won’t actually be changing.

Add this property to Document now:

var wrappedValue: String {
    get {
        value
    }
    nonmutating set {
        do {
            try newValue.write(to: url, atomically: true, encoding: .utf8)
            value = newValue
        } catch {
            print("Failed to write output")
        }
    }
}

And now we just need an initializer that provides initial values for both url and the value state. The first of these we can figure out by using FileManager to append the user’s filename to the app’s documents directory, but for the latter we need to load the initial value of the text file and wrap that in a State object.

Here’s that in code:

init(_ filename: String) {
    let paths = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
    url = paths[0].appendingPathComponent(filename)

    let initialText = (try? String(contentsOf: url)) ?? ""
    _value = State(wrappedValue: initialText)
}

That’s it – that’s our first pass of the property wrapper complete. To try it we need to update ContentView to use the @Document property wrapper and place its context inside a text view, but in order to make the test interesting we’re also going to add a button to simulate changing its value – this will just generate a random number and place it into the document.

Here’s the new ContentView:

struct ContentView: View {
    @Document("test.txt") var document

    var body: some View {
        NavigationView {
            VStack {
                Text(document)

                Button("Change document") {
                    document = String(Int.random(in: 1...1000))
                }
            }
            .navigationTitle("SimpleText")
        }
    }
}

If you run that now you’ll see the text view is empty by default, and if you press the button nothing will happen. Yes, after all that work we don’t actually have much to show, but that’s okay: with one tiny change we can bring the whole thing to life.

You see, right now SwiftUI doesn’t realize it should be watching our property wrapper for change notification, even though it has an @State property inside there. To fix this we need to make Document conform to the DynamicProperty protocol, like this:

@propertyWrapper struct Document: DynamicProperty {

In fact, that’s all we need to do – SwiftUI will take care of the rest for us. Go ahead and run the app again, because if you press the button it will update automatically. Even better, the new contents have been written to “test.txt” automatically, so if you relaunch the app you’ll see it remembers its last value – nice!

Projecting values

Wrapping a simple string works great for simple property wrappers like we have right now, but for more advanced purposes you’re also likely to want to expose a projected value. This allows us to create an alternative way of using the property we’re wrapping, and it’s down to us to define exactly what it does.

SwiftUI’s own @State property wrapper uses the projected value to create a binding for its data, and if we do the same thing here then it would allow us to bind directly to a document so that every change we make gets saved out.

This takes remarkably little code to accomplish. First we need to add a new property to Document that declares our projected value and how it works. Projected values must always be called projectedValue, but otherwise can work however you want.

So, start by adding this property to Document:

var projectedValue: Binding<String> {
    Binding(
        get: { wrappedValue },
        set: { wrappedValue = $0 }
    )
}

It’s worth stopping to step through what that code does: when our binding is written to we update wrappedValue, which in turn triggers our nonmutating setter, which is what causes the new value to be written to disk.

And now we can update ContentView to bind a TextEditor directly to our document, like this:

TextEditor(text: $document)

If you run that back you’ll see every change you make is immediately saved, and will also be restored when you relaunch the app. Nice!

Challenges

If you want to take this tutorial further, here are some suggestions:

Rather than have our binding write to disk every time a single character is changed, can you write code that simply sets a dirty flag and handle the writing at a later date? This might be periodically using Timer, or perhaps even by detecting the app moving to the background.
Can you think of a way for our property wrapper to detect external changes, and reload itself in that case? For example, if someone else modifies the file, our wrapper should detect that and load the modified file. This might be as simple as a timer checking when the file was last modified.

If you liked this, you'd love Hacking with Swift+…

Here's just a sample of the other tutorials, with each one coming as an article to read and as a 4K Ultra HD video.

Find out more and subscribe here