Tutorial: Building Notifications

Introduction

In this tutorial we show some basic steps of using qx.Website. To do so, we build a simple notification system for web pages. The system should expose one method which brings up a bubble on the screen containing the notification message. The bubble should go away after a period of time. You might be familiar with Growl for OSX which offers similar functionality.

Basics

Let's get started! As qx.Website is a simple JavaScript file, we first need to download the script file. After that, we're going to create a simple HTML file in the same directory as the downloaded script and include it:

<!DOCTYPE html>
<html>
  <head>
    <title>qx.Website tutorial</title>
    <script type="text/javascript" src="q-5.0.2.min.js"></script>
  </head>
  <body>
  </body>
</html>

You can also use a version on a CDN. To do so, just include the following code instead of referencing the local script

<script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/qooxdoo/5.0.2/q.min.js"></script>

Having done that, you can load the page in your favorite browser and check if the title is there and the qx.Website library has been loaded. For instance, simply open a JavaScript console in your browser and see if q is defined. If so, we've completed the first step and can start building the application.

Next, we need a script tag to write our code into. To keep it simple, we'll just put it in the head of the HTML page, right below the existing script tag.

<script type="text/javascript" charset="utf-8">
  // your code here...
  console.log("it works");
</script>

The console.log statement in the script will show us if it works. Reloading the page should bring up the log message in the browser's console. Now it's time to formulate a simple plan covering the next steps. We should first create the popup we want to show, then we can implement the notify method and finally, we can add some demo code to showcase our work. The following code should be placed in the script tag to replace the previous content.

// create the notification popup
var popup;

// create the notification API
var notify = function(message, delay, callback) {
 // do the notifying
}

// DEMO
notify("This is ...", 1000, function() {
 notify("... a qx.Website notification demo.", 2000);
});

As you see, we've defined three arguments for the notify method: First, the message to display, second a delay in milliseconds and finally a callback function, which will be executed as soon as the popup is gone. The demo code at the bottom shows how it should be used and should trigger two messages in sequence.

notify

Next, let's implement the notify method. We already added the function and only need to fill in the implementation. First, we want to set the message and show the popup. But we want to show the popup with some style and fade it in.

var notify = function(message, delay, callback) {
  popup.setHtml(message);
  popup.fadeIn();
};

That was easy. The first line simply applies the message as inner HTML of the popup. The second line fades in the popup. This simple fadeIn applies a CSS animation in all browsers supporting CSS animations. If the browser doesn't support CSS animations, the fade in is done using JavaScript so you don't need to worry about that either! Reload the page and see your message in the popup fading in. As soon as the message is faded in, we should start a timer to trigger the fade out. But when does the animation end? Specifically for that, qx.Website offers an event named animationEnd which we can react to.

popup.fadeIn().once("animationEnd", function() {
  console.log("end");
});

Again, we used the native console API to check if our code works. Running the code now should show the end message in the console as soon as the popup is faded in. A little hint: Make sure you add the listener only once using the once method. We don't want to keep piling up listeners on the popup. Now we can start the timer which will be a simple setTimeout offered by the browser. As soon as the time is over, we can fade out.

popup.fadeIn().once("animationEnd", function() {
  window.setTimeout(function() {
     popup.fadeOut();
  }, delay);
});

Now we are almost there. The only thing missing is to execute the callback as soon as the fade out has ended. Again, we listen to the animationEnd event and call the callback. But as this should be an optional parameter, we should check its availability before executing.

popup.fadeIn().once("animationEnd", function() {
  window.setTimeout(function() {
     popup.fadeOut().once("animationEnd", function() {
       callback && callback.call();
     });
  }, delay);
});

Giving it a try should show both notification messages in sequence. Well done! We have implemented a (very) simple notification mechanism for web pages.

Summary

In this tutorial, we used a small part of the qx.Website API. First, we saw parts of the Manipulating module with q.create and .appendTo. After that, we used the CSS module with .setStyle and .addClass and the Attributes module with .setHtml. .fadeIn and .fadeOut are part of the Animation module and .once is part of the Event module. There are more methods in the named modules and there are additional modules you can experiment with.

|