A picker interface for iOS system Twitter accounts: handles requesting access to Twitter, presenting the user with a list of accounts, and returning the user's chosen account to your code.

What it is

While iOS makes it very easy to fire off a tweet (using SLComposeViewController), it doesn't help you out too much when it comes to getting the user to pick from the list of Twitter accounts configured on the device.

RCRTwitterAccountPicker provides a simple way for your app to get hold of an ACAccount instance representing a Twitter account that the user wishes to use, for whatever purpose you you need it.

On devices with multiple configured Twitter accounts, RCRTwitterAccountPicker presents an interface with a list of accounts that the user may choose from. A ready-to-use interface can be used for this, or you can choose to provide you own.

On devices with only one account configured, RCRTwitterAccountPicker returns the account directly without asking the user to select from a 'list' of one.

If a device has no Twitter accounts configured, or the user has denied your app access to Twitter, then this information is returned to your calling code accordingly.

What it Depends on

RCRTwitterAccountPicker depends on Xcode 5 and higher (although note that the sample project is designed for Xcode 6 and will need modifying to work with Xcode 5).

RCRTwitterAccountPicker has been tested with iOS 7 and iOS 8 (note that the sample project has been designed for 8, but will run on 7).

All code uses ARC.

Note that RCRTwitterAccountPicker does not require a network connection itself, as everything happens on the device. However, adding Twitter accounts via the Settings app will require a working network connection (and of course your calling code may well do too).

How to Use it

Setup

First, add the RCRTwitterAccountPicker folder and code to your project.

Basic Use: Using the Standard Picker View Controller

The picker comes with everything you need to use it, including a view controller for listing Twitter accounts and allowing the user to select one. In this section we assume that you want to keep things simple and just use the built-in view controller (see the next section if you want to provide your own custom view controller).

One way to use the picker is as follows.

Let's assume you want to manage and run the picker from one of your app's view controllers. First, you'll need a couple of imports:

#import <Accounts/Accounts.h>
#import "RCRTwitterAccountPicker.h"

Next, add a property for the picker to your view controller:

@property (nonatomic, strong) RCRTwitterAccountPicker *twitterAccountPicker;

Then, when you need to get hold of a Twitter account, you can use some code along the lines of the following:

[self.twitterAccountPicker runPickerWithPresentingViewController:self completionHandler:^(BOOL granted, ACAccount *selectedAccount) {

    NSString *message;

    if (granted) {
        if (selectedAccount) {
            // We have an ACAccount instance representing the user's chosen Twitter account - we can now use this as we wish
            message = [NSString stringWithFormat:@"You selected Twitter account: %@", selectedAccount.username];
        }
        else {
            // selectedAccount is nil - there are no Twitter accounts configured on the device
            message = @"You do not have any Twitter accounts configured on this device";
        }
    }
    else {
        // granted is NO - the user has denied the app access to Twitter accounts
        message = @"You have not granted this app access to your device's Twitter accounts";
    }

    // This completion handler block will be run on an arbitrary queue, so we ensure we're on the main queue before updating the UI
    dispatch_async(dispatch_get_main_queue(), ^{
        [[[UIAlertView alloc] initWithTitle:@"Twitter Account Picker" message:message delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil] show];
    });
}];

Note that we pass the picker a reference to self, as the picker needs an existing view controller from which to present it's own picker view controller.

Then, we use the completionHandler parameter to provide a block of code to run when the picker is ready to return a value. The block's granted parameter signifies whether or not the user has allowed the app access to Twitter, and the selectedAccount parameter provides access to an ACAccount instance representing the Twitter account that the user has selected (or nil if there are no accounts configured on the device).

If granted is YES and we have a selectedAccount then we are good to go. Otherwise, we act accordingly.

In this example we simply display an alert that reports the result of the picker, displaying the Twitter username if we successfully get an account back from the picker.

Finally, note that the picker's completionHandler makes no promises regarding the queue it runs on - hence the call to dispatch_async() when updating the UI (displaying the alert).

Custom Use: Supplying Your Own View Controller

First, note that RCRTwitterAccountPicker is currently designed to work with view controllers with XIB files. If you know what you're doing, it will certainly be possible to use the picker without needing XIBs, but such usage is not covered in detail here.

There are two ways to provide your custom view controller. The first, and simplest, is to create a subclass of RCRTwitterAccountPickerViewController with a XIB whose view contains a table view. This scenario is detailed below.

The second option is to have your view controller conform to the RCRTwitterAccountPickerViewController protocol. This approach is the most flexible, and doesn't require you to subclass, use XIBs, or even table views. Whilst this approach is not discussed here, note that RCRTwitterAccountPicker has full documentation comments that provide detailed information on such usage.

So, assuming you're subclassing RCRTwitterAccountPickerViewController and using a XIB with a table view as described above, the steps for running the picker with your custom view controller are listed below. Note that these steps assume you are familiar with subclassing in Objective C, and the use of Interface Builder.

1. Create a subclass of RCRTwitterAccountPickerViewController, ensuring it has an associated XIB file.
2. Using Interface Builder, lay out your view however you like, with the only requirement being that it has a table view.
3. Set the data source and delegate of the table view to be your custom view controller (this will be File's Owner in Interface Builder).
4. Link the table view to the IBOutlet tableView property in the RCRTwitterAccountPickerViewController.h.
5. Have your view controller's init method call the initWithNibName:bundle: initializer on the superclass, passing in the name of your XIB via the first parameter.
6. Add any custom code to your view controller and override any UITableViewDataSource or UITableViewDelegate methods as per your requirements. Note: if you simply need a custom view then there may be no need to do anything here.
7. Use the initWithViewController: method when initializing the picker, passing in an instance of your custom view controller via the parameter.
8. You're done! Refer to the previous section for detailed information on how to use the picker and handle the results it returns.

Refer to the sample project for a working example of running the picker with a custom view controller in this way.

Sample Project

A sample project demonstrating working examples of both basic and custom uses of the Twitter account picker can be found in the RCRTwitterAccountPickerSample folder.

TODO

Some things that are planned for the future:

• Support for cancelling out of the picker view controller without picking an account.
• Support for pushing the picker view controller onto a navigation controller (currently it is presented/dismissed and not pushed).

License

MIT License (see LICENSE in the root of the repository).