Cephi Systems Software and Contract Services

Property Lists in Objective-C

If you are new to Objective-C, property lists (plists for short) can be an unfamiliar concept. Opening a .plist file with a text editor will reveal that they closely resemble XML files. A plist is just a data file: it stores data in the form of serialized objects in a standardized format and structure. This standardization is important since plists can be read by any application designed to read them. Put another way, an application expects the data in the plist to be organized in a certain way (a structure). If the application does not see the plist in the correct structure then it will probably throw an exception.

Here is an example of the source code of a simple plist holding two people's personal information:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <array>
        <dict>
            <key>name</key>
            <string>Bob Johnson</string>
            <key>payGrade</key>
            <integer>5</integer>
            <key>weight</key>
            <real>175.5</real>
        </dict>
        <dict>
            <key>name</key>
            <string>Mike Smith</string>
            <key>payGrade</key>
            <integer>2</integer>
            <key>weight</key>
            <real>475.5</real>
        </dict>
    </array>
</plist>

When viewed as a plist file in Xcode, this plist will appear as follows:

Like XML files, plists consist of data elements which hold content (elements of your data). In the above example there is a hierarchy of data elements: an array as the root property-list object (the top-level container), then each individual person is represented by a dictionary object. Each dictionary then holds some data elements: a string for the person's name, a floating point number (the tag) for the person's weight, and an integer for their pay grade. Each element is denoted or wrapped by tags, and each must have an opening and closing tag or the application will consider the plist invalid.

Example:

<string>Bob Johnson</string>

So the tags are enclosed in the <>'s, with the opening tag coming first and the closing tag with a backslash being at the end of your content. When you instruct your application to reference the object corresponding to the name key, it will return a copy of the object between the tags, in this case Bob Smith (technically I believe it returns formatted data which is then converted into an object by the app/OS.) If you want to see more examples of how XML files are organized see the links at the end of this article.

Once your data is in a plist it can be written to disk, or sent across the internet to communicate with a another application or server. Plists are designed to be storable, transportable and easily accessible. Plists often hold a dictionary object such as with the Info.plist, but you can set your plist up to hold objects such as an array, an array of dictionaries, a dictionary of arrays, or whatever is convenient for you. When you create a plist in Xcode the default root property-list object (the top level or root container) is a dictionary ready to contain other objects. Through Xcode's plist editor you can add new rows that can be dictionaries, arrays, booleans, strings, dates, numbers, or data (NSData objects).

If you want something other than a dictionary as your root property-list object you cannot currently do this though Xcode's plist editor (as of version 4.0.2). You do this by editing the source code instead. This is done by right clicking on the Plist file in Xcode's project manager window and selecting “Open As” then “Source Code.” You then see the source code as shown at the top of this article. The default location for plist files is in the Supporting Files folder and they are identifiable by the .plist file extension.

In iOS devices, like the iPad and iPhone, applications have a default info-plist which stores information (metadata) about the application such as bundle names, its icon, and supported interface orientations. This plist is named [the application name]-Info.plist. This information is read by the operating system and is used to display and configure the application.

Having problems with your plist? This can be caused by the syntax being incorrect such as a misspelled or missing tags, putting a string inside an integer element, or an invalid character somewhere. When you try to build and run the application containing the plist, Xcode will give an “error: reading plist: The data couldn’t be read because it has been corrupted.” Checking the source code for the plist as explained above is a good way to see what the problem is.

Plists are pretty easy to use and are good for storing up to a few hundred kilobyets of data per Apple. You have a choice between saving your plist in either an XML or a binary format. The tradeoff between these two choices is XML formats can be manually edited, but binary formats have the advantages of being more compact, consuming less memory and they read/write faster, so binary formats may be better for working with larger amounts of data. You can also save your plists in an old-style ASCII format that is most commonly associated with the OpenStep API specification.

In addition to creating a plist in Xcode, plists can also be created programmatically. Below is a simple example of how to programmatically create, populate, and save a plist and then reference it by copying its contents to a dictionary:

-(void) createPlist
{
    //Get the path to the document directory in your app bundle:
    NSString *path = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
    //Add the name your plist will be saved as:
    NSString *plistPath = [path stringByAppendingPathComponent:@"myPlist.plist"];
    //Make a dictionary that holds 2 strings
    NSDictionary *dictForPlist = [NSDictionary dictionaryWithObjects:[NSArray arrayWithObjects: @"string 1", @"string 2", nil]forKeys:[NSArray arrayWithObjects: @"Key 1", @"Key 2", nil]];

    NSError *error;
    //Create a plist with the data from the dictionary
    //For the error we pass a pointer to a pointer so new NSError objects can be referenced rather than altering an existing NSError object.
    NSData *plistData = [NSPropertyListSerialization dataWithPropertyList:dictForPlist format:NSPropertyListXMLFormat_v1_0 options:0error:&error];
    
    //If plistData exists, save it as a plist file.
    if(plistData) 
    {
        [plistData writeToFile:plistPath atomically:YES];
        //This is written to the application bundle document directory:
        NSLog(@"plistPath %@",plistPath);
    }
    else 
    {
        NSLog(@"Something went horribly wrong: %@", [error localizedDescription]);
    }
    
    //Reterive the data from the plist, and put it in a mutable dictionary so we reference or manipulate the objects within:
    NSMutableDictionary *myDict = [[NSMutableDictionary alloc] initWithContentsOfFile: plistPath];
    NSLog(@"myDict %@",myDict);
    
    //Since we alloc'ed a mutable dictionary we should release it when done with it: 
    [myDict release];
}

Links:

More about XML: http://www.w3schools.com/xml/xml_syntax.asp

Apple's Property List Programming Guide:
https://developer.apple.com/library/ios/#documentation/Cocoa/Conceptual/PropertyLists/Introduction/Introduction.html#//apple_ref/doc/uid/10000048-CJBGDEGD