This module provides helper functions for creating Local Notifications within your Titanium iOS project. The localNotify is meant to replace the existing Titanium Schedule and Cancel methods.
* You need Titanium 1.8.2 or greater.This module is freely available on github. Check the dist folder for a compiled release.
If you are building from source you will need to do the following:
- Modify the titanium.xcconfig file with the path to your Titanium installation
- Download the latest release from the dist folder or you can build it yourself.
- Install the bencoding.dictionary module. If you need help here is a "How To" guide.
- You can now use the module via the commonJS require method, example shown below.
var notify = require('bencoding.localnotify');
Now we have the module installed and avoid in our project we can start to use the components, see the feature guide below for details.
For detailed documentation please reference this project's documentation folder. A code "How To" example is provided in the app.js located in the project's example folder.
This method takes all of the same parameters as the [Titanium official API](http://docs.appcelerator.com/titanium/2.0/index.html#!/api/Titanium.App.iOS-method-scheduleLocalNotification), but does not return a notification object.
Because the notification object is not returned, you can schedule your notifications without requiring a background service. For example you can use the below code sample under a button click event.
The below sample shows you how to schedule a local notification to run in 30 seconds from now.
notify.scheduleLocalNotification({
alertBody:"This is a test of benCoding.localNotify",
alertAction:"Just a test",
userInfo:{"id":1,"hello":"world"},
date:new Date(new Date().getTime() + 30000)
});
alert("LocalNotification Scheduled");
The below sample shows how to create a callback that queries your scheduled local notifications. You can then loop through the results in your callback function.
//This is our callback for our scheduled local notification query
function localNotificationCallback(e){
Ti.API.info("Let's how many local notifications we have scheduled'");
Ti.API.info("Scheduled LocalNotification = " + e.scheduledCount);
alert("You have " + e.scheduledCount + " Scheduled LocalNotification");
var test = JSON.stringify(e);
Ti.API.info("results stringified" + test);
};
//Call this method and return a callback with the results
notify.activeScheduledNotifications(localNotificationCallback);
Simply call the returnScheduledNotifications method and you will be returned a collection with all of the available information about your scheduled local notifications.
The below sample shows how to get a resultset by using this method.
//Call this method to return a collection with information on your scheduled notifications
var results = notify.returnScheduledNotifications();
Ti.API.info("Let's how many local notifications we have scheduled'");
Ti.API.info("Scheduled LocalNotification = " + results.scheduledCount);
alert("You have " + results.scheduledCount + " Scheduled LocalNotification");
var test = JSON.stringify(results);
Ti.API.info("results stringified" + test);
The below sample shows how to get a resultset by using this method.
//Call this method to return a collection with information on your scheduled notifications
var results = notify.findLocalNotificationsByKey("foo","category");
Ti.API.info("Let's how many local notifications we have scheduled'");
Ti.API.info("Scheduled LocalNotification = " + results.scheduledCount);
alert("You have " + results.scheduledCount + " Scheduled LocalNotification");
var test = JSON.stringify(results);
Ti.API.info("results stringified" + test);
In the below example, a callback is returned with all notifications that have a userInfo.category property with a value of foo.
The below sample shows how to get a resultset by using this method.
//This is our callback for our scheduled local notification query
function localNotificationCallback(e){
Ti.API.info("Let's how many local notifications we have scheduled'");
Ti.API.info("Scheduled LocalNotification = " + e.scheduledCount);
alert("You have " + e.scheduledCount + " Scheduled LocalNotification");
var test = JSON.stringify(e);
Ti.API.info("results stringified" + test);
};
//Call this method and return a callback with the results
notify.searchLocalNotificationsByKey("foo","category",localNotificationCallback);
In the above scheduleLocalNotification example you see we use userInfo:{"id":1,"hello":"world"} when creating the notification.
The method cancelLocalNotification returns an integer with the number of scheduled notifications canceled. Since you can schedule one or more notifications with the same userInfo.id property this will let you know how many where removed without having to re-run the activeScheduledNotifications method.
The below sample shows how to cancel a local notification with the userInfo id property set to 1. After canceling we query the saved notifications to confirm the cancel was successful.
//We are going to remove all of the LocalNotifications scheduled with a userInfo id value of 1
var canceledCount = notify.cancelLocalNotification(1);
alert("You have canceled " + canceledCount + " notifications");
//Now query the scheduled notifications to make sure our local notification was canceled
notify.activeScheduledNotifications(localNotificationCallback);
In the above scheduleLocalNotification example you see we use userInfo:{"id":1,"hello":"world","category":"foo"} when creating the notification.
You can use any of the defined keys to cancel an event. In the below example, you see that a key of "category" is provided along with the value of "foo". This will remove all notifications that meet this criteria.
The method cancelLocalNotificationByKey returns an integer with the number of scheduled notifications canceled. Since you can schedule one or more notifications with the same property information this will let you know how many where removed without having to re-run the activeScheduledNotifications method.
The below sample shows how to cancel a local notification with the userInfo "category" property set to "foo". After canceling we query the saved notifications to confirm the cancel was successful.
//We are going to remove all of the LocalNotifications scheduled with a userInfo id value of 1
var canceledCount = notify.cancelLocalNotificationByKey("foo","category");
alert("You have canceled " + canceledCount + " notifications");
//Now query the scheduled notifications to make sure our local notification was canceled
notify.activeScheduledNotifications(localNotificationCallback);
Please note this method works the same as the native Titanium method discussed here.
The below sample shows how to cancel all scheduled local notifications.
//Cancel all scheduled local notifications
notify.cancelAllLocalNotifications();
This project is licensed under the OSI approved Apache Public License (version 2). For details please see the license associated with each project.
Developed by Ben Bahrenburg available on twitter @benCoding
Please consider following the @benCoding Twitter for updates and more about Titanium.
For module updates, Titanium tutorials and more please check out my blog at benCoding.Com.