00001 /** 00002 00003 Appigo Third Party Integration - AppigoPasteboard.h 00004 00005 Copyright (c) 2009-2010 Appigo, Inc. All rights reserved. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a copy 00008 of this software and associated documentation files (the "Software"), to 00009 deal in the Software without restriction, including without limitation the 00010 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 00011 sell copies of the Software, and to permit persons to whom the Software is 00012 furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00020 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 00023 IN THE SOFTWARE. 00024 00025 */ 00026 00027 00028 00029 /** 00030 @file AppigoPasteboard.h 00031 @brief A convenience class for importing tasks and notes into Appigo Todo and Appigo Notebook. 00032 00033 @class AppigoPasteboard AppigoPasteboard.h 00034 @brief A convenience class for importing tasks and notes into Appigo Todo and Appigo Notebook. 00035 00036 A convenience class that allows third party iPhone apps to import data into 00037 Appigo Applications via UIPasteboard objects. 00038 */ 00039 00040 /** 00041 @mainpage Overview 00042 00043 <strong>Appigo Third Party Integration</strong> is provided via a set of convenience classes by Appigo, Inc. which allow third party iPhone apps to import data into Appigo iPhone apps via persistent UIPasteboard objects. 00044 00045 <strong>Importing Tasks into Appigo Todo:</strong> 00046 - <strong>Basic Tasks</strong> 00047 @code 00048 // 00049 // Create a new task 00050 // 00051 AppigoTask *task = [[AppigoTask alloc] initWithName:@"My Task"]; 00052 00053 // 00054 // Set any desired properties such as due date, priority, etc. 00055 // 00056 task.dueDate = [NSDate date]; // today 00057 00058 // 00059 // Import the task into Todo 00060 // 00061 [AppigoPasteboard openTodoWithTask:task]; 00062 00063 // 00064 // Release the task object for good measure 00065 // 00066 [task release]; 00067 @endcode 00068 00069 - <strong>Projects and Checklists</strong> 00070 @code 00071 // 00072 // Create a new project task 00073 // 00074 AppigoTask *projectTask = [[AppigoTask alloc] initWithName:@"My Project"]; 00075 00076 // 00077 // Set the task type to project 00078 // 00079 [projectTask setType:AppigoTaskTypeProject withPropertyKeys:nil withPropertyValues:nil]; 00080 00081 // 00082 // Create and add subtasks to the project 00083 // 00084 // Note: Alternatively, you can create an NSArray of AppigoTask objects and 00085 // set them as subtasks of the project task by setting the subtasks property 00086 // of the project. 00087 // 00088 AppigoTask *subtask = [[AppigoTask alloc] initWithName:@"Subtask #1"]; 00089 00090 // ... set any desired subtask properties (not shown here) 00091 00092 [projectTask addSubtask:subtask]; 00093 [subtask release]; 00094 00095 subtask = [[AppigoTask alloc] initWithName:@"Subtask #2"]; 00096 [projectTask addSubtask:subtask]; 00097 [subtask release]; 00098 00099 // 00100 // Import the task into Todo 00101 // 00102 [AppigoPasteboard openTodoWithTask:projectTask]; 00103 00104 // 00105 // Release the project task object for good measure 00106 // 00107 [projectTask release]; 00108 @endcode 00109 00110 - <strong>Custom Tasks</strong> 00111 - See the @ref pageCustomTaskType "Custom Task Types" page for information on how you can create custom tasks to allow users of Todo to launch your application when they complete the task. 00112 00113 <strong>Importing a basic note into Appigo Notebook:</strong> 00114 @code 00115 // 00116 // Create a note 00117 // 00118 AppigoNote *note = [[AppigoNote alloc] initWithName:@"My Note Title"]; 00119 00120 // 00121 // Set the text of the note 00122 // 00123 note.text = @"Hello world."; 00124 00125 // 00126 // Import the note into Appigo Notebook. 00127 // 00128 [AppigoPasteboard openNotebookWithNote:note]; 00129 00130 // 00131 // Release the note for good measure. 00132 [note release]; 00133 @endcode 00134 */ 00135 00136 /** 00137 @page pageCustomTaskType Custom Task Types 00138 00139 <strong>Appigo Todo</strong> (beginning with version 3.2) allows third party 00140 apps to import custom task types. 00141 00142 <strong>What are custom task types?</strong> 00143 00144 Custom task types in Todo allow users to perform specific actions on a task 00145 while viewing its detail screen. For example, Todo offers built-in task type of 00146 "Call a Contact." When a user specifies a contact to call, the details of a 00147 task then have a special phone image at the top left which, when pressed, allow 00148 the user to place a phone call directly from Todo to the contact specified. 00149 When you import a custom task type into Todo, you have the ability to specify 00150 an icon and custom action. 00151 00152 The power of creating a custom task comes by using URLs which Todo will use 00153 when users complete tasks or perform their action. The 00154 setActionForTaskWithAppDisplayName: method in the AppigoTask class allows you 00155 to specify your app's display name, a series of URLs and an image that will be 00156 displayed in Todo when a user views the task. 00157 00158 For means of illustration, we'll show an example of how Appigo's AccuFuel 00159 (a fuel economy tracking app) might use this to set up a reminder task to 00160 change the oil in a vehicle. 00161 00162 @code 00163 00164 // 00165 // Create a new task 00166 // 00167 AppigoTask *task = [[AppigoTask alloc] initWithName:@"Jeep Liberty: Change Oil"]; 00168 00169 // 00170 // Set the due date to be due in 5 days from today 00171 // 00172 NSCalendar *calendar = [NSCalendar currentCalendar]; 00173 NSDate *today = [NSDate date]; 00174 00175 NSDateComponents *components = [[NSDateComponents alloc] init]; 00176 [components setDay:5]; 00177 00178 NSDate *inFiveDays = [calendar dateByAddingComponents:components toDate:today options:0]; 00179 task.dueDate = inFiveDays; 00180 [components release]; 00181 00182 // 00183 // These are the custom URLs that we want Todo to use when opening our 00184 // app. We will pass a reminder of "123" to Todo so that when the user 00185 // completes the task or performs the action on the task, AccuFuel will 00186 // be able to identify which reminder Todo is referring to. 00187 // 00188 NSURL *completionLaunchURL = [NSURL URLWithString:@"accufuel://com.appigo.todo.customtask/?method=task-completed&reminder-id=123"]; 00189 NSURL *actionLaunchURL = [NSURL URLWithString:@"accufuel://com.appigo.todo.customtask/?method=task-action&reminder-id=123"]; 00190 00191 // 00192 // Prepare the custom action image that Todo will display as a button 00193 // to the left of the task name when the user views the task. When the 00194 // user taps this button, the actionLaunchURL will be called. As 00195 // mentioned in the API documentation, this action image MUST be 29x29 00196 // pixels and MUST be in PNG format. Other sizes and types will be 00197 // ignored. 00198 // 00199 UIImage *actionImage = [UIImage imageNamed:@"accufuel-todo-action-image.png"]; 00200 00201 // 00202 // Set up the custom task 00203 // 00204 [task setActionForTaskWithAppDisplayName:@"AccuFuel" 00205 withCompletionNotifyURL:nil 00206 withCompletionLaunchURL:completionLaunchURL 00207 withActionLaunchURL:actionLaunchURL 00208 withActionImage:actionImage]; 00209 00210 // 00211 // Import this task into Todo 00212 // 00213 [AppigoPasteboard openTodoWithTask:task]; 00214 [task release]; 00215 00216 @endcode 00217 00218 */ 00219 00220 /** 00221 @page pageTaskTypeData Task Type Data 00222 00223 <strong>Appigo Todo</strong> stores corresponding task type data (phone 00224 numbers, addresses, email addresses, etc.) with a task. Todo also supports 00225 synchronizing this data with third party task management services via use of 00226 special identifiers in a task's note. 00227 00228 The AppigoTask class provides a convenience method 00229 (setType:withPropertyKeys:WithPropertyValues:) to simplify the process of 00230 specifying this task type data. 00231 00232 Task Type Data (keys and values) is used for the following task types: 00233 - AppigoTaskTypeCallContact 00234 - AppigoTaskTypeSMSContact 00235 - AppigoTaskTypeEmailContact 00236 - AppigoTaskTypeVisitLocation 00237 - AppigoTaskTypeURL 00238 00239 If keys and values are specified on any other task type, it will be ignored. 00240 00241 <strong>Task Type Data Keys</strong> 00242 00243 The property keys are meant to specify label items such as 00244 <strong>mobile</strong>, <strong>home</strong>, <strong>url</strong>, etc. 00245 These labels are shown to the user on the left side of a button in a 00246 UIActionSheet when the user taps the task's action button. 00247 00248 <strong>Task Type Data Values</strong> 00249 00250 The property values must correspond to the specified property keys and are the 00251 values of the labels. They should be phone numbers, email addresses, street 00252 addresses, etc. 00253 00254 <strong>Example:</strong> Creating a Call a Contact Task 00255 00256 @code 00257 00258 AppigoTask *task = [[AppigoTask alloc] initWithName:@"Call Bob Smith"]; 00259 task.dueDate = [NSDate date]; // today 00260 [task setType:AppigoTaskTypeCallContact 00261 withPropertyKeys:[NSArray arrayWithObjects:@"mobile", @"home", @"work", nil] 00262 withPropertyValues:[NSArray arrayWithObjects:@"555-555-1111", @"555-555-2222", @"555-555-3333", nil]]; 00263 00264 [AppigoPasteboard openTodoWithTask:task]; 00265 [task release]; 00266 00267 @endcode 00268 00269 */ 00270 00271 #import <UIKit/UIKit.h> 00272 00273 @class AppigoTask; 00274 @class AppigoNote; 00275 00276 00277 #pragma mark - 00278 #pragma mark General Constants 00279 00280 // iTunes App Store URLs for Appigo's Apps 00281 #ifdef IPAD 00282 #define kAppigoTodoAppStoreURL @"http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=371787147&mt=8" 00283 #else 00284 #define kAppigoTodoAppStoreURL @"http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=282778557&mt=8" 00285 #endif 00286 00287 #define kAppigoNotebookAppStoreURL @"http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=290089621&mt=8" 00288 00289 00290 00291 #pragma mark - 00292 @interface AppigoPasteboard : NSObject <UIAlertViewDelegate> 00293 { 00294 } 00295 00296 00297 #pragma mark - 00298 #pragma mark Task Methods 00299 00300 /** 00301 Set the Appigo Pasteboard task. 00302 00303 @param task The task to set/add to the Appigo Pasteboard to make it available to other applications. 00304 */ 00305 + (void)setTask:(AppigoTask *)task; 00306 00307 /** 00308 Get the currently available task from the Appigo Pasteboard. 00309 00310 @return Returns the currently available task from the pasteboard or nil if no task is currently present. 00311 */ 00312 + (AppigoTask *)task; 00313 00314 /** 00315 Get the currently available task from a specific pasteboard. 00316 00317 @param pasteboardName The name of the specific pasteboard to look for a task. 00318 @return Returns the currently available task from the specified pasteboard or nil if no task is available on the specified pasteboard. 00319 */ 00320 + (AppigoTask *)taskFromPasteboardNamed:(NSString *)pasteboardName; 00321 00322 /** 00323 Launch Appigo Todo and import the specified task. 00324 00325 @param task The task to import into Appigo Todo. 00326 @return Returns NO if Todo was unable to be launched. Check the console log for the specific reason. In most cases, the user likely does not have Appigo Todo (or Appigo Todo Lite) installed. We recommend using a UIAlertView to prompt the user about this (and offer a direct link to the App Store for them to download/purchase Notebook). Samples of how to do this are available in CustomTask (a sample third party app which demonstrates how to use Appigo's Third Party Integration). 00327 */ 00328 + (BOOL)openTodoWithTask:(AppigoTask *)task; 00329 00330 00331 #pragma mark - 00332 #pragma mark Note Methods 00333 00334 /** 00335 Set the Appigo Pasteboard note. 00336 00337 @param note The note to set/add to the Appigo Pasteboard to make it available to other applications. 00338 */ 00339 + (void)setNote:(AppigoNote *)note; 00340 00341 /** 00342 Get the currently available note from the Appigo Pasteboard. 00343 00344 @return Returns the currently available note from the pasteboard or nil if no note is currently present. 00345 */ 00346 + (AppigoNote *)note; 00347 00348 /** 00349 Get the currently available note from a specific pasteboard. 00350 00351 @param pasteboardName The name of the specific pasteboard to look for a note. 00352 @return Returns the currently available note from the specified pasteboard or nil if no note is available on the specified pasteboard. 00353 */ 00354 + (AppigoNote *)noteFromPasteboardNamed:(NSString *)pasteboardName; 00355 00356 /** 00357 Launch Appigo Notebook and import the specified note. 00358 00359 @param note The note to import into Appigo Notebook. 00360 @return Returns NO if Notebook was unable to be launched. Check the console log for the specific reason. In most cases, the user likely does not have Appigo Notebook installed. We recommend using a UIAlertView to prompt the user about this (and offer a direct link to the App Store for them to download/purchase Notebook). Samples of how to do this are available in CustomTask (a sample third party app which demonstrates how to use Appigo's Third Party Integration). 00361 */ 00362 + (BOOL)openNotebookWithNote:(AppigoNote *)note; 00363 00364 00365 #pragma mark - 00366 #pragma mark Global Settings 00367 00368 /** 00369 Specify whether the AppigoPasteboard should automatically handle showing an 00370 alert if the user does not already have the target Appigo app installed when 00371 calling openTodoWithTask: or openNotebookWithNote:. 00372 00373 @param showAlertsAutomatically A BOOL value to specify whether to show alerts. 00374 By default, this is set to YES. Specify NO to handle informing users yourself. 00375 */ 00376 + (void)setShowErrorAlertsAutomatically:(BOOL)showAlertsAutomatically; 00377 00378 00379 @end