Good morning. Welcome to Session 227, Data Delivery with Drag and Drop. My name is Dave Rahardja, and I'm joined here, today, by my colleague Tanu, who's going to be operating the demos. So, if you've been following along in our series of Drag and Drop sessions, this diagram should be pretty familiar to you.

During this session, we're going to be focusing on this part of the diagram, Item Providers. Now, Item Providers are fundamental to the way data is transferred between applications in drag and drop. So, in this session, we're going to cover four topics about item providers. We're going to cover some basics.

We're going to talk about how uniform type identifiers help your apps to be more compatible with others in the system. We're going to cover how you can create model classes that work really well with drag and drop. And finally, we're going to close out by covering some advanced topics that'll add some real polish to your apps in our ecosystem. So, let's get started.

Let's talk about some NSItemProvider basics. So, what's an NSItemProvider? Simply put, an NSItemProvider is a data promise. All data is loaded through drag and drop asynchronously and on demand. An NSItemProvider can also, help you to provide progress and cancellation of data transfer. And it is supported widely in our API. Of course, in drag and drop, but also in UIPasteConfiguration. And we've added API for UIPasteboard, so that you can use NSItemProvider directly with it.

So, what does it mean to provide data or promise data? Providing data to an NSItemProvider is really simple. All you have to do is create an NSItemProvider and pass it an object that is suitable for use. Now, a lot of our system provided classes, such as UIImage in a string, in its attributed string can be used this way. And we'll see in a few slides now, how you can make your classes work in this fashion, as well. Once you provide the data, it can be retrieved by the receiving application equally simply, by calling the loadObject method on the itemProvider, therein.

Remember that data transfer is asynchronous and that your completionHandlers will be called on a nonmain cue. So, if you're going to update the UI with your received data, be sure to dispatch back to the main queue before you call UIKit methods. And you're going to see this brought up a few times. So, to show you how easy it is to use NSItemProviders, we're going to start with a demo. Tanu.

Good morning, everyone. You've now heard of drag and drop and NSItemProviders. But now, you're probably wondering how to use these in your own apps. My name is Tanu Singhal, and I'll show you a simple demo that will help you get started with NSItemProviders. We have an app, here, that has a list of customers for our product. Now, I met some new people who are also interested in trying out this product. So, I noted their names down in Reminders.

It would be nice if could drag a name and drop it into my app. So, how do we do this? Let's look at the TableViewController for our Contacts app. Before I start typing I want you to know that we made the sample code for this available on the developer website. So, you don't have to worry about jotting down everything, right now.

In the TableViewController, I'll add a TableViewDropDelegate. Let's also set this delegate. You may have heard of the TableViewDropDelegate in previous sessions. But if you haven't, then don't worry. Because for now, we only need to implement one method called TableView performDropWith coordinator. In this method, I'll iterate over the drag items provided by the ItemProvider. Sorry, the dragItems provider by the coordinator.

Now, each dragItem has its own itemProvider. And we can check whether the itemProvider can load objects of a certain type. So, I'm going to check if the itemProvider can load a string. For that, I'll call the canLoadObject method. If it can load it, then I'll call the loadObject method.

And the completionHandler of this loadObject method will give me an object which will be a string that I can use to update my data models, as well as my UI. One thing to note is that the completionHandler is on the background thread. So, if you want to make any changes to your UI, then you need to go back to the main thread, and then make those changes.

So, let me dispatch my main queue. And in the main thread I'll use the string object, and I'll insert it into the TableView. This code is ready to run, now. Wait just a moment. And this time, I can drag a name from Reminders and drop it into my app.

The canLoadObject and LoadObject methods can also be used for other system types, like attributed strings, URLs, images, and even colors. So, now that you've seen how straightforward it is to handle system objects in your using itemProviders, I would encourage all of you to try out these APIs. Up next, Dave will talk about Progress and Cancellation.

Thank you, Tanu. So, that covers the basics about how to use NSItemProviders in your application. It was really simple. Now, let's talk about progress and cancellation. When you retrieve data using NSItemProviders, we return a progress object to you that allows you to track the progress of data transfer as it occurs.

The progress object has two interesting properties on it, that you might want to observe. The first, is the fractionCompleted property, which tells you from zero to one, how much of the data has been transferred. And the second, is an isFinished property that tells you that the data transfer has been completed, whether it is successful or not. You can use key value observing to watch these two properties and update your UI accordingly. Such as by providing your own progress indicator and cancellation button.

There is a cancel method on the progress object that will immediately cancel the data transfer, as well. When you call he cancel method on the return progress object, your receiving application will receive, will get a callback on the completionHandler with an error in it, regardless of whether or not the source application has cancelled their data providing.

You get one progress object per load request. However, there's an overall progress object that you can get from the UIDropSession that allows you to monitor and cancel the entire remaining data transfer in progress. So, now that we've covered the basics, let's talk about maximizing compatibility. You want your application to provide data to as many other applications on the system, as possible. And receive drops from as many applications, as possible, as well.

The key to understanding how to maximize compatibility is understanding uniform type identifiers. So, let's recap. One NSItemProvider represents one thing that the user is dragging across the glass. However, there can be multiple representations that you can make available for every item that the user is dragging. Let me give you an example.

If you're writing a vector drawing program, for example, you could offer a native file format for best quality as the thing that you're dragging. But you might also offer conversions to PDF, PNG, or even JPG, so that you can drop this item on a variety of destination applications.

Uniform type identifiers allow you to tag these representations with unique strings that identify the kinds of data that you're putting up for the drag. For a native file format, you can define your own strings, such as com.yourcompany.vector-drawing. And for commonly known types, such as PDF and PNG, you can use the symbols defined in mobile core services to tag them.

Now, fidelity order matters. The order in which you register your representations should correspond to the order of quality that you're making available to the destination. Usually, the highest fidelity would be your internal data representation type. And then, followed by the next high fidelity common type, and so on and so forth.

Now, one tip to remember when using type identifiers to register your representations, is that there are uniform type identifiers that correspond to abstract types. Such as data, or plain text, or image. Avoid these. Instead, use concrete data types that help the consumer of your data interpret the bytes that you're going to send over to them. So, for example, use utf8-plain-text, instead of plain-text. Or probably .png instead of image, so that the receiver can interpret your data. Of course, for your private type identifier, you're free to define your own data types and byte layouts.

So, you've seen how these multiple representations allow you to maximize compatibility. But you didn't see any of this type identifiers being used in our initial example code of creating NSItemProviders. So, how did this work together? This is where we talk about creating model classes that harness the power of both multiple representations for compatibility. And the simplicity of using objects to initialize itemProviders.

To create model classes that work well with drag and drop, we're going to talk about two protocols that help you to do this. NSItemProviderReading and NSItemProviderWriting. Let's talk about the writing protocol, first. NSItemProviderWriting exports data from your model object and NSItemProviderReading imports data and creates a model object from a representation. And by adopting these protocols, you can maintain the conversion between your model objects and multiple representations with your model object and not with the UI code.

So, let's take a look at NSItemProviderWriting. This is what it looks like. There are only two things that you need to implement to conform to this protocol. The first is a writableTypeIdentifiersForItem Provider property. This is the list of the type identifiers that you can export in fidelity order. Highest fidelity first.

And then, a loadData method which will take that typeIdentifier that has been requested by the other application. Which will call a completionHandler, either with the data that you've made available or with an error. By implementing this protocol, the UI code can look like this and our framework code will do the equivalent of this, for you.

All right. Let's take a look at the reading protocol. The reading protocol is, of course, the other end of the pipe. It too, has two things that you need to implement. The first is the list of readable type identifiers in fidelity order, also. And the second, is that initializer that will take a NS data block, a NS data object, which should be used to initialize the instance of your object.

When you implement this protocol the UI code can look like this, a canLoadObject. You can pass it to your vector drawing object. And when you call the loadObject, our framework code will matchmake the two lists of type identifiers, both from the provider and the consumer. To find the best match to ensure that the highest quality data is used to create an instance of your object.

So, in short, to make model classes that work well with drag and drop, you should create, these classes should conform to NSItemProvider reading and writing protocols. Because these are Objective-C protocols, your model classes should also inherit from NSObject. And when you do this, you can use your classes and your objects wherever NSItemProvider is supported, drag and drop, and UIPasteConfiguration, and also, with the new API in UIPasteboard. So, to show you how this is done in code, I'm going to ask Tanu to do another demo.

Hello, again. In the previous demo, we learned to load simple system objects like strings. Now, let's see how we can drag a rich contact card from the Contacts app and drop that into our app. To do this, I've created a class called ContactCard. This holds the name, phone number, and photo for a contact. Now, I'm going to go back into the TableView controller, and this is the performDrop method that we implemented, before. Last time, we were trying to load a string. Now, we want to load a contact card. So, I'll replace all instances of NSSTring with ContactCard.

Since we are requesting a contact card the completionHandler will directly give me a contact card object, and I can use that to insert into my TableView. Now, this should have worked, right? But the reason we're getting errors, here, is because the NSItemProvider does not recognize my ContactCard class. So, we need to do a little work to conform to the NSItemProvider. Let's look at the ContactCard class, again. And here, I'm going to implement the NSItemProviderReading protocol. This will tell the NSItemProvider that I can read data that it provides.

Now, I need to specify the types of identifiers that I can read. My ContactCard class can read either a vCard, or it can read plain text. Note that these need to be specified in descending order of fidelity. If we specified plain text first, then we would always get called back for plain text. Even when a more rich vCard type was available.

So, after we've specified the types we can read, we're going to set up an initializer where we'll actually read the data from the itemProvider. One of the arguments in this initializer is the typeIdentifier. So, I can use that to figure out what type of data I received. If I got a vCard, I'll use a helper method to set the phone number, picture, and all the other information I need. If I just got plain text, I'm going to set the name for my contact card.

Now, when we run this, those errors are resolved. This is because the NSItemProvider understands our class, now. So, this time, I can drag and name from the Contacts app on the right, and drop it into my app. As you can see, we loaded the name, phone number, as well as the photo for this contact.

Note that we can still drag out plain text, like from the Reminders app, again. And this works, because our ContactCard class not only handles vCards, but it also handles plain text. So, this is what we wanted. And our users really like this feature. But now, we have another feature request. They want the ability to drag out contacts from our app and drop it into other apps. In order to implement that, we'll have to conform to another protocol called NSItemProviderWriting protocol.

As part of this protocol, I'll specify the types of identifiers that I can write. My class can again, write either a vCard or plain text. After this, we need to specify a loadData method. In this method, we'll create the data that we want to provide to the itemProvider.

So, based on the type identifier, I can create different types of data and I'll just pass it to the completionHandler. Now, we have completed the implementation for the NSItemProviderWriting protocol. There's just one last thing to do. We need to go back into our TableViewController and tell the TableView that it can be used to drag out items. To do this, I'll implement the TableViewDragDelegate. We need to set this delegate, too.

And for this delegate, we'll implement one method called itemsForBeginning session. In this method, I'm going to create an itemProvider. And you can see that I'm able to pass a ContactCard object directly to the itemProvider's initializer. This works only because we implemented the NSItemProviderWriting protocol. Let's run this code, now.

And I would like to share a contact with my colleague on Messages. So, let me drag out Dinesh's contact and drop it. As you can see, we were able to send out the name, phone number, as well as the photo. Which is what we were trying to accomplish.

So, now we have learned how the NSItemProvider reading and writing protocols can be used to transfer data using custom class objects. These are really powerful protocols and we think you'll find them extremely useful when you implement drag and drop in your own apps. Up next, Dave will cover some advanced topics.

Thanks, Tanu. So, cool. All right. Next, we're going to cover some advanced topics. These are just some collection of things that is very good to know, when you're going to polish your app so that it shines in the drag-and-drop environment. The first thing we're going to cover is data marshaling. So, if you look at the NSItemProvider API in iOS 11, you'll discover that there are three ways you can provide data. You can provide data as a data object, obviously. But you can also provide data as a file or a folder on your file storage.

Third, you can provide the data as a reference into a File Provider. We'll talk about File Providers more, later. Similarly, the receiver of the data can retrieve data in three different ways. They can copy it as their own NS data object. They can copy a file or a folder into their container. And they can attempt to open the file in place.

So, three ways to provide data, and three ways to consume it. What do you have to do to make sure that data transfer happens seamlessly, and that the data is made available in the correct format? Well, the good news is you have to do nothing. We do it for you.

Data marshaling makes sure that the provider of the data can provide and consume the information in the way that's most convenient for them. If you provide a file and then, you consume it as a data, we will read the file into an NSData object for you. If you provide an NSData and you ask for a file copy, we'll write it to file storage and give you your L reference to it.

If they provided a folder and you asked for NSData, we will zip up the contents of the folder and give you an NSData of the zip file. And if they provide a reference to a file provider and you ask for a file copy, we will call in the promises for the file provider and make a copy on your behalf.

All right. So, we've seen how progress and cancellation worked from the consumer side. So, I want to talk a little bit about how progress and cancellation works on the provider's side. I'm going to show you a block of code, here. Don't worry that it's a dense block of code, because I'm going to highlight the parts that are most important. This is a loadData implementation for our NSItemProviderWriting. In which you are going to use a dataLoader object to incrementally load data.

To provide progress and cancellation support, the first thing you have to do is create your own progress object. In this case, we're creating one with a UnitCount of 100 as a percentage. On that progress object, you can attach a cancellationHandler that will be called when the consumer of your data calls cancel on their instance of the progress object.

In this case, all we're doing is setting a local variable from true to false, which should stop the dataLoader from loading the next chunk. As the dataLoader progresses, you can update the completedUnitCount on your progress object to drive the progress indicator on the receiver. And of course, you have to return your own progress object so that we can type it over to the other side.

All right. Switching gears, now. We're going to talk about some features that help you to polish your data representations when creating suites of apps. So, we're going to talk about Per-Representation Visibility. Remember, you can provide multiple representations of your data in NSItemProvider. You can restrict the visibility of each representation to either visible to only your source application.

To the applications that are assigned by your team, so in your suite of apps, or to everyone. You can use this property to hide private types that you are rapidly maintaining with versions of your application suite. So, you don't have to worry about third parties serializing your data to disc.

In a similar vein, you have a team data property on NSItemProvider. This is an eight kilobyte data block that you can attach through an NSItemProvider. They are only visible to other applications in your team. You can use this to improve your UI in any way you see fit, during a drag.

This is metadata, and can be retrieved even before the user lifts their finger. All right. There is a suggestedName property on the NSItemProvider. If you provide a string for the suggested name, we will use it as a file name when the retriever writes your data to disc. This is especially useful, of course, when you're providing an NSData.

And the last property I want to talk about is Preferred Presentation Size. This is a CG size property that you can provide to give a hint to the receiver about how big your representation's going to end up after they've laid out. This is used, for example, by Mail, to drop images into the Mail Compose sheet, into the destination layout, even before the data arrives.

And finally, I'm going to talk about File Providers. So, File Providers is a whole other topic, on its own. But a short summary can be said as follows. A File Provider is an app extension. This app extension allows data transfer from a network download, for example, to continue even if your main application has been terminated. For long running drags, this is especially useful. Because as the user waits for a download to occur, they may navigate away from your app, and your app could get terminated.

If you provide a URL to a file inside a File Provider container, the File Provider extension will continue to serve the data transfer request, even though your UI application is terminated. And that increases the chances that your data is going to be transferred successfully. And as an added bonus, if you create a File Provider that appears in the file's app, we will allow you to drag and drop URLs that can be opened in place. Which means that multiple applications can access that same file, instead of getting their own copy.

There's some really great information available in the following two sessions. I highly recommend that you attend them, if you are interested in providing File Providers in the context of drag and drop. All right. Next, we're going to take a look at what we can do with files in drag and drop, by having Tanu do another demo.

Hope you are ready for another demo. In the previous demo, we saw how we could drag and drop simple system objects, as well as custom class objects. Now, let's see how we can handle files. We'll look at our customer's app, again. And for some people, here, we have additional data.

Like for Adam, we know what products he's purchased. Now, I would like to drag out this file into another app and potentially edit it, there. To implement this, I'll look at the ContactDetailsViewController in my customer's app. Over here, we will add a drag interaction to the attachment image that we just saw.

Let's also, implement the Drag Interaction Delegate, right here, because we have set the delegate to self. You may have heard of the drag interaction delegate in previous sessions. If you're interested in learning more about this delegate, I would encourage you to check out the video for Session 213 on Mastering Drag and Drop. For the purposes of this demo, though, we'll only look at one method, called itemsForBeginning session.

In this method, we'll create a new itemProvider, and on the itemProvider we'll call a method called registerFileRepresentation. This method takes four arguments. The first one is the type identifier. Our attachment file was actually an image. So, I've set the type identifier to JPEG. The second parameter is file options. This can be used to specify if we want other apps to open our file in place, or if we want them to make a copy. We would like them to open our file in place, so we can see the changes they make. The third parameter is visibility.

This can be your own process, your team, or all. I've just set it to all. Finally, we have the completionHandler. And we are going to pass the URL file into this completionHandler. So, let's get the URL, first. Over here, I have a helper method that grabs the URL for my file from a File Provider.

I need to use a File Provider only when I'm opening files in place. If I wanted other apps to make a copy, then I do not need a File Provider. I could have just provided a local URL. We'll pass this URL to the completionHandler. Now, our itemProvider is set up. And we can use this to create a drag item. With this, the code is ready to run.

So, now I can drag out this file. And let me open another app where I'll drop it. So, we'll drag out the data, drop it into a document editing app. And I'm concerned now, that Adam is buying a lot of products from our competitor. So, let me highlight this and save these changes. So, since our document editing app actually used the URL provided by the customer's app, you'll see that we got the same changes back in our customer's app.

Glad you like that. We've now seen how to handle system objects, custom class objects, as well as files. We have a wide range of APIs that you can adopt. And we look forward to seeing how you use them. Back to Dave, to summarize.

Thank you, Tanu. All right. Let's recap. During this session, we've seen how an NSItemProvider is fundamental to the way data is transferred between applications in Drag and Drop. We've seen how multiple representations allow your applications to maximize compatibility with other applications. And we've seen how data is transferred asynchronously with progress in a cancellable fashion.

We've also seen how NSItemProvider reading and writing protocols allow you to make model classes that work well with drag-and-drop UI code. And how visibility and team data allows you to create suites of apps that work in especially well together during drag and drop. And finally, we've seen how File Providers afford you the ability to open files in place as the result of drag and drop.

For more information, please visit our developer website, Session 227. And I highly encourage you to attend the File Provider related sessions, today and tomorrow, to learn more about how to create File Providers for your own applications. If you haven't seen the first three sessions on Drag and Drop, I highly recommend that you review them on video. Thank you, for your attention, and have a great WWDC.