Following on from the Exporting for iPhone Tutorial this addition will show you how to bundle additional files with your iPhone app. Why would you want to do this? Perhaps you’ve built your app using external resources such as XML data and/or images and you wish to load them at runtime to give you greater flexibility to change the content while developing. This could be the case when you have built a dynamic framework that can be repackaged for another purpose by swapping some external files.
A lot of the time you can load these remotely from a server online, but unless it’s necessary you might not want to require an internet connection to use your app, so storing locally on the user’s device could make sense. They would probably thank you also for not eating up their data allowances. There are two matters when setting about to do this, the first is to bundle the actual files, and the second is to actually access them from with your app as it runs on the device.
Bundling the files
In order to include extra files into your IPA compilation you need to tell the packager which files to include. If you’ve followed the previous tutorial you will be using the Air 2.7 iOS project for flash develop. Once you’ve created your project and you’re getting ready to package everything up you’ll need to make a slight change to your PackageApplication.bat file. Open the file up in your favourite editor (You can do this within FlashDevelop) and we need to edit one line. Look for the line (line 59) that appears something like this:
call "%FLEX_SDK%adt.bat" -package %SIGNING_OPTIONS% iphone/myawesomeapp-%IPATYPE%.ipa application.xml bin/myawesomeapp.swf bin/icons Default.png
This is the line that makes the actual call to compile and amongst other things it specifies which are the files to include in the package. This is where you need to enter in the locations of the files you wish to include. Now as far as I can tell you need to enter the file, separated by a space, right at the end of this command – but just before “Default.png”. This may or may not be a bit of voodoo but it’s working for me so I’ll just stick with that. The good news is that if you have a bunch of images or other files in the one directory you don’t need to enter in each filename one at a time as you can include entire directories also. Remember that all of these filepaths will be relative to the PackageApplication.bat file so if you’ve got a folder named “images” in your “bin” folder (using the project template package you would have downloaded from the earlier tutorial) you would add in “bin/images”. Here’s an example of how this command might look for my imaginary awesome app:
call "%FLEX_SDK%adt.bat" -package %SIGNING_OPTIONS% iphone/myawesomeapp-%IPATYPE%.ipa application.xml bin/myawesomeapp.swf bin/icons bin/images bin/content.xml Default.png
As you can see there I’ve added a folder called images and also an XML file called content.xml which I will use to determine the filenames and locations of the images to load in.
After this you can package as normal and the files will be bundled with your IPA.
Accessing your external files from the device
Once you’ve bundled your files and they are successfully installed onto your device you’ll want to be able to access them. This is pretty much the same as how you might normally do it using URLRequest and URLLoader except for a small difference in specifying the file path. By using the Air specific File class functions we can determine the location of your files in the devices file system, and then from that point you can load as normal.
There are probably a few ways to achieve this and the File class has quite a ot of useful functionality which you can read about here.
My personal approach to this is to save a reference to the “bin” folder in my app and then use it as a prefix to all of the file paths I use for my external files. To do this I used the following:
var myFile:File = File.applicationDirectory; myFile = myFile.resolvePath("bin"); _prefix = String(myFile.url)+"/";
This code is using the File.applicationDirectory function to find the app’s location on the device and then using the resolvePath function to find the “bin” folder within this and convert that location to a string. Finally I add a trailing slash and then store this location as a prefix to use for all my external files calls.
for this example the next step is to load in the content.xml file, which has a filepath of: _prefix+”content.xml” and then I can load in the images specified by that file as I wish. One thing to note is that I made the XML file specifically use relative paths so that I could append them to the _prefix value and get a valid location. Using an absolute path wouldn’t have worked (or made any sense anyway).
So there you go, that’s all there is to it. It’s quite straight forward but I didn’t find much concise information about it when I searched so I hope that makes things easier for anyone else out there trying to do the same thing.
