Message in a Bottle

Gone are the days when you had to use something like that. No more messages in a bottle and no there are no Ghosts in the Machine. For those with a keen eye and ear might have noticed that these are titles of songs from the Police. So what does that have do with our quest in learning Lua? What do you do when you have an issue that requires the law to intervene? You *Notify* the Police. Phew, to get a word, I had to go that long way...

Well, what if we could get our messages and instead of them being delivered in a bottle all of them delivered via notifications? Locally?? That's what the latest feature from CoronaSDK is, Local Notifications, it is available in the Daily Builds, which means not for general consumption, if you are a subscriber, you can take advantage of that and download it today. Let us look at what and how of the Local notifications.

What is a local notification

Local notification is a popup that appears when you are on the home screen, i.e. your app is in the background. Think of it as a reminder that you might have set for a particular time. These notifications will appear like an alert box while you are on the Home Screen, or running another app. (I have yet to try it on iOS 5 to see if the notifications go to the new Notification area or show up as popups). The notifications can feature adding Badges, these are the numbers that you can see on top of the icon, If you have used an iPhone, you must definitely have seen the badge on the Mail Icon, showing you how many new unread mail sit in your Inbox, or the updates for installed apps on the app store. A custom sound could be played when the notification is received and you can also pass custom data that can be used to display the notifications.

How do I use it?

First things first, you cannot test this in the Corona Simulator as it requires the iOS platform either on the Device or on the xCode simulator to run. So it will be a bit of compiling and deployment to test this.

In line with the CoronaSDK theory of One like of code, it is simple...

 local myNotification = system.scheduleNotification( 60, options )

what this line does is schedules a new notification to appear in 60 seconds and the options are what you can pass to the notification. The structure of the notification has four named items, namely the message for the alert, the number to update the badge with, the sound you want to play and then a userdefined variable that can also be a table, thereby allowing you to pass a lot more.

local options = {
        alert = "Wake up!",
        badge = 2,
        sound = "alarm.caf",
        custom = { anythingYouWant = "Corona SDK Rocks!" }
    }

When invoked, this is what the notification would look like

The notification here is seen popping up while running another application and offers two options, to either dismiss the notification or view it, viewing means to invoke the app that spawned the notification.

There is a small glitch that could be a bug or maybe something that I got wrong in the code. The documentation on Ansca's site states that the badge variable is used as an additive value than an absolute value, which means that if the badge said 3, and you run it again with a badge value of 2, it would now update to 5, but having run the above code several times, I should have had the badge increasing in increments of 2, but it remained constant at 2.

Video to demonstrate that can be seen here

which brings us to the next part,

How do we handle the notification?

Well, like anything we need to handle the event, so we need an eventHandler, such as

        local function notificationListener( event )
        print( event.name )     -- "notification"
        print( event.custom.anythingYouWant )   -- "Corona SDK Rocks!"

        -- Do something ...
    end

and to set the eventHandler to capture the events, we use

   Runtime:addEventListener( "notification", notificationListener )

Now, before you run that code and come back with the point that this notification is not handled, well, for starters, the print statements are *never* seen from the xCode simulator, sometimes I wonder why does Ansca code even feature that when there is no point in those print statements, unless there is a way that they look at those.

Instead use

native.alert(event.name, event.custom.anythingYouWant, {"OK"})

which will show as a popup.

Secondly, the default behaviour of a Corona App is to terminate the moment the home button is pressed, so it does not go into the background mode, unless it is set via the settings using a build.settings file.

This code is for a feel of what the notifications are like and how they interact from within a coronaSDK app. For a more comprehensive sample, keep an eye out, maybe we will integrate it within a utility app for all to test.

Hope you have fun testing the notifications