This article explains how you can easily display user alert messages without using JavaScript's obtrusive alert() function.

Introduction

Google has posted the orkut Developer Guidelines for developers who build OpenSocial applications for the platform. These seem do be very good guidelines in general, not just for OpenSocial and not just for orkut (although some are very specific to the platform). The first "MUST" item in the user experience section reads:

That makes sense since alert boxes are horrible. Hence this small article will show you an easy way to include non-interruptive and unobtrusive error and info messages in your OpenSocial application.

Details

Prerequisites

This example uses the jQuery JavaScript library for some JavaScript luxury. Include it in the html section of your gadget xml so that it will look something like this:

  <?xml version="1.0" encoding="UTF-8"?>
  <Module>
      <ModulePrefs 
           title="My Great App">
          <Require feature="opensocial-0.7"/>
          <Require feature="dynamic-height" />
          <Require feature="views" />
      </ModulePrefs>
      <Content type="html" view="canvas">
          <![CDATA[
              <script src="http://YOURSERVER/jquery/jquery-1.2.3.min.js" type="text/javascript"></script>
              ...
              more includes and your html code
          ]]>

Now find a spot in the HTML markup of your application that would be a good place to display a message to the user. Most likely this will be somewhere near the top of the page. Insert this:

  <div style="text-align: center; width: 80%">
      <div id="msg-box" class="error-msg-box"> 
          <p><!-- msg goes here --></p>
          <input type="button" onclick="dismissMsg()" value="OK"/>
      </div>
  </div>

You must provide styles for both the error-msg-box and the info-msg-box CSS classes. Style it to your liking. These are two very simple styles for an error message box with a red border and an info message box with a green border:

  .error-msg-box {
                padding: 3px; 
                border: 2px solid #BB0000; 
                color: #BB0000; 
                width: 100%; 
                text-align: center; 
                display: none
        }    
        
        .info-msg-box {
                padding: 3px; 
                border: 2px solid #00BB00; 
                color: #00BB00; 
                width: 100%; 
                text-align: center; 
                display: none
        }

Now just add these four functions to your JavaScript:

  function showError(msg) {
        showMsg(msg, "info-msg-box", "error-msg-box");
  }

  function showInfo(msg) {
        showMsg(msg, "error-msg-box", "info-msg-box");
  }

  function showMsg(msg, oldClass, newClass) {
    $('#msg-box').removeClass(oldClass).addClass(newClass);
    $('#msg-box > p').html(msg);
    $('#msg-box').show('normal', function() {gadgets.window.adjustHeight();});
  }

  function dismissMsg() {
    $('#msg-box').hide('normal', function() {gadgets.window.adjustHeight();});
  }

That's it. Now you can call showError('Something went wrong!') from anywhere in your code and the user can click OK to dismiss the message. You can also dismiss the message programatically by calling dismissMsg() from your code. This even honors the second "MUST" of the User Experience section:

Always call the gadgets.window.adjustHeight() method when the application's content changes to prevent scrollbars from appearing.

As a last note: jQuery even nicely animates the message box when it appears or disappears.