An iOS (Objective-C) Wrapper for the Trello API
Objective-C C
Switch branches/tags
Nothing to show
Latest commit 5fff297 Jun 8, 2012 Vince Mansel Added GET /1/members/[member_id or username]/boards/[filter]
* updated README v0.1.1

README.md

ios-trello (v0.1)

An iOS (Objective-C) API Wrapper for Trello

Trello is a free, collaborative task management web tool that can be used for anything. Really! Check it out here. This project contains sources to enable you to build Trello into your native iOS projects. It is basically an API wrapper that makes it easy for your app to login and send GET, PUT, POST and DELETE HTTP signals to your available and authorized Trello boards.

Load up the included iPad demo/test project in your simulator, and take ios4trello for a spin. (See Client Source Configuration below to obtain keys!).

The Trello API Reference is here.

The demo is based on the Trello API, AFNetworking (for transport) and ytoolkit/NSMutableURLRequest (for basic OAuth). You can use any OAuth library you want, but ios-trello is closely tied to AFNetworking through a few Macros.

Here is the pattern to get a list of boards (with a name that starts with a variant of "MyProject") from Trello. It is up to you how you parse, handle and display the JSON that is returned. This examples stores the names into an NSArray model called boardList, and the ids into an NSArray called boardIDs.

- (void)loadFeedStream {
    if (self.accesstoken && self.tokensecret) {
    
        [[VMTrelloApiClient sharedSession] getMemberMyBoardsWithSuccess:^(id JSON) {
             [self parseJSONforMyProjectBoards:JSON];
             [self.tableView reloadSections:[NSIndexSet indexSetWithIndex:0] withRowAnimation:UITableViewRowAnimationAutomatic];
         }
         failure:^(NSError *error) {
             [VMTrelloApiClient operationDidFailWithError:error title:@"Trello" message:Network_Authorization_Error_Please_login]; 
             NSLog(@"Authorization Error: %@", error.description);
         }];
    }
}

- (void)parseJSONforMyProjectBoards:(id)JSON
{
    //NSLog(@"Name: %@ %@", [JSON valueForKeyPath:@"name"], [JSON valueForKeyPath:@"memberships"]);
    //NSLog(@"JSON: %@", JSON);
    if (YIS_INSTANCE_OF(JSON, NSArray)) {
        [self.boardList removeAllObjects];
        for (id item in JSON) {
            if (YIS_INSTANCE_OF(item, NSDictionary)) {
                NSString * boardName = [item objectForKey:@"name"];
                if (YIS_INSTANCE_OF(boardName, NSString)) {
                    if (   [boardName rangeOfString:@"[MyProject]"].location == 0
                        || [boardName rangeOfString:@"MyProject:"].location  == 0) {
                        [self.boardList addObject:boardName];
                        [self.boardIDs addObject:[item objectForKey:@"id"]];
                        NSLog(@"boardName: %@, id = %@", boardName, [self.boardIDs lastObject]);
                    }
                }
            }
        }
    }
}

Assuming you have those listed in a tableView, here is how to access one board and list the cards on that board.

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    NSLog(@"Board = %@", [self.boardList objectAtIndex:indexPath.row]);
    
    [[VMTrelloApiClient sharedSession] 
     get1Boards:[self.boardIDs objectAtIndex:indexPath.row]
     success:^(id JSON) {
         NSLog(@"Board:JSON = %@", JSON);
     } failure:^(NSError *error) {
         NSLog(@"Board JSON Error: %@", error.description);
     }];
    
    [[VMTrelloApiClient sharedSession] 
     get1BoardsCards:[self.boardIDs objectAtIndex:indexPath.row]
     success:^(id JSON) {
         NSLog(@"BoardCards:JSON = %@", JSON);
     } failure:^(NSError *error) {
         NSLog(@"BoardCards JSON Error: %@", error.description);
     }];
}

Here's how to get going...

Additional Sources Required:

Dependencies:

  • ytoolkit (OAuthv1) (http://github.com/sprhawk/ytoolkit)
  • (Note: for expendiency, delete all test directories, SenTesting Framework and ASIHTTPRequest files from ytoolkit)
  • (If you are not linking against the static library, you may also need to fix some fix some imports: i.e. change <ytoolkit/ydefines.h> to "ydefines.h" ... etc. Let the compiler be your guide ;)

Demo Configuration

The included Xcode Project is an iPad app that exercises the Trello API.

  1. Under Project > ios-trello > Linking > Other Linker Flags, Double-Click then click + to set flags
-ObjC
-all_load
  1. Under Targets > ios4trello > Build Phases > Target Dependencies, Click + and Choose items to add:
  • (ytoolkit > ytoolkit)
  1. Under Targets > ios4trello > Build Settings > Search Paths > Header Search Paths, enter:
{BUILT_PRODUCTS_DIR}/usr/local/include
  1. Under Targets > ios4trello > Build Phases > Compile Sources, Double-click the following source files, and add the flag:
-fno-objc-arc
  • All AFNetworking .m Sources (10 files)
  • All ytoolkit .m library Sources (11 files)
  • Reachability.m

Additional Frameworks and Libraries:

Under Targets > ios-trello > Build Phases > Link Binary with Libraries:

  • IOS 5.1
  • SystemConfiguration
  • Security

Client Source Configuration

  1. If you haven't already, create a Trello account.

  2. Go to Trello Docs and generate an Application Key

  3. Edit/Create the file TrelloClientCredentials.m and substitute your keys.

  4. (See Demo): In TrelloLoginViewController.m, globally substitute Your_App_Name for ios4Trello. (This will let your users know that your app is seeking authorization to access thier Trello account.)

Keeping it real and live

Here's our Trello Board which tracks development and features of ios-trello.

This library is not complete (see status below), so if you do find anything missing or not functioning as you would expect, please let us know.

And by all means, pitch in. What would you like to add to the project? Feature requests, pull-requests, tests, docs, examples are all welcome.

Peace!

Roadmap/Implementation Status

The Trello API (Beta) is functional with on-going development and is fairly complete (as far as I know). This is the map/status for ios-trello.

  • 0.1 - Basic read-only API, create board, edit board description, create list, create card
  • 0.2 - support additional read-only methods (i.e. all GET methods)
  • 0.3 - support additional, create, update and delete
MethodVersion
Actions
GET /1/actions/[action_id] 0.1 - IMPLEMENTED
GET /1/actions/[action_id]/[field] 0.2
GET /1/actions/[action_id]/board 0.2
GET /1/actions/[action_id]/board/[field] 0.2
GET /1/actions/[action_id]/card 0.2
GET /1/actions/[action_id]/card/[field] 0.2
GET /1/actions/[action_id]/list 0.2
GET /1/actions/[action_id]/list/[field] 0.2
GET /1/actions/[action_id]/member 0.2
GET /1/actions/[action_id]/member/[field] 0.2
GET /1/actions/[action_id]/memberCreator 0.2
GET /1/actions/[action_id]/memberCreator/[field]0.2
GET /1/actions/[action_id]/organization 0.2
GET /1/actions/[action_id]/organization/[field] 0.2
Boards
GET /1/boards/[board_id] 0.1 - IMPLEMENTED
GET /1/boards/[board_id]/[field] 0.1 - IMPLEMENTED
GET /1/boards/[board_id]/actions 0.1 - IMPLEMENTED
GET /1/boards/[board_id]/cards 0.1 - IMPLEMENTED
GET /1/boards/[board_id]/cards/[filter] 0.2
GET /1/boards/[board_id]/cards/[idCard] 0.2
GET /1/boards/[board_id]/checklists 0.2
GET /1/boards/[board_id]/lists 0.1 - IMPLEMENTED
GET /1/boards/[board_id]/lists/[filter] 0.2
GET /1/boards/[board_id]/members 0.2
GET /1/boards/[board_id]/members/[filter] 0.2
GET /1/boards/[board_id]/membersInvited 0.2
GET /1/boards/[board_id]/membersInvited/[field]0.2
GET /1/boards/[board_id]/myPrefs 0.2
GET /1/boards/[board_id]/organization 0.2
GET /1/boards/[board_id]/organization/[field] 0.2
PUT /1/boards/[board_id] 0.3
PUT /1/boards/[board_id]/closed 0.3
PUT /1/boards/[board_id]/desc 0.1 - IMPLEMENTED
PUT /1/boards/[board_id]/name 0.1.1 - IMPLEMENTED
POST /1/boards 0.1 - IMPLEMENTED
POST /1/boards/[board_id]/checklists 0.3
POST /1/boards/[board_id]/lists 0.1 - IMPLEMENTED
POST /1/boards/[board_id]/myPrefs 0.3
Cards
GET /1/cards/[card_id] 0.1 - IMPLEMENTED
GET /1/cards/[card_id]/[field] 0.2
GET /1/cards/[card_id]/actions 0.2
GET /1/cards/[card_id]/attachments 0.2
GET /1/cards/[card_id]/board 0.2
GET /1/cards/[card_id]/board/[field] 0.2
GET /1/cards/[card_id]/checkItemStates 0.2
GET /1/cards/[card_id]/checklists 0.2
GET /1/cards/[card_id]/list 0.1 - IMPLEMENTED
GET /1/cards/[card_id]/list/[field] 0.2
GET /1/cards/[card_id]/members 0.2
PUT /1/cards/[card_id] 0.3
PUT /1/cards/[card_id]/closed 0.3
PUT /1/cards/[card_id]/desc 0.1 - IMPLEMENTED
PUT /1/cards/[card_id]/due 0.3
PUT /1/cards/[card_id]/idList 0.3
PUT /1/cards/[card_id]/name 0.3
POST /1/cards 0.1 - IMPLEMENTED
POST /1/cards/[card_id]/actions/comments 0.3
POST /1/cards/[card_id]/attachments 0.3
POST /1/cards/[card_id]/checklists 0.3
POST /1/cards/[card_id]/labels 0.3
POST /1/cards/[card_id]/members 0.3
POST /1/cards/[card_id]/membersVoted 0.3
DELETE /1/cards/[card_id] 0.1.1 - IMPLEMENTED
DELETE /1/cards/[card_id]/checklists/[idChecklist] 0.3
DELETE /1/cards/[card_id]/labels/[color] 0.3
DELETE /1/cards/[card_id]/members/[idMember] 0.3
DELETE /1/cards/[card_id]/membersVoted/[idMember] 0.3
Checklists
GET /1/checklists/[checklist_id] 0.2
GET /1/checklists/[checklist_id]/[field] 0.2
GET /1/checklists/[checklist_id]/board 0.2
GET /1/checklists/[checklist_id]/board/[field] 0.2
GET /1/checklists/[checklist_id]/cards 0.2
GET /1/checklists/[checklist_id]/cards/[filter] 0.2
GET /1/checklists/[checklist_id]/checkItems 0.2
PUT /1/checklists/[checklist_id] 0.3
PUT /1/checklists/[checklist_id]/name 0.3
POST /1/checklists 0.3
POST /1/checklists/[checklist_id]/checkItems 0.3
DELETE /1/checklists/[checklist_id]/checkItems/[idCheckItem] 0.3
Lists
GET /1/lists/[list_id] 0.1 - IMPLEMENTED
GET /1/lists/[list_id]/[field] 0.2
GET /1/lists/[list_id]/actions 0.2
GET /1/lists/[list_id]/board 0.2
GET /1/lists/[list_id]/board/[field] 0.2
GET /1/lists/[list_id]/cards 0.2
GET /1/lists/[list_id]/cards/[filter] 0.2
PUT /1/lists/[list_id] 0.3
PUT /1/lists/[list_id]/closed 0.3
PUT /1/lists/[list_id]/name 0.1.1 - IMPLEMENTED
POST /1/lists 0.1 - IMPLEMENTED
POST /1/lists/[list_id]/cards 0.1 - IMPLEMENTED
Members
GET /1/members/[member_id or username] 0.2
GET /1/members/[member_id or username]/[field] 0.2
GET /1/members/[member_id or username]/actions 0.2
GET /1/members/[member_id or username]/boards 0.1 - IMPLEMENTED
GET /1/members/[member_id or username]/boards/[filter] 0.1.1 - IMPLEMENTED
GET /1/members/[member_id or username]/boardsInvited 0.2
GET /1/members/[member_id or username]/boardsInvited/[field] 0.2
GET /1/members/[member_id or username]/cards 0.2
GET /1/members/[member_id or username]/cards/[filter] 0.2
GET /1/members/[member_id or username]/notifications 0.2
GET /1/members/[member_id or username]/notifications/[filter] 0.2
GET /1/members/[member_id or username]/organizations 0.2
GET /1/members/[member_id or username]/organizations/[filter] 0.2
GET /1/members/[member_id or username]/organizationsInvited 0.2
GET /1/members/[member_id or username]/organizationsInvited/[field] 0.2
PUT /1/members/[member_id or username] 0.3
PUT /1/members/[member_id or username]/bio 0.3
PUT /1/members/[member_id or username]/fullName 0.3
PUT /1/members/[member_id or username]/initials 0.3
Notifications
GET /1/notifications/[notification_id] 0.2
GET /1/notifications/[notification_id]/[field] 0.2
GET /1/notifications/[notification_id]/board 0.2
GET /1/notifications/[notification_id]/board/[field] 0.2
GET /1/notifications/[notification_id]/card 0.2
GET /1/notifications/[notification_id]/card/[field] 0.2
GET /1/notifications/[notification_id]/list 0.2
GET /1/notifications/[notification_id]/list/[field] 0.2
GET /1/notifications/[notification_id]/member 0.2
GET /1/notifications/[notification_id]/member/[field] 0.2
GET /1/notifications/[notification_id]/memberCreator 0.2
GET /1/notifications/[notification_id]/memberCreator/[field] 0.2
GET /1/notifications/[notification_id]/organization 0.2
GET /1/notifications/[notification_id]/organization/[field] 0.2
Organizations
GET /1/organizations/[org_id or name] 0.2
GET /1/organizations/[org_id or name]/[field] 0.2
GET /1/organizations/[org_id or name]/actions 0.2
GET /1/organizations/[org_id or name]/boards 0.2
GET /1/organizations/[org_id or name]/boards/[filter] 0.2
GET /1/organizations/[org_id or name]/members 0.2
GET /1/organizations/[org_id or name]/members/[filter] 0.2
PUT /1/organizations/[org_id or name] 0.3
PUT /1/organizations/[org_id or name]/desc 0.3
PUT /1/organizations/[org_id or name]/displayName 0.3
PUT /1/organizations/[org_id or name]/name 0.3
PUT /1/organizations/[org_id or name]/website 0.3
POST /1/organizations 0.3
DELETE /1/organizations/[org_id or name] 0.3
Tokens
GET /1/tokens/[token] 0.2
GET /1/tokens/[token]/[field] 0.2
GET /1/tokens/[token]/member 0.2
GET /1/tokens/[token]/member/[field] 0.2
DELETE /1/tokens/[token] 0.1 - IMPLEMENTED
Types
GET /1/types/[id] 0.2

Credits

ios-trello and ios4trello were developed by Vince Mansel (http://github.com/vincemansel)

Additional sources are attributed to the following projects.

  • AFNetworking
  • ytoolkit
  • Roadmap Table Layout (thanks trello4j)

Thanks, Vince