Today’s guest tutorial comes to you courtesy of Ingemar Bergmark, a Corona Enterprise developer. He has a background in the UNIX world as a DBA/Systems Analyst using Informix and Oracle, and has been programming for 25 years. His programming interests started when he built his first computer, a Sinclair ZX-80. He has been interested in game development since his early teens, however he was mostly interested in writing graphics SDKs for his friends since the days of the Hercules Graphics Card. Only recently that he’s ventured out on his own into the world of game development. He’s the owner of Swipeware, an independent studio in Siheung, South Korea. Current titles include those listed on his website www.swipeware.com.
Would you like to open an email attachment with your own custom extension directly in your app? Today’s tutorial explains how to set up your iOS build settings, send the file to your app’s Documents directory, and use the launchArgs URL to get the file’s path so you can work with it in Corona.
1. Register the Extension in build.settings
First, you’ll need to register your extension in the plist section of your build.settings. This involves the addition of two tables and several parameters within each.
- CFBundleDocumentTypes defines your custom extension.
- UTExportedTypeDeclarations tells iOS about your custom extension so that other apps (like Mail) will present the option to open the file in your app.
In the following example, you’ll register a custom file extension of “wxyz“. Inspect the build.settings modifications:
Let’s investigate the CFBundleDocumentTypes table and its specific parameters:
- CFBundleTypeIconFiles — an array of strings containing the names of the image files to use for the document icon. For further details on the size and specifications for these images, please refer to Apple’s guidelines here.
- CFBundleTypeName — the “abstract” name for the document type, used to refer to the type. This key is required. In our example, we’re using “wxyz File“.
- CFBundleTypeRole — specifies the app’s role with respect to the type. The value can be Editor, Viewer, Shell, or None. This key is required and we’ll specify it to Viewer.
- LSHandlerRank — determines how this app ranks among the apps that declare themselves editors or viewers of files of this type. Possible values, and the order of precedence, are: Owner, Alternate, None. In this example we’ll use Owner, indicating that this app is the creator of files of this type.
- LSItemContentTypes — an array of strings; each one must contain a UTI (Uniform Type Identifier) defining a supported file type. For a detailed description of UTI concepts, please refer to Apple’s guidelines here. In this case, we specify the app’s bundle identifier plus our desired file extension of .wxyz.
Now, let’s investigate the UTExportedTypeDeclarations table and its parameters (complete reference can be found here):
- UTTypeConformsTo — an array of strings; each string identifies a UTI to which this type conforms. These represent the parent categories to which the custom file format belongs. For example, a JPEG file conforms to the public.image and public.data types. For a complete reference, please see Apple’s documentation here.
- UTTypeDescription — An “abstract” user-readable description of this type.
- UTTypeIdentifier — The UTI associated with the type. In this case, we’ll match the app’s bundle identifier plus our desired file extension.
- UTTypeTagSpecification — A dictionary defining at least one equivalent type identifier. The key-value pairs identify the filename extensions, MIME types, OSType codes, and pasteboard types that correspond to this type.
2. Build Handler Functions
Next, you’ll need to build the handler functionality into your app. Inspect the following code carefully:
The sample code above doesn’t do anything fancy. It simply displays the path to your imported file in the Documents directory. Let’s have a look at what’s happening:
- First, we use … which is Lua syntax that returns a table with arguments passed to your app by the system.
- Following that is a utility function that extracts and returns the path to your file in the Documents directory.
- Next, we check for launch arguments. If the .url passed to the app begins with “file://“, we know that we’re trying to handle a custom extension. The .url part can also be used to handle URL schemes, but that’s explained in a different tutorial here.
- Two display objects are then created for the purpose of showing the path to the file that was imported into the app.
- Since our app can suspend to the background, we need a way to detect when the app resumes with an attachment. This is done by adding an event listener for the system event. The event type we look for is applicationOpen.
After you’ve implemented all of the code above, check and re-check every setting. Then, send yourself an email with an attachment that has a “wxyz” extension.
Now, on your device, open the Mail app, select the email that you just sent, and “tap-and-hold” the attachment. You should see your app’s name in the “Open in” dialog pop-up. Select your app from the list and the app should open, with the file in your Documents directory for further processing!
For the next stage, I am working on a process that should be able to import data (attachments) received from other people and parse the data into an SQLite database. When it’s complete, this will allow people to send data in the form of attachments that can then be easily imported into the app. In the meantime, I hope this tutorial gets you started with the concept of sharing and accessing email attachments in Corona.