<?xml version="1.0" encoding="utf-8"?>
<html>
Version|opensocial-0.7|opensocial-0.8
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:
| Panel |
|---|
Always include error handling routines to generate a user-friendly message. HTML alert boxes are strongly discouraged as they're interruptive. |
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.
...
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:
| Panelcode |
|---|
<?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs <Module> <ModulePrefs title="My Great App"> <Require <Require feature="opensocial-0.7"/> <Require <Require feature="dynamic-height" /> <Require <Require feature="views" /> </ModulePrefs> <Content <Content type="html" view="canvas"> <![CDATA[ <script <script src="http://YOURSERVER/jquery/jquery-1.2.3.min.js" type="text/javascript"></script> ... more includes and your html code 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:
...
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:
| Panelcode |
|---|
.error-msg-box{ { padding: 3px; border: 2px solid #BB0000; color: #BB0000; width: 100%; text-align: center; display:none } none } .info-msg-box{ { padding: 3px; border: 2px solid #00BB00; color: #00BB00; width: 100%; text-align: center; display:none } none
}
|
Now just add these four functions to your JavaScript:
| Panelcode |
|---|
function showError(msg){ { showMsg(msg, "info-msg-box", "error-msg-box"); } |
...
} function showInfo(msg) |
...
| Panel |
|---|
{ showMsg(msg, "error-msg-box", "info-msg-box"); } |
...
} function showMsg(msg, oldClass, newClass) |
...
| Panel |
|---|
{ $('#msg-box').removeClass(oldClass).addClass(newClass); $('#msg-box > p').html(msg); $('#msg-box').show('normal', function() {gadgets.window.adjustHeight();}); } |
...
} function dismissMsg() |
...
| Panel |
|---|
{ $('#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.
Author Bio
I'm Johannes Fahrenkrug, a freelance software dude and security consultant. I started full time freelancing in the summer of 2007. Now I enjoy making the newest technologies usable to my customers. I have a fascination for learning new languages and frameworks. My languages of choice are Ruby, Objective-C/Cocoa and JavaScript at the moment. I live with my lovely wife Simone in Northern Germany. You can contact me through my website freelance writing.
</html>