So yesterday I began a short series on the Yahoo! User Interface or YUI for short.

I began with the tab view, and today I am going to talk about the connection manager.

The connection manager is not a control like the tab view or a dialog (which we will talk about tomorrow). It is basically how you make an asynchronous call to the server to get that whole “ajax” feel that everyone loves so much.

Here is an example from the real estate site I built.

var divCV = document.getElementById('divContactView');
        
function getContactsSuccessHandler(o)
{
    // Format and display results in the response container.
    divCV.innerHTML = o.responseText;
}

function getContactsFailureHandler(o)
{
    alert('failure');
    divCV.innerHTML = o.status + " " + o.statusText;
}

var oGetContactsCallback = {
    success: getContactsSuccessHandler,
    failure: getContactsFailureHandler
}
        
function getContactList()
{
    // entryPoint is the base URL
    var entryPoint = 'Commands/GetContactList.aspx';

    // Initiate the HTTP GET request.
    var request = YAHOO.util.Connect.asyncRequest('POST', entryPoint, oGetContactsCallback);
}

That is all there is to it…nothin’ too scary, but lets break it down to get a good feel for what is happening.

The first thing you see is me creating the variable divCV. This little guy is just a holder for where the goodies from my server will go. In the tab view code from yesterday you will notice that this is one of my tabs.

The Workhorse
Now lets jump down a bit and talk about the function getContactList(). We will get to the others shortly, but this is the workhorse of the connection manager, while the others are simply helpers. The cool thing is that even though this is the workhorse, there really isn’t much going on because the YUI is taking care of the heavy lifting.

In this method you will notice 2 things: a URL (called the entry point), and the asyncrequest.

The entrypoint is just what it sounds like. It is the page that this async request will be calling. If you need to send a query string, you can by just adding your variables to the URL like you would with any link.

The asyncrequest is where you tell the YUI that you would like to initiate an Ajax call. In this method call are 3 parameters.
1. ‘POST’ or ‘GET…this is just how you are submitting the form
2. Our entry point
3. oGetContactsCallback. This little object tells the request how to respond. You will see that I defined this object a little higher up. It has two simple properties, success and failure. Each of these properties in turn tells YUI what to do in each situation…essentially that means you are telling the framework what method to call in the event that the request is successful and what to do if everything goes boom.

Now, if you don’t want to use a query string to send stuff to the server, you can use an optional 4th parameter. This is basically a string that contains all the stuff you want to send to your server. An easy way to make use of this is to create a comma delimited string of name/value pairs and split them up on the server side.

Ajax Little Helpers
Now we are back to the little helpers we skipped over earlier. As stated before, these are methods that handle either success or failure of the request.

In my case I am simply writing out to my divCV variable the text that came back from the server. The server sends back an object (called o in my code). When things go right our object contains several nice properties, but we really only care about one of them (you can see the whole list here). The responseText property contains whatever we did on the server side of things (we will get to how to build this up in a few). So by placing that text into the innerHTML property of my div the content changes without having to reload the page. Nice.

When things go bad, our object contains different properties (here is the full list), but again, we are only using a couple. The status is a simple number that shows the status of the failed request. What is more useful is the statusText property. This guy tells you what happened. Now in my experience, this wasn’t all that informative. As usual, javascript error messages are cryptic at best, and useless most of the time. These messages aren’t much better, but at least you can show something to your users.

Sever Side
So that is great and all, but what about the back end? How do I load up the responseText in the first place? That is the easy part if you can believe it. Here is what my code looks like for GetContactList.

protected void Page_Load(object sender, EventArgs e)
{
     if (Session["AgentID"] == null)
         return;

     Response.Write(UICommand.GetContactList());
     Response.End();
}

Now this is written in C#, but it is applicable to any web language. Just put your code where it is the first thing that happens with the “entrypoint” page is loaded.

The first thing I am doing is checking a session variable to make sure that the person is logged in and is where they ought to be. After that is the meat of it. Response.Write simply writes out to the webpage. Every language has one or several of these little guys…echo, print, etc. Everything that you write to the page is what gets placed into the responseText.

So, in my case, my UICommand.GetContactList() method builds up a big string of contacts to be brought back to the front end. This contains fully compliant HTML, CSS, and even some javascript. If you can put it in a .html page, you can Response.Write it.

Once I am done I call Response.End. Again, this is a common method between the languages. It simply tells the page to stop processing and get out. Once that is called, the success portion of your callback object is triggered and your responseText is loaded. If something failed while building your string, then the failure will get triggered.

So there ya have it…the connection manager. Sure beats building your own ajax implementation! Tomorrow I will discuss the YUI Dialog control, which is a great way to get a desktop-esque feel to a web page.

If you get to trying any of these controls and methods I am writing about and you run into some trouble, shoot me a line and I will do my best to help.