TehNrd

Popups suck. Everyone hates them, but it wasn’t always like this. There once once a time long long ago when popup actually displayed relevant information related to the site you were browsing. This was in a time before tabbed browsing and advertising behemoths. Then came advertising on the web and popups galore. Here begins the downfall of the popup. It wasn’t long before popups became incredibly annoying and web users closed them without a glance. Popups were used, abused, and are now the scum of the internet user experience.

So why this brief, and quite frankly masterfully written story on the history of popups? The help link you can add to Visualforce pages is a popup. There are a few reasons I don’t like this. One, it is a popup, and people hate popups. Two, you also have to manage an entirely separate page for what could be a very simple help dialog. And 3, it just doesn’t provide a good user experience. It feels so 1999.

What made the original popup good? It provided relevant info without interrupting your main browser window. So how can we keep the good of the popup while eliminating the bad? Enter the popup’s little cousin, the modal box.

You may not know what a modal box is (but you probably do, as people who read this blog are freakin geniuses) but I can almost guarantee you have used one before. It is a dialog box that opens up within a page but is not your traditional popup or alert box. Often the background will become darker to make the box stand out. Some examples: digg.com login link, quicktime movie trailers, and the images in this post are all modal boxes.

So how do we make the help link open a modal dialog instead of a popup box? Enter jQuery, our night in shining armor. We will be able to do this faster than you can make a hot pocket or some other microwavable delicacy.

WARNING: What I am about to show you is not supported by salesforce.com and could break if they decided to change the styles or layout, blah blah blah more disclaimer speak. It currently works with the old and new UI.

Continue if you are not a fraidy cat.

The first thing we need to do is setup our visualforce page, very simple. See this post on setting up jQuery in salesforce.com

<apex:page>
    <apex:includeScript value="{!URLFOR($Resource.jquery, 'js/jquery-1.3.2.min.js')}"/>
    <apex:includeScript value="{!URLFOR($Resource.jquery, 'js/jquery-ui-1.7.2.custom.min.js')}"/>
    <apex:stylesheet value="{!URLFOR($Resource.jquery, 'css/ui-lightness/jquery-ui-1.7.2.custom.css')}"/>
 
    <script type="text/javascript">
		//This is where our jQuery code will go.
    </script>        
 
    <!-- This div represents our modal box that will pop up -->
    <div id="myCustomHelp" title="Help" style="display: none;">
        <p>You can put <strong>html</strong> here.</p>
        <p>An image.</p>
        <p>Or maybe a demo video.</p>
    </div>
 
    <apex:sectionHeader title="Help Link Override" help=""/>
</apex:page>

Next we need to figure out how to identify the help link and attach a click event to it so that when clicked it will open our modal box. To do this we will use Firebug. Using the inspect feature of Firebug we can see that the link is included within a div that has the class “bPageTitle”.

Yes, there are some other divs that are closer to the link but these have generic class names such as “links” we want to ensure we find a div that has a unique class name so that we don’t override other links. An element Id would be preferable but these elements don’t have Ids so we will use class name. Now that we know the DOM structure surrounding this link we can isolate the link and add a click event.

Next is the javascript code that will be placed between the script tags in the page above.

/*This to make sure jQuery doesn't conflict with any 
  JS libraries salesforce.com might be using.*/
var j$ = jQuery.noConflict(); 
 
j$(document).ready(function(){
	/*This block of code sets up our dialog 
	  box and all of the options.*/
 
	j$("#myCustomHelp").dialog({
		autoOpen: false,
		draggable: false,
		modal: true,
		resizable: false,
		width: 500
	});
 
	/*This block of code attaches a click event to the help link
	  to open the dialog box and prevent the default popup behavior.
	  The first line finds the element with class "bPageTitle" and then 
          finds all of the "a" tags within this element and adds a click event. */
 
	j$(".bPageTitle a").click(function(e){
		j$("#myCustomHelp").dialog('open');
		e.preventDefault();
	});
});

Now when you click the “Help” link you will see the the modal box instead of the traditional popup. This box can contain pretty much anything including images, text, links, or maybe a help video. Unfortunately I can’t show you a live demo as force.com sites do not render the help links but you can see what this looks like with the image below.