nvdnkpr / localnotify

Extends & provides helpers for Titanium Mobile's LocalNotifications

benCoding.localNotify Module

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.

Before you start

* You need Titanium 1.8.2 or greater.

Download the release

This module is freely available on github. Check the dist folder for a compiled release.

Building from source?

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

Setup

• 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.

benCoding.localNotify How To Example

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.

Methods

---

scheduleLocalNotification

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");

activeScheduledNotifications

You can use this method to query your scheduled local notifications. Simply call this method and provide a callback method similar to what is shown below. The callback will be returned a collection with all of the available information about your scheduled local notifications.

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);

returnScheduledNotifications

This method allows you to query your scheduled notification similar to activeScheduledNotifications but without the callback.

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);	

findLocalNotificationsByKey

This method allows you to query your scheduled notification similar to activeScheduledNotifications but with using a value and key combination. This method will return all notifications that has a matching UserInfo with the provided value and key combination. In the below example, we return 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.

	//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);

searchLocalNotificationsByKey

This method works in the same way as findLocalNotificationsByKey, but provides a callback method.

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);

cancelLocalNotification

This method allows you to cancel a specific scheduled local notification using the userInfo dictionary. To do this we use the convention of providing an id within the userInfo dictionary upon notification creation.

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);

cancelLocalNotificationByKey

This method allows you to cancel a specific scheduled local notification using any key defined in the userInfo dictionary.

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);

cancelAllLocalNotifications

This method cancels all scheduled local notifications.

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();

Licensing & Support

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

Learn More

---

Twitter

Please consider following the @benCoding Twitter for updates and more about Titanium.

Blog

For module updates, Titanium tutorials and more please check out my blog at benCoding.Com.