Writing Desktop Alerts
 


Getting a Dripline
Registering a Dripline Channel
Using the Dripline Channel
The Dripline CGI Script

The Droplets Platform Dripline is a mechanism for delivering a variety of client-side desktop alerts, regardless of whether the Droplets application is currently on or off. This document is intended as an introduction for programmers who wish to write Dripline alerts into their Droplets, and presents the essential steps in integrating a dripline into your Droplet. More detailed information on working with the Dripline class can be found in our API documentation for both Java and C++.

There are four essential steps in using a dripline in your Droplets:

  1. Get a Dripline within your Application class;
  2. Register a Dripline Channel in your start() method;
  3. Use this registered Dripline Channel as appropriate in your application logic;
  4. Create a CGI script for desktops alerts when application is closed.

1. Get a Dripline within your Application class

Within your Application (Java) or TDsApplication (C++) class, call the Application's getDripline() method, which has no arguments. So if we have named our application "App", the code would look like this:

Java: Dripline dripline = app.getDripline();
C++: TDsDripline& dripline = App->GetDripline();


2. Register a Dripline Channel in your start() method

Every Droplet that features a Dripline must include a start() method in the Application/TDsApplication class that registers at least one Dripline Channel within it (multiple Channels may be registered if necessary). There is no need to destroy this channel later. So if you have created a Dripline instance called "dripline", your registration would take the following form:

Java: dripline.registerChannel(String driplineChannelId, String driplineChannelName,
String driplineChannelDescription, String driplineChannelQuestion, String driplineChannelPollingUrl, boolean registrationForced);

C++: dripline.RegisterChannel(string DriplineChannelId, string DriplineChannelName, string DriplineChannelDescription, string DriplineChannelQuestion, string DriplineChannelPollingUrl, bool RegistrationForced);

The Dripline class API documentation gives full details on the purpose of each of these arguments. The majority of them are text to be presented in various circumstances, while the driplineChannelPollingUrl is the URL which the Droplet will poll for alerts whenever the application is offline (more on that in the final section).

The first argument, driplineChannelId, deserves special notice. If you use more than one dripline alert in a single application, it is important that each much have a unique Channel ID; you should assign it a name that's guaranteed to be both unique and human-readable.

At this point you may also want to get a Channel Token via a call to the Dripline's channelToken method. A Channel Token is a string value that is placed on the client-side computer, and can be used only in conjunction with a Dripline; this allows you to place the time and date of the end-user's last application session and based on this determine in your application logic whether or not a desktop alert is appropriate.

In order to get a Channel Token, make the following call immediately after registerChannel:

Java: dripline.setChannelToken(String driplineChannelId, String token);
C++: Dripline.SetChannelToken(string DriplineChannelId, string Token);

The first string argument should be identical to the first argument of your registerChannel call, while the second should be the exact text to be contained in the client-side token.

Once the Channel Token has been created, you can pass it to the client-side in your application logic in order to determine whether a desktop alert is necessary. Consult the Droplet SDK API Reference for details.


3. Use the registered Dripline Channel as appropriate in the application logic

The only remaining task is to use the Droplets API to place desktop alerts into your program logic as appropriate. The API has full details on this, and it is a fairly straightforward task. If you wish, for example, to send an icon to the client-side system tray whenever an end-user has new mail, you simply call the Dripline's alertWithIcon method and pass it the appropriate information:

Java: dripline.alertWithIcon("com.mycompany.email.channelone", "GotNewMail.ico", "New Mail!", "NewMail.wav", "");
C++: Dripline->AlertWithIcon("com.mycompany.email.channelone", "GotNewMail.ico", "New Mail!", "NewMail.wav", "");

One note on the second argument, alertIcon. This argument informs the Droplets Client of the icon's location. If the alertIcon string begins with "http:/", the Droplets Client treats the string as a URL address and attempts to fetch the icon there; otherwise, the icon is fetched from the application's imagejar.


You can also combine multiple alerts to create whatever custom effects you need. For example, if you wanted the Droplet to (1) show a static icon in the system tray whenever it is on, and (2) show an animated icon (two or more rotating images) that takes over in the system tray whenever the end-user has new mail, you would first call showIcon() so that an icon is placed in the system tray upon application start-up:

Java: dripline.showIcon("com.frats.mycompany.channelone", "Mail.ico", "Email", "");
C++: dripline->showIcon("com.frats.mycompany.channelone", "Mail.ico", "Email", "");

In order to replace the static icon with the animated "New Mail" icon, you now create an event listener (or other polling mechanism) to listen on the database for new email messages; and a method that is called whenever that event is triggered, which should include the following line:

Java: dripline.alertWithAnimatedIcon("com.mycompany.email.channelone", "GotNewMail1.ico" + '\t' + "GotNewMail2.ico", 500, "New Mail!", "NewMail.wav", "");

C++: Dripline.AlertWithAnimatedIcon("com.mycompany.email.channelone", "GotNewMail1.ico" + '\t' + "GotNewMail2.ico", 500, "New Mail!", "NewMail.wav", "");

The arguments to this method are explained in detail in the API documents for the Dripline class. Once this step has been accomplished, you will then need to register for an event listener that waits for the end-user to read their new mail and then calls a readNewMail() method in response; within this method, you reinstate the initial, static icon by re-calling showIcon().


4. Create a CGI script for desktop alerts when application is closed

If your Droplets application includes alerts to the desktop that run even when the application is closed, you will also have to write a small Web page with CGI logic (ASP, Perl or the like) that will reside on your deployment's Web server (its default location is DropletConfig/apps/[application name]/dripline; full deployment details are provided in Deploying the Web server). This is necessary because there is no notion of a server session when a user is not logged in, and no information about them currently stored in the Droplets Server. The alert therefore has to use persistent data, generally from a database. Your CGI script will perform this function when the application is closed; it is defined as an argument when you first call dripline.registerChannel().

This CGI will be called by the client-side polling agent at regular intervals as determined by your program logic. Each time it is polled, it receives:

AlertChannelID A string uniquely identifying a particular channel. A single Droplets application may use more than one channel for different purposes. Each channel ID needs to be unique among channel ids from a specific server. For that reason, we recommend including the application name in the ID, as well as descriptive text. For instance, "Email-NewMail".

AlertChannelToken The Channel Token is a string assigned by the Droplets application and may be used for whatever purpose the developer sees fit. For instance, it could contain the user ID associated with this dripline request, or the time at which the application was last closed, so that the alert logic can distinguish between new information and old.


The CGI in turn should include logic for doing the following two things whenever it is polled by a client:

1. Check the Droplets UI Server's associated database, and altering its own parameters based on what it finds.

This typically involves pulling data from the database, comparing that data to the information in the Channel Token and determining whether an alert is appropriate based on this comparison. For example, if your Droplet was an email program that sent desktop alerts to the client machine whenever a new message arrived, the Channel Token passed to the CGI script might include the email account ID and time at which the user last viewed a message. The CGI script would then pull a list of messages from the database, and determine if any of them had arrived since the application was closed.

2. Return a series of plaintext name/value pairs via an HTTP Post.

These name/value pairs take the following format:


 alert=1
 popup=1
 nextpoll=+5
 icon=http://www.mycompany.com/images/email1.ico
      http://www.mycompany.com/images/email2.ico
 message=You Have New Mail!
 animate=500
 sound=newmail.wav
  bgimage=http://www.mycompany.com/alertpopup.bmp
 popuptime=5

alert: A boolean value. True if the the client polling agent should display a desktop alert. False if it should not.

popup: Also boolean. Combine popup=1 with alert=1 if you want the alert to be a popup.

nextpoll: Number of seconds the client polling agent should wait before polling the CGI script again.

icon: location of the icon file(s) to be displayed on the client-side. If the value begins with "http:/", the client polling agent will treat this value as a URL; if not, the client polling agent will assume that the file is to be found in the application's imagejar. If this value is null (""), there will be no alert. When used with popup alerts, this icon will appear at the top left corner of the popup window.

message: The text (if any) to be displayed as a "Tool Tip" when a mouse runs over the alert icon in the system tray. When used with a popup alert, this text will appear within the popup window. In this case, use \n to break lines.

alertid: Use alertid to reset the channel token from the alert CGI.

animate: Used when there are multiple icons to be rotated for animated effects. The integer value is the number of milliseconds between rotations (so 500 means that the icons will be rotated twice per second). Leave blank if the icon is static.

sound: The .wav file to be played on the client machine when the desktop alert first arrives. Leave blank if no sound effects.

bgimage: This variable is for use with popup alerts. It should be set to the URL of a bmp image which will tile across the background of the popup. If it is a relative URL it will be looked up in the imagedir of the Droplet associated with this alert channel. To make the Dripline prepend the imagedir from the associated Droplet and look up the resulting image assign it the value bgimage=alertpopup.bmp

popuptime: For use with popup alerts. Its value equals the number of seconds for which the popup will continue to appear before it is auto-dismissed. Thus popuptime=5 indicates that the popup will continue to appear for five seconds before being dismissed. The value -1 means that it must be dismissed manually.

startdroplet: If startdroplet=1, the Droplets application starts up immediately. Use in conjunction with splash=0 and a nice transition effect to get a popup whose content is a full fledged Droplets application.

splash: Set splash=0 to cause the Droplets splash screen to be hidden during startup.

Full deployment details for both the CGI script and all aspects of the Dripline can be found within Deploying the Web server.

 Return to Droplets SDK Documentation Home