Namely, these features were nothing more than implementing the IComparable<T> and IEquatable<T> interfaces.

Upon further investigation, I’ve found that there is no need to implement IEquatable<T> here, as we’ll see in an example in just a moment.

Also, I’m not sure how often we’d find ourselves needing to sort collections of our enum-esque class.

Here’s the original class from the previous post:

The ‘Enum’ Class

This will be our baseline to begin implementing the interface(s):

public class UselessItem
{
    public string ItemName { get; private set; }
    public Guid ItemId { get; private set; }

    private UselessItem() { }

    private UselessItem(string itemName, Guid itemId)
    {
        ItemName = itemName;
        ItemId = itemId;
    }

    // Define the 'Enum' members
    public static UselessItem MacBook =
        new UselessItem("MacBook/MacBook Pro", new GUID("EAD0014A-3733-DD11-9DCA-0019B9B42749"));

    public static UselessItem ScreenDoorOnASubmarine =
        new UselessItem("Screen Door on a Submarine", new GUID("EAD0014A-3733-DD11-9DCA-0019B9852F2E"));

    public static UselessItem DehydratedWater =
        new UselessItem("Dehydrated Water", new GUID("EAD0014A-3733-DD11-9DCA-0019B2635342"));
}

Again, if you’d like to re-familiarize yourself with the above code and its features, check out the original post: Typesafe Enum Pattern in C#/VB.NET.

Do We Need IEquatable<T>?

See for yourself:

var ui1 = UselessItem.MacBook;
var ui2 = UselessItem.DehydratedWater;

var r1 = (ui1 == UselessItem.MacBook);  // r1 = true
var r2 = (ui1 == ui2); // r2 = false
var r3 = (ui2 == UselessItem.MacBook); // r3 = false

This behaves just as a normal Enum would. Clearly, there is no need to implement IEquatable<T> in this case.

Do We Need IComparable<T>

IComparable<T>, on the other hand, might prove useful if we ever find ourselves wanting to sort an Array, etc, of UselessItem pseudo-Enums.

Without implementing IComparable<T>, we are not able to do:

var uis = new[]
              {
                  UselessItem.MacBook,
                  UselessItem.DehydratedWater,
                  UselessItem.ScreenDoorOnASubmarine,
                  UselessItem.MacBook
              };

var s = string.Empty;

foreach (var ui in uis)
{
    s += ui.ItemName + " ";
}

// s = MacBook DehydratedWater ScreenDoorOnASubmarine MacBook

// And this won't work (yet):
Array.Sort(uis, (ui1, ui2) => ui1.CompareTo(ui2));  // CompareTo not defined for type UselessItem!

Implementing IComparable<T>

IComparable<T> is definitely one of the easier interfaces to implement – it only requires the implementation of a single method:

int CompareTo(T other);

CompareTo returns:

See MSDN’s Entry on IComparable<T> for more information.

This mechanism is what allows, for example, Array.Sort() to work easily with a simple lambda expression.

So let’s implement it!

// The 'enum' members have been omitted for brevity
public class UselessItem : IComparable<UselessItem>
{
    public string ItemName { get; private set; }
    public Guid ItemId { get; private set; }

    private UselessItem() { }

    private UselessItem(string itemName, Guid itemId)
    {
        ItemName = itemName;
        ItemId = itemId;
    }

    // Implementing interface method here
    public int CompareTo(UselessItem other)
    {
        return this.ItemName.CompareTo(other.ItemName);
    }

// ... snip ...

In line 18, you can see that we want to be able to sort by our ItemName property. Sorting the GUID ItemIDs is probably something of little interest, but it certainly can be done as well. In fact, this pattern can be used to make our enum-esque Class sortable by whatever property/datatype we might need for our purposes.

Let’s try a sample sort:

var uis = new[]
              {
                  UselessItem.MacBook,
                  UselessItem.DehydratedWater,
                  UselessItem.ScreenDoorOnASubmarine,
                  UselessItem.MacBook
              };

var s = string.Empty;

foreach (var ui in uis)
{
    s += ui.ItemName + " ";
}

// s = MacBook DehydratedWater ScreenDoorOnASubmarine MacBook

// Now this works!
Array.Sort(uis, (ui1, ui2) => ui1.CompareTo(ui2));

s = string.Empty;

foreach (var ui in uis)
{
    s += ui.ItemName + " ";
}

// s = DehydratedWater MacBook MacBook ScreenDoorOnASubmarine

// Sort in the other direction
Array.Sort(uis, (ui1, ui2) => ui2.CompareTo(ui1));

var s2 = string.Empty;

foreach (var ui in uis)
{
    s2 += ui.ItemName + " ";
}

// s2 = "ScreenDoorOnASubmarine MacBook MacBook DehydratedWater"

Not too shabby!

Conclusion

Well, we haven’t added a ton of real-world useful functionality to our enum-esque Class, though it was an easy way to demonstrate the implementation and usefulness of IComparable<T>. Initially, I had thought that implementing IEquatable<T> was also necessary to do simple operations such as:

var ui1 = UselessItem.DehydratedWater;

if (ui1 == UselessItem.MacBook)
{
    Console.WriteLine("Sorry you ended up w/a MacBook! Dehydrated Water is slightly more useful!");
}
else
{
    Console.WriteLine("Your item might be worthless, but at least it's not a MacBook!");
}

But, as it turns out, the nature of our enum-esque class gives us the above capability out-of-the-box.

And free stuff, that works as expected? A rarity these days!

In a nutshell, source control allows us to keep a historical record of any changes we’ve made to files over the course of time. This is beneficial because if multiple people are working on the same project, it can be very easy to accidentally overwrite someone else’s changes that you may not have been aware of. It also gives some peace of mind to know that copies of your teams’ work are safe from accidental local deletion, corruption, and other such maladies.

The source control system that we will be using today is known as Subversion.

Subversion (SVN) is an open-source, widely used, and in my experience, very solid choice for a version control system (VCS). To be sure, there are many others out there, such as Git, Mercurial, Team Foundation Server, CVS… the list goes on.

We’re going to quickly learn how to get an SVN server up and running on your Windows box with the aid of two software packages: VisualSVN Server and TortoiseSVN (which will serve as our client).

First, let’s grab these two packages – try and be sure to grab the latest stable release offered at each site.

VisualSVN Server: http://www.visualsvn.com/server/download/

TortoiseSVN: http://tortoisesvn.net/downloads.html

Installing VisualSVN Server

Fire up the VisualSVN Server installer that you downloaded from the above link. Follow the on-screen prompts – the default settings should be fine. Once that’s done, it should offer to take you right to the VisualSVN Server Manager Console – click OK and we’ll find ourselves at a screen that should look similar to:

The next step is to create at least one user and one repository:

Creating a new user couldn’t be simpler – just decide on a username and enter/confirm a password.

Setting up a new repository is equally simple – all you need to do at this point is give it a name, preferably something meaningful to you and your team. For now, don’t worry about the ‘Create default structure’ checkbox and make sure that it’s not checked.

And that’s it! Told you it was simple!

Installing and Using TortoiseSVN

Again, first step will be to run the TortoiseSVN installer that you downloaded earlier. Just accept any default settings. Once the installer is done, it will prompt you to reboot – go ahead and do so.

Once back in Windows, we find that our right-click context menu has some new additions:

Next, we’ll want to create a folder to create what is known as our ‘working copy’ of the project that will now be under source control.

In whatever location you deem appropriate, create a new folder, preferably with a name that matches the name of the repository you created earlier in VisualSVN Server.

Once that’s done, right click the new folder, and then click on ‘SVN Checkout…’ in the context menu, which brings us to:

All that’s needed for this screen is to type the URL of the repository you’ve created. I’m using localhost here, and this may or may not work. If it does not, replace localhost with the name of your machine.

Finally, replace where I show ‘Site1′ with the name of the repository you created earlier.

Leave all other settings as they are, then click OK.

Because we’re connecting over SSL, TortoiseSVN will prompt you about whether or not you want to accept the security certificate. Choose ‘Accept Permanently’ and you’ll be good to go for now and in the future.

Now, you have an active ‘working copy’ that is under version control by SVN!

Adding Project Files to SVN

If you already have an existing project, made up of files and directories, the first step will be to copy those items to the folder you just did the SVN Checkout to.

Note that it is easy to tell at a glance what folders/files are under source control, and what their current status is:

So, let’s add some files to our working copy folder and place them in to the repository.

The first step is to select the files that you want to place in the repository by first selecting those files/folders, right clicking your selection, and choosing TortoiseSVN -> Add…

Which brings us to:

Leave everything checked, then click OK.

TortoiseSVN will show the progress of the Add – if everything went ok, it should say so. Click OK to close the window.

Note that now each file/folder icon will be overlaid with a blue plus sign, indicating that it has been added but not committed.

The final step is to Commit these added files/folders by again, first selecting the ones you’ve just added, right-clicking that selection, and choosing ‘SVN Commit…’:

Which brings us to:

The area circled in red above is a text area to enter a log message detailing what you are committing. Personally, I think it best to always try to include some meaningful comment about what you’ve included/changed in the commit.

Messages like: ‘Pulled the javascript out of index.html and placed it in scripts/myscript.js” can definitely be of help.

Though the log message is optional for us, some shops may require a log message on each commit.

Don’t be lazy – always enter a commit log message!

Once you’re done entering your message, click OK. TortoiseSVN will show the progress of the commit, ending with a display of what revision you are now on. Since this was the very first commit, it makes sense that you should see that you are now at Revision 1.

Day to Day Usage of SVN

Frequently Updating and Commiting your project files is an excellent habit to get into. We already know what a Commit does, and I bet you can guess what an Update does.

To try it, select any files you’d like to have the latest copy of so that you can be sure that you’ve picked up any changes by other members of your team. Right click these selected files and click SVN Update…

Since you are the only one who has committed anything to this point, you’ll see that nothing has changed and that you are still on Revision 1.

Next Steps

Add more users, one for each member of your team.

Add more repositories, one for each of your projects.

Individually make and commit changes, being sure to update after each one to ensure you have the latest code.

Experiment with features such as ‘Locking’ which will prevent other team members from modifying the locked file until you release that lock.

Hopefully this has been of some use to you CVS n00bs out there – next time, we’ll go over conflict resolution, an important tenet of version control.

First, let’s create a simple Enum:

// C#
public enum UsefulItem {
    Unknown = 0,
    Foo,
    Bar,
    Baz
}

' VB.NET
Public Enum UsefulItem
    Unknown = 0
    Foo
    Bar
    Baz
End Enum

From here on out, we’ll stick to C# in these examples (VB.NET source available for download soon!).

A recent project prompted me to create a number of Enums, as I have done in the past in many other projects.

For this project, however, I had a desire to have tighter control over the usage of the Enum type, as it dawned on me that:

var ui1 = UsefulItem.Foo;
var ui2 = (UsefulItem) 256;

var s1 = ui1.ToString(); // s1 = "Foo"
var s2 = ui2.ToString(); // s2 = "256"

Ok, well that’s kinda disconcerting, but I’m sure .NET has a library function to check if an Enum value is defined. Not surprisingly, they do, and even less suprisingly, it is:

Enum.IsDefined(Type enumType, Object value)

Works great:

var ui1 = UsefulItem.Bar;
var ui2 = (UsefulIem) 1;  // Equal to 'Foo'
var ui3 = (UsefulItem) 256; // Again, undefined

var r1 = Enum.IsDefined(typeof(UsefulItem), ui1); // r1 = true
var r2 = Enum.IsDefined(typeof(UsefulItem), ui2); // r2 = true
var r3 = Enum.IsDefined(typeof(UsefulItem), ui3); // r3 = false

No surprises here, right? Well… maybe not so fast.

Hit up Google for some research and immediately found widespread concern over the performance of Enum.IsDefined().

It turns out that Enum.IsDefined() uses Reflection and must access metadata in order to do its magic. Neither of these operations are real speed demons, to be sure, and when using IsDefined in a loop with a ton of iterations, these performance problems may manifest themselves in an attention-getting way.

No, I never bothered to test this.

An alternative method for checking if an in-range UsefulItem variable was given:

var ui1 = UsefulItem.Foo;
var ui2 = (UsefulItem) 256;

var r1 = (ui1 < UsefulItem.Unknown && ui1 > UsefulItem.Baz);  // r1 = false, ui1 is defined
var r2 = (ui2 < UsefulItem.Unknown && url > UsefulItem.Baz);  // r2 = true, ui2 is not defined

This works, but what about when you add another UsefulItem to your Enum definition? The code above suddenly goes stale, maintenance nighmare ensues, company goes under, and you begin your unlimited unemployment benefit checks!

And the above was for a simple enum that had integer values in the Enum definition that matched the integer values in the DB lookup table. (The use of Enums to represent DB lookup table values can be discussed at another time).

The next Enum I needed to create didn’t have any integer values to line up with. The next lookup table that I wanted to represent used GUIDs as its primary key (PK) and this doesn’t work:

public enum UselessItem {
    Unknown = new Guid("00000000-0000-0000-0000-000000000000"),
    MacBook = new Guid("FAE0D3E4-9996-473B-8EEB-00001A5AC22F")
}

I get that last snippet was a bit gratuitous – we all know by now that Enums use integers as their underlying datatype.

And not only did I want to have a GUID represent each of my quasi-Enums, but I also wanted string representation beyond the camelcase names in the Enum. I won’t bother with another silly example – clearly a string is not an int, and can in no way be tied to the members of an Enum.

During my earlier research that revealed .NET’s willingness to allow any integer to be assigned to an Enum, I stumbled across something called the Typesafe Enum Pattern.

For reasons unknown to me, Java apparently doesn’t do Enums. That may not be entirely true, but for the sake of argument, let’s just over-simplify things here and agree that Java doesn’t do Enums.

I ended up finding Replace Enums with Classes [sun.java.com] and was inspired by what I read.

It led me to develop:

public class UselessItem
{
    public string ItemName { get; private set; }
    public Guid ItemId { get; private set; }

    private UselessItem() { }

    private UselessItem(string itemName, Guid itemId)
    {
        ItemName = itemName;
        ItemId = itemId;
    }

    // Define the 'Enum' members
    public static UselessItem MacBook =
        new UselessItem("MacBook/MacBook Pro", new GUID("EAD0014A-3733-DD11-9DCA-0019B9B42749"));

    public static UselessItem ScreenDoorOnASubmarine =
        new UselessItem("Screen Door on a Submarine", new GUID("EAD0014A-3733-DD11-9DCA-0019B9852F2E"));

    public static UselessItem DehydratedWater =
        new UselessItem("Dehydrated Water", new GUID("EAD0014A-3733-DD11-9DCA-0019B2635342"));
}

Note that the version above has been somewhat stripped down for clarity – originally I had implemented both IComparable and IEquatable as well as overridden the ‘==’ and ‘!=’ operators and the ToString() and GetHashCode() methods. These changes are left as an exercise for the reader

Using this newly created struct, let’s check out some of its characteristics:

var ui1 = UselessItem.MacBook;

var in1 = ui1.ItemName; // in1 = "MacBook/MacBook Pro'
var g1 = ui1.ItemId; // g1 = {EAD0014A-3733-DD11-9DCA-0019B9B42749}

Could a disgruntled fanboi do this?

ui1.ItemName = "MacBooks Rule! PCs suxx!";
ui1.ItemID = Guid.NewGuid();

Definitely not! Note lines 3 and 4 of our UselessItem Class definition – they only allow setting of these two properties from within the class itself. This is caught at compile time and simply not allowed.

Other things that the compiler will keep us safe from:

var macIsRad = new UselessItem("PCs and Windoze", Guid.NewGuid());

var haxxor1 = (UselessItem) Guid.NewGuid();

var haxxor2 = (UselessItem) "pwnt!!!";

In line one above, we cannot create new UselessItem objects, thanks to our private explicit default contructor:

private UselessItem() { }

Lines 3 and 5 will fail to compile as nothing but UselessItem objects can be cast to UselessItem.

Though this, as contrived as it is, will only be caught at runtime:

object o1 = string.Empty;

var ui1 = (UselessItem) o1;

Try the above code and get an InvalidCastException at runtime, killing the application if not caught.

And we even get the same behavior out of our class as we would a traditional Enum:

var ui1 = UsefulItem.Foo;
var ui2 = ui1;
var ui1 = UsefulItem.Baz;

// Final Result: ui1 = UsefulItem.Baz, ui2 = UsefulItem.Foo

var ui3 = UselessItem.MacBook;
var ui4 = ui3;
var ui3 = UselessItem.ScreenDoorOnASubmarine;

// Final Result: ui3 = UselessItem.ScreenDoorOnASubmarine, ui4 = UselessItem.MacBook

For some reason, this surprised me. At first, I thought that using a struct rather than a class would be prudent here, seeing as how structs are value types and classes are reference types.

After giving it a bit of thought, I believe it is because we cannot actually even instantiate a UselessItem object, we don’t have to worry about usual reference type behavior.

There is some tradeoff, I suppose.

Because a class can contain an explicit parameterless constructor, and a struct cannot, we end up the following difference between the two approaches:

Assume for a moment that UselessItem is indeed a struct:

Because structs are value types, they can never be set to null. This is partly the reason why they cannot have explicit parameterless constructors. Calling new on a struct is no different than declaring a new struct variable without assigning a value:

var ui1 = new UselessItem();
UselessItem ui2;

Though you aren’t able to use the ui2 variable here (compile-time error – Use of unassigned local variable ‘ui2′) it is plain to see during debugging that after line 2 above has run, both ui1 and ui2 contain the same values, which for structs, are all the default values for each type contained within (in this case, null for the ItemName and {00000000-0000-0000-0000-000000000000} for the ItemId.

On the other hand, using a class, we end up with:

var ui1 = new UselessItem(); // Illegal! Private parameterless constructor!
UselessItem ui2;

Obviously, the code in line 1 above is not an issue, since it fails at compile time. ui2, though, is actually equal to null following this initial declaration. Again, this is contrast to a struct, who ends up with default values for all of its members.

I, for one, think the use of a class here is a bit cleaner, as we can just check the whole object against null rather than checking some/all of the struct members against default values to determine if our object represents an unknown, or null, UselessItem.

Pretty cool!

Would love to hear comments on this approach – go ahead, tear me a new one, I can take it.

(Disclaimer: I don’t pretend to be an expert in PHP [nor .NET for that matter!], so please understand that the way I go about this might be sub-optimal. Whatever, sue me.)

Building the HTML Contact Form

This part is as straightforward as can be. We’re going to create a ‘Contact Form’ with a grand total of THREE fields – extending this model is left as an exercise for the reader (lol, always wanted to write that!)

For brevity, we’re going to use the HTML5 doctype and a table-based (gasp!) layout. Feel free to change it to whatever you want.

Here goes:

<!DOCTYPE html>
<html>
<head>
    <title>My Rad Contact Form</title>
    <style type="text/css">
        table tr > td { text-align: right; }
        table tr > td + td { text-align: left; }
    </style>
</head>
<body>
    <form action="ContactFormHandler.php" method="post">
        <table>
            <tr>
                <td>
                    Your Name:
                </td>
                <td>
                    <input type="text" id="Name" name="Name" />
                </td>
            </tr>
            <tr>
                <td>
                    Your Email:
                </td>
                <td>
                    <input type="text" id="Email" name="Email" />
                </td>
            </tr>
            <tr>
                <td>
                    Least Favorite Color:
                </td>
                <td>
                    <select id="LeastFavoriteColor" name="LeastFavoriteColor">
                        <option value="">- Choose -</option>
                        <option value="Blue">Blue</option>
                        <option value="Green">Green</option>
                        <option value="Orange">Orange</option>
                        <option value="Red">Red</option>
                        <option value="Yellow">Yellow</option>
                    </select>
                </td>
            </tr>
            <tr>
                <td colspan="2" style="text-align: center;">
                    <input type="submit" id="submit" value="Contact Me!" />
                    <input type="reset" id="reset" value="Start Over!" />
                </td>
            </tr>
        </table>
    </form>
</body>
</html>

Which, in IE9 renders as:

I’ve highlighted line 10 above to bring attention to the ‘action’ attribute of our opening form element. Whatever the form’s action is set to is where, on submission, the form ‘posts’ its values to. To read more about HTTP POST, please visit google.

And that completes the form!

Creating a MySQL Table to Store Form Values

Again, as a Microsoft fanboy ©, I rarely spend much time with MySQL in any real capacity. You have been warned.

We are going to assume that you have a MySQL instance installed and available to you. And that you know how to login and arrive at the MySQL ‘command line.’

Once logged in, we’ll first need to create a new database to store our new table which in turn will store our contact form values:

mysql> CREATE DATABASE MyRadContactForm;

Not surprisingly, this creates a new database with the name MyRadContactForm. The ALL CAPS is not required, but SQL is typically written in this fashion.

Next, we must let MySQL know what database we want to use:

mysql> USE MyRadContactForm;

Now our new DB is the active one, and we can create our table in it:

mysql> CREATE TABLE MyRadContacts (
    -> ContactID INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    -> ContactName VARCHAR(100),
    -> ContactEmail VARCHAR(100),
    -> ContactLeastFavoriteColor VARCHAR(10)
    -> ContactDateCreated DATETIME
    -> );

Quickly, ContactID is what we call a Primary Key – it is used to uniquely identify each record in the table.

It is an INT (Integer) type, meaning it can store whole numbers.

It is a NOT NULL column, meaning that it must contain a value for each row in the table.

And finally, it is an AUTO_INCREMENT column – this means that each time we add a new record to this table, MySQL will ensure that each ID is unique by essentially adding one to the highest existing ID at the time of a new insert.

VARCHAR(100) means that we can store a string (sequence of letters, numbers, etc) up to 100 characters in length.

DATETIME… well, that should be obvious.

Our new table should now be in place, though to quickly check, we can try:

mysql> SHOW TABLES;
+----------------------------+
| Tables in MyRadContactForm |
+----------------------------+
| MyRadContacts              |
+----------------------------+

Creating PHP Server-Side Code to Store New Values

Well, now we have something the client sees (the HTML form) and something buried deep within the bowels of a database to store values input by the client.

How, then, do we manage to bridge the gap between these two pieces?

In this case, we’ll use PHP.

We assume that you have a functioning PHP installation. Check out xampp for a relatively painless way to get up and running with PHP/MySQL/Apache on various platforms.

Right, without further delay:

<?php
    // Grab our POSTed form values
    // Note that whatever is enclosed by $_POST[""] matches the form input elements
    $contactName = $_POST["ContactName"];
    $contactEmail = $_POST["ContactEmail"];
    $contactLeastFavoriteColor = $_POST["ContactLeastFavoriteColor"];

    // Connect to our DB with mysql_connect(<server>, <username>, <password>)
    $sql_connection = mysql_connect("localhost", "root", "root");

    mysql_select_db("MyRadContactForm", $sql_connection);

    // Probably should check to make sure the connection was successful
    // But I'm too lazy...
    $sql = "INSERT INTO MyRadContacts (
                ContactName,
                ContactEmail,
                ContactLeastFavoriteColor,
                ContactDateCreated
            )
            VALUES (
                '$contactName',
                '$contactEmail',
                '$contactLeastFavoriteColor',
                NOW()
            )";

    mysql_query($sql, $sql_connection);

    mysql_close($sql_connection);
?>

This example is lacking in a number of areas, but we aren’t going to care about SQL Injection or error-checking at this point.

Brief rundown of the above code:

Lines 4-6: We are creating three variables to store the values of our incoming form. Note that each item matches the ‘name’ attributes of our form inputs.

Line 11: This is the equivalent of the USE MyRadContactForm command that we issued earlier to our MySQL server prior to creating our table.
Line 13: This is the beginning of an SQL INSERT statement. Not surprisingly, this command inserts new records into our table. In the first set of parentheses, we specify which table columns that we want to store our data in. The second set of parentheses represent the actual values to store in the table.

Lines 20-22: PHP makes life a bit easier for us here, as it will automatically detect our variable names and replace them with the values they contain. NB: The $sql string we’ve created is surrounded with “ aka double quotes. This is crucial to get this behavior. The variable names are themselves surrounded by ‘ aka single quotes, as this is standard SQL for indicating that you are working with string values (aka VARCHAR).

Line 23: We call the MySQL built-in function NOW() to store the current date/time in ContactDateCreated at the time our insert is performed. There are other ways of handling this (such as declaring a variable in PHP), but this is easy.

Line 26: mysql_query does the actual work of sending our INSERT statement to our DB via the $sql_connection we created earlier.

Remember, this is just a primer (and not much of one at that!). Writing code like this will likely draw ire from your peers and pink slips from your employers.

Creating an HTML Contact Form Submission Viewer

So, we’ve got our form, database, table, and server-side PHP script. If all is well, we should now be adding new records to the table with each form submission.

But what good does this data do anyone if it is tucked safely away in the bowels of our MySQL server?

Let’s make a quick-and-dirty PHP page to display the input values:

<!DOCTYPE html>
<html>
    <head>
        <title>My Rad Contacts</title>
    </head>
    <body>
<?php
    $sql_connection = mysql_connect("localhost", "root", "root");

    mysql_select_db("MyRadContactForm", $sql_connection);

    $result = mysql_query("SELECT * FROM MyRadContacts");

    echo "<table>";
    echo "<tr><td>Name</td><td>Email</td><td>Least Favorite Color</td><td>Created On</td></tr>";

    while ($row = mysql_fetch_array($result)) {
        echo "<tr>";
        echo "<td>" . $row["ContactName"] . "</td>";
        echo "<td>" . $row["ContactEmail"] . "</td>";
        echo "<td>" . $row["ContactLeastFavoriteColor"] . "</td>";
        echo "<td>" . $row["ContactDateCreated"] . "</td>";
        echo "</tr>";
    }

    echo "</table>";

    mysql_close($sql_connection);
?>
    </body>
</html>

Line 12: This time, since we want to display data already in our DB, rather than insert new records, we issue a SELECT statement. The * (asterisk) tells SQL that we want every column for each row we get back. We store the data we receive in a variable named $result.

Line 14: Using PHP’s echo command, we begin the definition of our HTML table. PHP echoes its argument to the HTML page seen by the end user.

Line 17: The keyword while indicates to PHP that we want to start a loop, in which we will output the values stored in each row of our DB. When we reach the last row, the while statement is no longer true, and the loop exits.

Line 19: Again, we use echo to get our stuff out on to the HTML page. Here, we are building a table cell (<td>) that contains whatever is stored in the ContactName field for this record. Note that PHP uses a single . (dot) character to stitch strings together. This is often referred to as ‘string concatenation.’

Line 26: Finally, we use echo one last time to close our <table> tag.

UPDATE

By request, I’ve put together a zip file containing the PHP/HTML source seen above. I haven’t actually run it to verify its accuracy, so please keep that in mind.

ContactFormDemoSource

First, let’s create a simple class to demonstrate our needs:

public class Person {
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateCreated { get; set; }
    public DateTime? DateModified { get; set; }
}

Note the use of nullable value types on lines 5 and 7 above. For those not familiar with the concept of nullable types, have a look at: Using Nullable Types – MSDN.

In our class, we are anticipating that there may be NULL values stored for a Person’s Age and Last Modified Date.

Simple enough. But how to best build a Person object from a SqlDataReader? I’ve seen tons of different approaches, such as:

var people = new List<Person>();

using (var dr = cmd.ExecuteReader()) {
    while (dr.Read()) {
        people.Add(new Person {
            Id = (int) dr["Id"],
            FirstName = dr["FirstName"].ToString(),
            LastName = dr["LastName"].ToString(),
            Age = Convert.IsDbNull(dr["Age"]) ? null : (int?) dr["Age"],
            DateCreated = (DateTime) dr["DateCreated"],
            DateModified = Convert.IsDbNull(dr["DateModified"])
                                                 ? null
                                                 : (DateTime?) dr["DateModified"]
        });
    }
}

This approach certainly isn’t that bad, and seems to be a very common method for handling NULLs via nullable types.

But we’re not content with something that’s only ‘not bad,’ are we? Of course not.

Let’s try another way:

var people = new List<Person>();

using (var dr = cmd.ExecuteReader()) {
    while (dr.Read()) {
        people.Add(new Person {
            Id = (int) dr["Id"],
            FirstName = dr["FirstName"].ToString(),
            LastName = dr["LastName"].ToString(),
            Age = dr["Age"] as int?,
            DateCreated = (DateTime) dr["DateCreated"],
            DateModified = dr["DateModified"] as DateTime?
        });
    }
}

Check out lines 9 and 11 – we are using the ‘as’ operator rather than the clunky ternary, resulting in code that, IMHO, is more concise, clear, and therefore easier to read and maintain.

I’m surprised that I haven’t seen others doing this… I know I’m not the only one to have stumbled across this approach!

Further along in the stored procedure, I needed the value of this newly-inserted GUID to use in another INSERT statement. Fortunately, T-SQL provides us with precisely what we need – the OUTPUT clause.

A quick demo:

The table DDL:

CREATE TABLE [dbo].[MyTable] (
	[MyId] [uniqueidentifier] NOT NULL,
	[FirstName] [varchar](50) NULL,
	[LastName] [varchar](50) NULL,
	CONSTRAINT [PK_MyTable] PRIMARY KEY CLUSTERED ([MyId] ASC)
)
GO

ALTER TABLE [dbo].[MyTable] ADD CONSTRAINT [DF_MyTable_MyId] DEFAULT (newsequentialid()) FOR [MyId]
GO

Example portion of sproc:

DECLARE @MyTempTable table (MyTempId uniqueidentifier);

INSERT INTO MyTable (
    FirstName
    , LastName
)
OUTPUT inserted.MyId INTO @MyTempTable
VALUES (
    'Brian'
    , 'Dobberteen'
);

DECLARE @NewlyInsertedId uniqueidentifier;

SELECT @NewlyInsertedId = MyTempId FROM @MyTempTable;

Thanks to the bit highlighted above on lines 7 and 15, we now have a reference to the newly inserted GUID and can use it as needed.

Additionally, the use of newsequentialid() here lessens the impact of using a GUID clustered index.

This was selected as an ASP.NET Article of the Day for June 18, 2010

‘SjAJ’ ASP.NET CustomValidator

SjAJ?! Sorry, I couldn’t resist. I had started with AJAX, but thinking now… hmmm, the method being described here is Synchronous jQuery And JSON.

Something tells me that SjAJ is not going to make it to buzzword status. Oh well, I tried.

We will try to quickly outline a method for using the ASP.NET CustomValidator control in conjunction with jQuery and the AJAX Control Toolkit.

Initially, I had tried to use other APIs to call my web services and/or page methods. Problem was, at least that I could tell, was that the asynchronous nature of these operations cause an issue inside the ClientValidationFunction specified in the CustomValidator control.  Eventually, I revisted the code in my earlier posts, and once again, jQuery came to the rescue! Details follow.

ASP.NET CustomValidator Control

For those not familiar with the CustomValidator control, let me give a brief explanation.

<asp:CustomValidator runat="server" ID="UserNameExistsValidator"
    OnServerValidate="UserNameExistsValidator_ServerValidate"
    ControlToValidate="UserNameTextBox"
    ClientValidationFunction="doesUserExist" />

The bit we’re most concerned with here is the ClientValidationFunction. This will fire during client-side page validation, receiving two arguments.

function doesUserExist(source, arguments) { }

source contains the <span> element rendered for the validation control. Since we are going to use the ASP.NET Ajax Control Toolkit’s ValidatorCalloutExtender we will ignore the argument source.

arguments is much more interesting here, as it contains two properties: IsValid and Value

As you might expect, Value contains the value contained in the ControlToValidate that we’ve specified in our validator control. IsValid is what we’ll use to indicate whether or not the value we’re checking exists or not.

Here’s a simple, albeit very contrived, example of how the ClientValidationFunction works:

<asp:CustomValidator runat="server" ID="ZipCodeCustomValidator"
    ControlToValidate="ZipCodeTextBox"
    ClientValidationFunction="isValidZipCode" />

<script type="text/javascript">
    function isValidZipCode(source, arguments) {
        var zipCode = arguments.Value;
        var zipCodeValid = /^\d{5}(-\d{4})$/.test(zipCode);

        arguments.IsValid = zipCodeValid;
    }
</script>

Again, very contrived, and quite silly, actually – we would be much better off using a RegularExpressionValidator for this particular case… but I digress.

Briefly, this CustomValidator uses client-side code to test the value entered in a text box (ZipCodeTextBox in this case) against the regex /^\d{5}(-\d{4})?$/ which will allow values such as 95060 or 95060-1234 but not 950-0000 nor 95064-0.

Checking for An Existing Value

As mentioned earlier, I was having trouble getting things to work using a few asynchronous techniques. It seemed that if arguments.IsValid is set inside a callback function, it doesn’t register properly, and the control always appears valid.

Luckily, jQuery’s $.ajax() function has a handy option: async, which when set to false does what we need – it waits for the response from the server before continuing to our success function.  Without further ado…

function doesUsernameExist(source, arguments) {
    var exists;
    $.ajax({
        type: "POST",
        contentType: "application/json; charset=utf-8",
        url: "Default.aspx/DoesUserExist",
        data: "{'username': '" + arguments.Value + "'}",
        dataType: "json",
        async: false,
        success: function(result) {
            exists = result.d;
        }
    });
    arguments.IsValid = !exists;
}

In line 6, we specify the name of our PageMethod contained inside our Default.aspx page. This is only one of many ways to accomplish this, of course. See http://brian.dobberteen.com/code/responding-to-jquery-ajax-request-with-php/ for my treatment of using PHP as a ‘web service’ of sorts.

Line 9 is the all-important async: false that seems to provide the needed magic to get this all working.

Finally, on line 14, we set our CustomValidator’s IsValid property to true only if the value we are checking for did not exist.

To make things easy, let’s use the ASP.NET membership system to check for an existing username. This has the benefit of providing the method for both server and client side validation. Here goes:

using System;
using System.Web.Security;
using System.Web.Services;
using System.Web.UI;

public partial class _Default : Page 
{
    protected void Page_Load(object sender, EventArgs e) { }

    [WebMethod]
    public static bool DoesUserExist(string username)
    {
        return Membership.GetUser(username) != null;
    }

    protected void UserNameExistsValidator_ServerValidate(object source, ServerValidateEventArgs args)
    {
        args.IsValid = !DoesUserExist(args.Value);
    }
}

The logic here is very simple. On line 13, we use the ASP.NET Membership system to check for an existing username. This logic also serves us well for our OnServerValidate event handler, starting on line 16.

The .aspx page:

<%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %>

<%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit" TagPrefix="cc1" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Check Existing Usernames</title>
    <style type="text/css">
        .invalid {
            border: solid 1px #ff0000;
            background-color: #ffcccc;
        }
    </style>
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js">
    </script>
    <script type="text/javascript">
        function doesUsernameExist(source, arguments) {
            var exists;
            $.ajax({
                type: "POST",
                contentType: "application/json; charset=utf-8",
                url: "Default.aspx/DoesUserExist",
                data: "{'username': '" + arguments.Value + "'}",
                dataType: "json",
                async: false,
                success: function(result) {
                    exists = result.d;
                }
            });
            arguments.IsValid = !exists;
        }
    </script>
</head>
<body>
    <form id="form1" runat="server">
    <asp:ScriptManager runat="server" ID="sm1" />
    <div>
        Username:
        <asp:TextBox runat="server" ID="UserNameTextBox" CausesValidation="true" />
        <asp:Button runat="server" ID="ClientSubmitButton" Text="Check Username Client Side"
            OnClientClick="Page_ClientValidate(); return false;" />
        <asp:Button runat="server" ID="ServerSubmitButton" Text="Check Username Server Side"
            OnClientClick="ValidatorEnable(UserNameExistsValidator, false);" />
    </div>
    <asp:CustomValidator runat="server"
        ID="UserNameExistsValidator"
        ControlToValidate="UserNameTextBox"
        ClientValidationFunction="doesUsernameExist"
        OnServerValidate="UserNameExistsValidator_ServerValidate"
        Display="None"
        ErrorMessage="Username Already Exists" />
    <cc1:ValidatorCalloutExtender runat="server"
        ID="UserNameExistsValidator_CalloutExtender"
        TargetControlID="UserNameExistsValidator"
        HighlightCssClass="invalid"
        PopupPosition="BottomLeft" />
    </form>
</body>
</html>

And finally, a screenshot of what the validator looks like when I enter ‘bdobberteen’ for the username – an account I created minutes earlier:

I am not sure if this degrades gracefully in the face of a non-javascript browser. Namely, the ValidatorCalloutExtender won’t display. A possible solution would be to add a ValidationSummary control, initially set its visibility to false, and, upon postback, if the server-side validation fails (!Page.IsValid), set that same ValidationSummary to visible, allowing downstream browsers to view the various error message(s).

Hope this helps someone!

- brian -

Sample Code for Article

Since beating the proverbial dead horse is my specialty, this brief post is going to cover making a call to the Yahoo! Maps API via an ASP.NET web service (.asmx) which we then call from client script with the aid of the Microsoft ASP.NET AJAX library(ies).

In order to access the necessary JavaScript script libraries, we must first include the customary ScriptManager object in our page:

<asp:ScriptManager runat="server" ID="sm1">
    <Services>
        <asp:ServiceReference Path="~/ZipCodeService.asmx" />
    </Services>
</asp:ScriptManager>

As you may have already guessed, this declaration creates a ScriptManager for our page and includes a reference to the web service (which we will create momentarily) used for fetching the City and State upon user input of a US Zip Code.

Without further ado, here’s the complete web service code:

using System.Linq;
using System.Web.Script.Services;
using System.Web.Services;
using System.Xml.Linq;

namespace YahooMapsZipCodeLookup
{
    [WebService(Namespace = "http://tempuri.org/")]
    [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
    [System.ComponentModel.ToolboxItem(false)]
    [System.Web.Script.Services.ScriptService]
    public class ZipCodeService : System.Web.Services.WebService
    {
        private static readonly string MAP_URL = "http://local.yahooapis.com/MapsService/V1/geocode?appid=";
        private static readonly string MAP_APP_ID = "<YOUR ID HERE>";

        [WebMethod]
        public CityState GetCityStateByZip(string zipCode)
        {
            XDocument xdoc = XDocument.Load(MAP_URL + MAP_APP_ID + "&zip=" + zipCode);

            var state = root.Descendants().Where(el => el.Name.LocalName == "City").Single().Value;
            var city = root.Descendants().Where(el => el.Name.LocalName == "State").Single().Value;

            return new CityState { City = city; State = state; };
        }
    }
    public class CityState
    {
        public string City { get; set; }
        public string State { get; set; }
    }
}

After our ScriptManager registers this service, we now have access to proxy(ies) that can be called from the client side. To do so, we can create a wrapper to the service call:

function getCityStateByZip(zip) {
    YahooMapsZipCodeLookup.ZipCodeService.GetCityStateByZip(
                    zip,
                    onZipLookupSuccess,
                    onZipLookupError,
                    "<%= DateTime.Now %>"  // Passing as the context
         );
}

It’s not as simple as just including the above call – we need to provide the methods named in the second and third parameters (the two lines highlighted in green above). Which would look something like:

function getCityStateByZip(zip) {
    YahooMapsZipCodeLookup.ZipCodeService.GetCityStateByZip(
                    zip,
                    onZipLookupSuccess,
                    onZipLookupError,
                    "<%= DateTime.Now %>"  // Passing as the context
         );
}
function onZipLookupSuccess(result, context, methodName) {
    // Note how we can access the properties of the returned CityState object
    // The ScriptManager takes care of all of this for us!
    $get("CityStateResult").innerHTML = result.City + ", " + result.State;
}
function onZipLookupError(error, context, methodName) {
    // The error object's most interesting method is probably get_message(), which
    // will, in this case, return the message of any ASP.NET exceptions that may
    // have occured on the server side webservice.
    $get("CityStateResult").innerHTML = "Error: " + error.get_message();
}

Though we aren’t making any use of the context and methodName parameters being passed to our callback functions, I’ll just point out that the context is whatever was set when calling the webservice – in this case, the date and time were used. The context can be very useful to track asynchronous calls in a stateless environment.

The methodName, cleverly enough, returns the name of the web service method that we’ve called – in this case, methodName contains GetCityStateByZip which, as we all know, is the name of the only method exposed by our YahooMapsZipCodeLookup.ZipCodeService.

There is another option to writing explicit callback methods, and one that I prefer (probably due to my experience with jQuery). If we don’t want to write explicit methods, we can use anonymous functions as parameters in the call to our web service:

function getCityStateByZip(zip) {
    YahooMapsZipCodeLookup.ZipCodeService.GetCityStateByZip(
                zip,
                function(result, context, methodName) {
                    $get("CityStateResult").innerHTML =
                            result.City + ", " + result.State + "<br />"
                          + "context: " + context + "<br />"
                          + "methodName: " + methodName;
                },
                function(error, context, methodName) {
                    $get("CityStateResult").innerHTML =
                        "error: " + error.get_message();
                },
                "<%= DateTime.Now %>"  // Passing as the context
        );
}

The two highlighted lines indicate where we’ve replace the names of functions with anonymous functions. NB: the line numbers in the above snippet are supposed to correspond with the actual aspx page.

To hook everything up on our actual page, we need to add an event handler to, in this case, a textbox:

<input type="text" onchange="getCityStateByZip(this.value);" />
<input type="submit" value="Get City and State" onclick="return false;" />
<div id="CityStateResult"></div>

I also snuck in the CityStateResult div that is the target of our DOM manipulation upon receipt of a response from the web service. I also added a do-nothing submit button to demonstrate that a button press will fire the textbox’s onchange event.

The entire aspx page:

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Calling a Web Service from ASP.NET AJAX Client Script</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <asp:ScriptManager runat="server" ID="sm1">
        <Services>
            <asp:ServiceReference Path="~/ZipCodeService.asmx" />
        </Services>
    </asp:ScriptManager>
    <input type="text" name="ziptxt" id="ziptxt" onchange="getCityState(this.value);" />
    <input type="submit" value="Get City and State" onclick="return false;" />
    <div id="cityStateResult"></div>
    </div>
    <script type="text/javascript">
        function getCityState(zip) {
            var citystate =
                YahooMapsZipCodeLookup.ZipCodeService.GetCityStateByZip(
                    zip,
                    function(result, context, methodName) {
                        $get("cityStateResult").innerHTML = 
                            result.City + ", " + result.State + "<br />"
                         + "context: " + context + "<br />"
                         + "method name: " + methodName;
                    },
                    function(error, context, methodName) {
                        $get("cityStateResult").innerHTML =
                            "error: " + error.get_message();
                    },
                    "<%= DateTime.Now %>"  // Passing as the context
                 );
        }
    </script>
    </form>
</body>
</html>

In a nutshell, when the user triggers the onchange event of our textbox, the event is handled by our wrapper function getCityStateByZip(zip), to which we pass this.value, which contains the changed value of the textbox. This value is then passed to the web service, which returns a CityState object – ASP.NET AJAX handles all of the serialization and other such details for us in a nearly transparent way. We can refer to the CityState object returned by our web service as if the object was a normal .NET object, i.e. result.City or result.State.

And I think that covers it! No more posts on zip code lookups, I promise!

Before I forget, here is the source to the samples seen above: Calling a Web Service with ASP.NET AJAX Client Script Source Code

Using reader As XmlReader = XmlReader.Create(MAP_URL & MAP_APP_ID & "&zip=" & zip)
  While reader.Read
    If reader.Name = "City" And reader.IsStartElement Then
      ret.City = reader.ReadElementString("City")
    End If

    If reader.Name = "State" And reader.IsStartElement Then
      ret.State = reader.ReadElementString("State")
    End If
  End While
End Using

We were using the above to basically read the XML response line-by-line, checking for the two elements we are interested in, and storing their values in our simple CityState object ‘ret.’ Again, the XML we are processing looks like:

<?xml version="1.0" ?> 
<ResultSet -xmlns omitted for clarity->
  <Result precision="zip">
    <Latitude>36.993591</Latitude> 
    <Longitude>-122.060199</Longitude> 
    <Address /> 
    <City>Santa Cruz</City> 
    <State>CA</State> 
    <Zip>95064</Zip> 
    <Country>US</Country> 
  </Result>
</ResultSet>
<!--  ws05.ydn.gq1.yahoo.com compressed/chunked Thu Jul  9 14:54:33 PDT 2009 -->

Though our XmlReader method works fine, it seemed a bit clunky to me, so I set out to check out LINQ to XML to see if we can clean the code up a little bit.

LINQ is still somewhat of a new concept for me, as I haven’t had much chance to work with it given the nature of much of the work I do. Its potential usefulness, however, seems pretty clear to me, and definitely look forward to working with it as much as possible – at least until the next latest, greatest thing comes along! I’ve always felt the LINQ syntax to be a bit unusual, and – unlike I’d first hoped – not that close to SQL. Of course, LINQ isn’t SQL, so I suppose I shouldn’t be surprised that LINQ doesn’t look more like:

SELECT element FROM elements WHERE element.name = 'City'

Of course, this is an incredibly trivial example, and the only difference between a similar LINQ query is the arrangement of the three components of the query (SELECT, FROM, and WHERE). But in reading that I’ve done, LINQ can get pretty cryptic at times… though I used to feel the same way about complex SQL, which now is very easy for me to comprehend.

At any rate, we’ll be dropping our use of the XmlReader class and instead opt for a LINQ-to-XML XDocument object. We need to change our Imports declaration slightly, removing System.Xml and replacing it with System.Xml.Linq. Much the same as we did with the XmlReader, we use XDocument’s static function Load to grab our XML from the Yahoo Maps API (more about accessing the Yahoo Maps API).

Dim xdoc As XDocument = XDocument.Load(MAP_URL & MAP_APP_ID & "&zip" = & zip)

Just like our earlier examples, this is contained within a PageMethod that accepts ‘zip’ as its only parameter and returns a simple CityState object. After the XDocument is loaded, we can now perform a LINQ query on it, allowing for us to easily specify what elements (City and State, in this case) we’d like the value of.

Dim city = (From el in xdoc.Descendants _
              Where el.Name.LocalName = "City" _
              Select el.Value).Single

Because we’re interested in the City and State elements, which are descendants of the root ‘ResultSet’, we’re using the cleverly named property Descendants of our XDocument object. Descendants is an IEnumerable collection of XElement objects which is what makes our LINQ operations possible. As you can see, the LINQ query first specifies where to look for something (akin to the FROM clause in an SQL SELECT statement), then we set the criteria to be sure we find the ‘City’ element. I discovered that el.Name won’t work for us, as the Name property of an XElement object is an XName object. The LocalName property of an XElement refers to the elements unqualified name, without any namespace info included. The LINQ statement next ‘Selects’ the element matching our criteria. Finally, since we are only expecting a single city to exist in our XML response, we wrap the whole LINQ query in parentheses and use .Single to return the one-and-only value we’re after. .Single will throw an exception if more than one element was found by our query. To get the value of the State element, just replace Where el.Name.LocalName = “City” to Where el.Name.LocalName = “State”.

I’ve experimented with polling both the City and State elements in one pass, i.e.

Where el.Name.LocalName = "City" Or el.Name.LocalName = "State"

But this just seemse to necessitate another query to be sure that we’re getting the right values from our new, albeit smaller, collection of XElements. So, for now, we’ll just perform two seperate LINQ operations… please let me know if there are better ways of going about this (and I’m sure that there are!)

Finally, let’s take a quick look at using a Lambda expression to streamline this whole thing a bit more. The following gives us the same result as the first LINQ query above:

Dim city = xdoc.Descendants.Where(Function(el) el.Name.LocalName = "City").Single.Value

The call to .Where from our xdoc.Descendants is a call to an ‘extension method.’ These extension methods are central to the functionality of LINQ. In this case, we’re passing an ‘anonymous function’ to the Where extension method that we will be using to apply our criteria. The anonymous function is passed el which is an XElement object. And again, we want an element with a LocalName of City, so the body of our anonymous function does just this, compares the LocalName to ‘City’, and if it matches, the expression continues by fetching the Single city element’s Value.

Clearly, we’ve only just scratched the surface of LINQ and LINQ to XML, but we gotta start somewhere, no?

Earlier, we used ASP.NET PageMethods, but let’s see a possible PHP solution.

Again, we’ll just be performing the trivial task of retrieving a city/state location based on a zip code entered on our form.

...
<form id="form1">
  <input type="text" name="ZipCodeTextBox" id="ZipCodeTextBox" />
</form>
...

Since we’ll use jQuery to bind this textbox to the onchange event, there are no additional attributes needed in our markup here.

<script type="text/javascript">
$(function() {
});
</script>

A quick note on jQuery for those new to it: in line 2 above, the rather terse statement $(function() is shorthand for “wait until the page’s document object model (DOM) is loaded so that we can bind event handlers, set CSS properties, etc. to page elements.” The DOM loads before the images on a page are done downloading, so this allows for our jQuery to work as soon as it is able to. $ is essentially shorthand for jQuery itself and is central to its operation. Wrapping an element in $() bestows upon that element with all the power of jQuery, allowing for extensive manipulation through chaining of functions.

jQuery also allows for us to create new DOM elements by using the syntax:

$("<div id='div1'></div>")

In this example we have created a div with an id attribute of ’1′. Even though this element now “exists,” it is not actually in the DOM. Rather than include an <input> in our XHTML, let’s instead create it with jQuery. With chaining, we can handle not only the creation, but the binding of the onchange event, some simple CSS styling, and finally, the insertion of the new element into the page.

Because ASP.NET is pretty specific about a PageMethod can respond to a client-side reqest, we used the $.ajax() function in our earlier example, as it allows for the most granular approach to sending an AJAX request. But now, since we are going to build a simple PHP script to respond to a GET request, there is a very handy jQuery function, namely $.getJSON():

$(function() {
  $("<input type='text' id='ZipCodeTextBox' name='ZipCodeTextBox' />")
    .bind('change', function(event) {
      if (/^\d{5}(-\d{4})?$/.test($(this).valI())) {
        $.getJSON("ZipCodeService.php", {zip: $(this).val()}, function(msg) {
          $("<label />").text(msg.City + ", " + msg.State).appendTo("#form1");
        });
      }
    })
    .appendTo("#form1");
});

Lines 2 and 6 demonstrate jQuery’s ability to generate new DOM elements on the fly – in this case a new textbox and a new label – and perform various operations on them, including inserting them into the page. Here we use appendTo() to place our new elements after the last child element of what we’ve selected, in this case #form1.

Line 5 is the call to $.getJSON, whose signature looks like:

$.getJSON(url, parameters, callback)

In our example, we use ZipCodeService.php as our URL, which refers to the script we’re about to create that will reside in the same location as our XHTML file. For parameters, I chose to create a simple object using JSON notation, {zip: $(this).val()}, which will be turned into proper query string parameters by jQuery. We could also have set our parameters as they would appear in a query string, i.e. “zip=” + $(this).val() – in this simple GET request, this is a pretty trivial point, but if you were working with a more complicated javascript object, it would be a lot easier to simply pass it as a whole rather than trying to manually serialize it. Finally, the callback parameter to $.getJSON() is the name of a function that will fire following completion of the AJAX request – it features two parameters, the first containing the javascript object returned and the second the status of the request. We are going to ignore the status parameter, so our anonymous callback function looks like:

function(msg) { $("<label />").text(msg.City + ", " + msg.State).appendTo("#form1"); }

Doesn’t get much easier! All we had to do was return a JSON encoded object from our PHP function and in two lines of javascript, we have direct access to the City and State properties that we requested.

Now, let’s check out ZipCodeService.php – please note: this is my first foray into the world of PHP and XML, so if I’ve badly butchered anything, please let me know!

<?php
// Check to make sure 'zip' was sent in the GET request
if (!empty($_GET["zip"])) {

  // Set a couple of constants
  define("MAP_URL", "http://local.yahooapis.com/MapsService/V1/geocode?appid=");
  define("MAP_APP_ID", "<YOUR APP ID>");

  // Retrieve the query string parameter 'zip' and store it in $zip
  $zip = $_GET["zip"];
  
  // Run *another* Regular Expression test on the input
  if (preg_match("/^\d{5}(-\d{4})?$/", $zip)) {

    // Use simplexml_load_file to grab our XML response from Yahoo
    // This works much the same as when we loaded the XML in our ASP.NET
    $xml = @simplexml_load_file(MAP_URL . MAP_APP_ID . "&zip=" . $zip);

    // Make sure that our request actually succeeded!
    if ($xml)
    
      // Because the Yahoo Maps API will give some funky responses to some
      // strings that *look* like US zip codes but are somehow classified as foreign
      // we are going to check that the zipcode is indeed a US postal code and that
      // the Zip element is set in the response - something which is absent on the
      // postal codes deemed to be located outside the US by Yahoo Maps
      if (!empty($xml->Result->Zip) && $xml->Result->Country == "US")
        $ret = array('City' => (string)$xml->Result->City, 'State' => (string)$xml->Result->State);
      else
        return false;
    else
      return false;


  echo json_encode($ret);
}
	} 
?>

On line 28, we are using array() to construct a new associative array (aka hash) with the keys ‘City’ and ‘State’ (big surprise, right?!) and their respective values. I found that our simplexml object exhibits some interesting behavior when it comes to casting. It seems that it is smart enough to know to cast to a string automatically when used in some scenarios, such as in a comparison:

if ($xml->Result->City == "Anytown")

But if we try and assign $xml->Result->City to a key in our associative array, it instead assigns the entire simplexml object rather than its string contents. So, in our call to array() we need to cast the two elements as such:

$ret = array('City' => (string)$xml->Result->City, 'State' => (string)$xml->Result->State);

To cast our objects, we simply prepend them with the type to cast to enclosed in parentheses – a lot less verbose than VB’s clunky CType() function!

Now, all we need to do for our client-side $.getJSON() call to be happy is to write back a string representing a JSON object, which is where the handy json_encode() function comes into play. We just pass it our hash $ret and voila! Out pops a JSON string that we simply echo to our client, and that’s it on the server side!

All that’s left now is for the callback function we specified in our call to $.getJSON() to fire, in which a new <label /> is created, has its text set to City, State and is finally appended to our form.

Was this easier that doing it with ASP.NET? Was it lighter-weight? Faster? For something as trivial as this, I think that performance is not much of a consideration at all. Especially since the entire thing bottlenecks on our request to Yahoo Maps. In terms of ease of coding, I think I slightly prefer the ASP.NET PageMethod, though that is probably because I am such a Visual Studio fanboy. The .NET solution still requires two files as does the jQuery/PHP that we’ve concocted here. The XML handling routines in PHP seem just as capable as those in .NET. One thing I can say I like more about the PHP solution is that I feel much more in control of exactly what is going on in terms of generated code (there is none for our PHP solution!). I am not sure how much weight is added to a page when ASP.NET AJAX builds proxies for our client code to talk to a PageMethod, and I do know that jQuery, in minified and gzipped form, only takes 19K – which is awfully small… how close does ASP.NET AJAX come to that number?

I think we’ve pretty much exhausted this whole zipcode lookup thing, so next time I want to examine using nested ASP.NET data controls such as the Repeater, FormView, etc.