Saving Multiple Related Items (Files) from a Sandboxed Application
On the Mac App Store applications are required to be sandboxed. This means that an application has a restricted set of files that it can access. For most document based applications saving to arbitrary locations is relatively easy because Powerbox requests the save location from the user and then grants the application access to that location.
The problem occurs when a sandboxed application needs to write out more than one file (for example resources associated with the document). The easiest way to resolve this issue is to create a package or at least an enclosing folder. The user can pick the location for the folder and Powerbox will grant the application access to that folder and everything inside it. This way you can write as many files as you want to that folder.
Things can become more difficult if you are required to have more complicated export options. For example if you are exporting content for a webpage you may want to export a .html file with a resources folder adjacent to it. If you want to allow users to do this without creating an enclosing folder, because it may disrupt the rest of the site structure, sandboxing can only give you access to one file. You will only have permission to write the .html file or the resources folder not both.
Another situation where this can occur is when you need to change the extension of an existing file that a user has already granted your application access to. For example TextEdit starts out saving a .rtf file, but if you add images to your document it needs to save a .rtfd file (which is actually a package containing the text and the attached image). The problem is that a sandboxed version of TextEdit only has access to myCoolFile.rtf not myCoolFile.rtfd and cannot make this change without prompting the user with a Powerbox panel.
Both of these situations can be resolved by using the related files api. This api allows your application to specify related file types in the info.plist. If you already have access to myCoolFile.rtf you can tell the NSFileCoordinator that you are going to move a file in your sandbox to a file with the same name but a different (related) extension. This will grant you access to the myCoolFile.rtfd.
The same technique can be used to export a resources folder along with a .html file. The trick is that you have to treat the resources folder as a related file to a .html file. This can be accomplished by naming the folder with a .resources extension. For example if .html and .resources files are listed as related in the applications info.plist you can allow the user to choose where to save the coolPage.html file and then also save the resources to a folder called coolPage.resources. As long as you tell the NSFileCoordinator that you are going to move coolPage.html it will allow you to write the resources as well.
I will follow up sometime soon with example code and how to structure the info.plist to save multiple files in a sandboxed application using the related files api.