Zoning out with Moment Timezone

I’ve recently been heavily embedded in implementing time zone sensitivity into a web application and I thought I’d share my first experiences on handling this from the perspective of the browser.

A great little library for handling this kind of tricky number can be found in the form of Moment Timezone, which sits proudly beside Moment.js, but as a full date parsing solution incorporating time zones.

The part of the library that really caught my attention was the time zone inferring abilities of the library; the superbly named ‘guess‘ function (loving the name!). The function, despite the name, is actually pretty sophisticated, so let’s take a look at a working example and how the documentation defines the ‘guts’ of its time zone guessing powers.

Moment Timezone can be installed and used in a number of different ways, as described here, but I went with the good old classic method of adding a NuGet package via Visual Studio:

Adding Moment Timezone via NuGet.

Adding Moment Timezone via NuGet.

Or, if you want to use the Package Manager Console then use this nugget instead:

Install-Package Moment.Timezone.js

Once the package is installed, alive and kicking we need to (as you would expect) reference the supporting Moment JavaScript library followed by the Moment Timezone based library, as follows:

<script src="~/Scripts/moment.min.js" type="text/javascript"></script>
<script src="~/Scripts/moment-timezone-with-data.min.js" type="text/javascript"></script>

You are then ready to utilise the guess function in a stupendous one-liner, just like this (wrapped in a jQuery document ready function, in this example):

<script type="text/javascript">
    // On page load grab a value denoting the time zone of the browser
    $(function () {
        // Log to the console the result of the call to moment.tz.guess()
        console.log(moment.tz.guess());
    });
</script>

The screenshots listed here show just a few examples of how the guess function works (by providing a tz database, or IANA database, value denoting which time zone Moment Timezone has inferred the client is in).

Moment Guess Usage London.

Moment Guess Usage London.

Moment Guess Usage Cairo.

Moment Guess Usage Cairo.

Moment Guess Usage Havana.

Moment Guess Usage Havana.

For newer, supporting browsers, Moment Timezone can utilise the Internationalization API (Intl.DateTimeFormat().resolvedOptions().timeZone) to obtain time zone information from the browser. For other browsers, Moment Timezone will gather data for a handful of moments from around the current year, using Date#getTimezoneOffset and Date#toString, to intelligently infer as much about the user’s environment as possible. From this information, a comparison is made against entries in the time zone database and the best match is returned. The most interesting part of this process is what happens in the case of a tied match; in this instance, a cities population becomes a deciding factor (the time zone linking to a city with the largest population is returned).

A full listing of tz database values can be found using the link below, showing the range of options available including historical time zones. It’s worth noting that the tz database also forms the backbone of the very popular Joda-Time and Noda Time date/time and timezone handling libraries (Java and C#, respectively; from the legendary Mr Skeet!).

List of tz database zones

For the project I was involved with, I ended up using Noda Time to actually perform conversions server side, utilising Moment Timezone to provide a ‘best stab’ at a user’s timezone on first access of the system. I’d like to give this the attention it deserves in a follow-up post.

Have a great week everyone, until the next time!

Groovy JavaScript Regex Name Capitalisation Handling

Greetings!

A tidbit found by a friend of mine online, forming the basis for a small piece of work I’ve done this week surrounding name capitalisation. This was pulled from a stack overflow article so credit where credit is due for starters:

js-regex-for-human-names

This is fairly robust, covering Mc, Mac, O’s and double-barrelled, hyphenated names. It does capitalise the first character directly after an apostrophe (regardless of placement) which may or may not be a problem. As for usage, I went with the following setup (with the relevant JavaScript and jQuery hooks being properly abstracted in the production code of course).

Firstly, the example HTML structure:

<div id="container">
	<!--An example form illustrating the fixNameCasing function being called on a test forename, middle names and surname field (when focus is lost)-->
	<form action="/" method="post">
		<div>
			<label id="forename-txt-label">Forename:</label>
		</div>
		<div>
			<input id="forename-text" name="forename-text" class="control-top-margin fix-name-casing" type="text" />
		</div>
		<div>
			<label id="middlename-text-label">Middle names:</label>
		</div>
		<div>
			<input id="middlename-text" name="middlename-text" class="control-top-margin fix-name-casing" type="text" />
		</div>
		<div>
			<label id="surname-text-label">Surname:</label>
		</div>
		<div>
			<input id="surname-text" name="surname-text" class="control-top-margin fix-name-casing" type="text" />
		</div>
		<div>
			<button id="submit-button" type="submit" class="control-top-margin">Submit</button>
		</div>
	</form>
</div>

Then, our jQuery/JavaScript juicy bits:

<!--Bring jQuery into scope so we can hook up a function to relevant elements on 'blur' event (lost focus)-->
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script>
<script type="text/javascript">
	
	// The name casing fix function utilising regex
	function fixNameCasing(name) {
		var replacer = function (whole, prefix, word) {
			ret = [];
			
			if (prefix) {
				ret.push(prefix.charAt(0).toUpperCase());
				ret.push(prefix.substr(1).toLowerCase());
			}
			
			ret.push(word.charAt(0).toUpperCase());
			ret.push(word.substr(1).toLowerCase());
			return ret.join('');
		}
		var pattern = /\b(ma?c)?([a-z]+)/ig;
		return name.replace(pattern, replacer);
	}
	
	// On document ready rig up of relevant controls (based upon using the 'fix-name-casing' class) 'blur' event. When focus is lost, in a given control, we take the controls input and format it based on a return value from fixNameCasing
	$(function() {
		$(".fix-name-casing").blur(function() {
			$(this).val(fixNameCasing($(this).val()));
		});
	});

</script>

The results! Each field in the following screenshot received fully lowercase or uppercase input before being tabbed out of (i.e. lost focus):

Image showing name capitalisation of three example name fields.

Name Capitalisation Test Output.

Lastly, here’s the entire code snippet:

<!DOCTYPE html>
<html>
<head>
	<title>Name Capitalisation Test</title>
	<style type="text/css">
		
		.control-top-margin {
			margin-top: 5px;
		}
	
	</style>
	<!--Bring jQuery into scope so we can hook up a function to relevant elements on 'blur' event (lost focus)-->
	<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script>
	<script type="text/javascript">
		
		// The name casing fix function utilising regex
		function fixNameCasing(name) {
			var replacer = function (whole, prefix, word) {
				ret = [];
				
				if (prefix) {
					ret.push(prefix.charAt(0).toUpperCase());
					ret.push(prefix.substr(1).toLowerCase());
				}
				
				ret.push(word.charAt(0).toUpperCase());
				ret.push(word.substr(1).toLowerCase());
				return ret.join('');
			}
			var pattern = /\b(ma?c)?([a-z]+)/ig;
			return name.replace(pattern, replacer);
		}
		
		// On document ready rig up of relevant controls (based upon using the 'fix-name-casing' class) 'blur' event. When focus is lost, in a given control, we take the controls input and format it based on a return value from fixNameCasing
		$(function() {
			$(".fix-name-casing").blur(function() {
				$(this).val(fixNameCasing($(this).val()));
			});
		});

	</script>
</head>
<body>
	<div id="container">
		<!--An example form illustrating the fixNameCasing function being called on a test forename, middle names and surname field (when focus is lost)-->
		<form action="/" method="post">
			<div>
				<label id="forename-txt-label">Forename:</label>
			</div>
			<div>
				<input id="forename-text" name="forename-text" class="control-top-margin fix-name-casing" type="text" />
			</div>
			<div>
				<label id="middlename-text-label">Middle names:</label>
			</div>
			<div>
				<input id="middlename-text" name="middlename-text" class="control-top-margin fix-name-casing" type="text" />
			</div>
			<div>
				<label id="surname-text-label">Surname:</label>
			</div>
			<div>
				<input id="surname-text" name="surname-text" class="control-top-margin fix-name-casing" type="text" />
			</div>
			<div>
				<button id="submit-button" type="submit" class="control-top-margin">Submit</button>
			</div>
		</form>
	</div>
</body>
</html>

The likelihood is that I’ll be using this just as a basis for my current requirements and adjusting as needed.

I hope this proves useful and kudos to my friend who found this and the original stackoverflow contributor. If anyone has any other examples of code that tackles this problem, that they would like to contribute, just let me know by commenting below.

Cheers!

Implementing reCAPTHCA

I wanted to outline some recent work I’ve done with the reCAPTCHA Google API. Although not too difficult to implement, I did struggle a little to find C# based server side examples on how to ultimately validate a CAPTCHA. To start us off however, what is reCAPTCHA?

reCAPTCHA is essentially a mechanism to protect your sites functionality from spam and other kinds of abusive activity. It’s free, which is a massive bonus, and as a cherry on top every solved CAPTCHA is used to annotate images and build on machine learning datasets. This data feeds into solving a myriad of problems, including improving maps and solving AI conundrums. The actual term is an acronym for Completely Automated Public Turing test to tell Computers and Humans Apart. For any history buffs, details on how this concept came about can be found here (in fact, there seems to be an interesting ‘origin of’ debate here):

Wiki CAPTCHA Documentation

And something a bit more fun:

To get started using reCAPTCHA, and for further information, you just need to visit the following link:

Google reCAPTCHA

Utilising reCAPTCHA version 2.0 seemed like the way to go for me and has a number of benefits. For example, it’s possible for this implementation to automatically confirm some requests as not being malicious in nature, without the need for a CAPTCHA to be solved. In addition, the CAPTCHAs themselves in version 2 are much nicer for a human to solve, relying on a party to pick out characteristics in an image, rather than trying to read ever more complex and convoluted character strings embedded in a given image. Image resolution (to pick out particular objects) is still a field whereby programs struggle somewhat, so this form of reCAPTCHA falls into a more secure bracket also.

Using reCAPTCHA

The basic process boils down to following these steps:

  • Go to the Google reCAPTCHA site and click on Get reCAPTCHA.
  • Sign in or sign up, do what you’ve got to do!
  • Register the domain where you want to embed reCAPTCHA. This will enable you to receive the relevant API keys to create and validate CAPTCHAs.
  • Add the relevant JavaScript to your page.
  • Embed the Site key in the page being served to the user (we’ll go over this below).
  • Use the Secret Key in your server side logic to validate the CAPTCHA response (based on user input). This is done by sending a request to the Google API siteverify address. Again, I’ll cover this below.
  • Get the response and see if the CAPTCHA has been solved correctly, simple as that.

First things first, you’ll want to safely note down your Site and Secret key for further use, these can be viewed again at any time by logging into the reCAPTCHA portal (where you signed up). So you’ve registered your domain and have the relevant keys, we now need to embed reCAPTCHA by adding the following element to the page you want to target:

<head>
...
    <!--Use async/defer as necessary if you desire-->
    <script src='https://www.google.com/recaptcha/api.js'></script>
...
</head>
<body>
    ...
    <!--The id attribute is not absolutely required, but I have listed it here as I make further use of (basically a style choice) for an jQuery AJAX call (could just use the class however)-->
    <div id="g-recaptcha-response" class="g-recaptcha" data-sitekey="YOUR_SITE_KEY_GOES_HERE"></div>
    ...
</body>

Be sure to drop the Site key you were provided with in the data-sitekey attribute, within the div outlined (and add the JavaScript reference listed to your page). Load up your page and you should see something akin to the following:

reCAPTCHA V2 Control.

reCAPTCHA V2 Control.

This is a super start. If you are doing a simple post on submit, you’ll be able to pull information out of the standard request object and use this server side. For me however, I wanted something incredibly lightweight so I went with the following jQuery AJAX call (I may tweak this in my personal implementation so treat this as not yet finalised, but it provides you with an idea of the structure nonetheless):


//Defines an outline (structure) for a javascript contact object
function Contact(name, email, message, recaptchaClientResponse) {
	this.Name = name
	this.Email = email;
	this.Message = message;
	this.RecaptchaClientResponse = recaptchaClientResponse;
}

...

//Submit Enquiry button click handler
$(".submit-enquiry").click(function (e) {

	//Hide the alert bar on every new request (TODO - More code required to tidy up classes on the alert div)
	$(".alert").hide();

	//Use ajax to call the service HandleEmailRequest method
	$.ajax({
		cache: false,
		async: true,
		type: "POST",
		dataType: "json",
		processData: false,
		data: JSON.stringify(
			{
				contactObj: new Contact
					(
						$("#NameTextBox").val(),
						$("#EmailTextBox").val(),
						$("#MessageTextArea").val(),
						$("#g-recaptcha-response").val()
					)
			}),
		url: "URL_TO_A_SERVICE.svc/HandleEmailRequest",
		contentType: "application/json;charset=utf-8",
		success: function (evt) {
			//Evaluate the response and add content to alert bar
			if (evt.SendEmailResult)
			{
				$(".alert").addClass("alert-success").html("<p>Message successfully sent!</p>").slideDown(1000);
			}
			else
			{
				$(".alert").addClass("alert-danger").html("<p>We couldn not send the message, sorry about that.</p>").slideDown(1000);
			}

			//Reset the recaptcha control after every request
			grecaptcha.reset();
		},
		error: function (evt) {
			//Add content to the alert bar to show the request failed
			$(".alert").addClass("alert-danger").html("<p>We could not send the message, sorry about that.</p>").slideDown(1000);

			//Reset the recaptcha control after every request
			grecaptcha.reset();
		}
	});
});

The first part of this code encapsulates the idea of a contact, in my case at least (i.e. a user leaving a message on the web page that will become an email). This is just an easy way for me to encapsulate details during the AJAX call. Using jQuery, I’ve attached a handler to the submit button on my page which, apart from a little UI manipulation (for an alert bar element), in essence just makes a call to a service (via the url parameter) using details that the client has provided, including information on the solved CAPTCHA. This is passed to the service using the data parameter; note the use of jQuery to get details of the CAPTCHA the user has completed ($(“#g-recaptcha-response”).val()). This is passed as JSON to the service. Once a request has been validated, the return value (a simple boolean in my case) is inspected and an alert is shown to the user before resetting the reCAPTCHA control (another spam control mechanism that I’ve added in for extra peace of mind). Lastly, for me, the use of JSON.stringify was absolutely key as I want to work with JSON data over the wire. More details can be found here:

JSON.stringify() Documentation

This is where it got a little trickier to proceed. On the reCAPTCHA documentation site, for version 2.0, I could only see examples for PHP:

reCAPTCHA Code Examples Available.

reCAPTCHA Code Examples Available.

So, what you’ll see next is the culmination of my digging around for a jQuery/AJAX/C# solution to this particular head-scratcher. Hopefully, it proves useful to anyone interested in going down this route.

Let’s get going! On the service side, you’ll need something like the following, to gather up the AJAX request:

/// <summary>
/// Represents a Contact (Potential Customer) contacting
/// the recipient with an enquiry.
/// </summary>
[DataContract]
public class Contact
{
	#region Automatic Properties (Data Members)

	/// <summary>
	/// The Contacts full name.
	/// </summary>
	[DataMember]
	public string Name { get; set; }

	/// <summary>
	/// The Contacts email address.
	/// </summary>
	[DataMember]
	public string Email { get; set; }

	/// <summary>
	/// The Contacts message to the recipient.
	/// </summary>
	[DataMember]
	public string Message { get; set; }

	/// <summary>
	/// A string that represents the clients reCAPTCHA
	/// (V2) response (passed along with other Contact
	/// information and processed before a message can be sent).
	/// </summary>
	[DataMember]
	public string RecaptchaClientResponse { get; set; }

	#endregion Automatic Properties (Data Members)
}

...

/// <summary>
/// Outlines the HandleEmailRequest method that is part of this service.
/// Consumes and returns a JSON format message (called from the client
/// with details that instantiate a Contact object). Method designed to 
/// process reCAPTCHA details and, on success, send an email to
/// the designated (recipient) email address. 
/// </summary>
/// <param name="contactObj">Contact details associated with the person requesting information.</param>
/// <returns></returns>
[OperationContract]
[WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Json, ResponseFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped)]
bool HandleEmailRequest(Contact contactObj);

...

/// <summary>
/// Public service method that attempts to send a
/// user message to the recipient as an email.
/// </summary>
/// <param name="contactObj">The Contact object constructed from JSON (passed from the client).</param>
/// <returns>A boolean that represents if this process was successful.</returns>
public bool HandleEmailRequest(Contact contactObj) => new EmailSender(contactObj).SendEmail();

I’ve given you a roll-up of an example Contact class (that is instantiated from the JSON automatically on call to the service), an example service interface definition and the outline of a service method (contained in a class implementing this interface). These of course are in separate files, but I’ve lined them up side-by-side to make it easier to absorb. In my case, the details are passed to and wrapped in an EmailSender class, the reCAPTCHA validation being called internally by the SendEmail method (as a private method called ValidateRecaptchaClientResponse):

/// <summary>
/// Private helper method that looks at the Contact object
/// associated with this EmailSender and attempts to verify
/// if the reCAPTCHA client response is valid (before attempting to
/// send an email message to the recipient). 
/// </summary>
/// <returns>A boolean that represents if reCAPTCHA validation succeeded or failed.</returns>
private bool ValidateRecaptchaClientResponse()
{
	//Online reference used as a basis for this solution: http://www.codeproject.com/Tips/851004/How-to-Validate-Recaptcha-V-Server-side
	try
	{
		//Make a web request to the reCAPTCHA siteverify (api) with the clients reCAPTCHA response. Utilise the Response Stream to attempt to resolve the JSON returned
		HttpWebRequest wr = (HttpWebRequest)WebRequest.Create(string.Concat("https://www.google.com/recaptcha/api/siteverify?secret=YOUR_SITE_SECRET_KEY_GOES_HERE&response=", contactObj.RecaptchaClientResponse));

		using (WebResponse response = wr.GetResponse())
		{
			using (StreamReader sr = new StreamReader(response.GetResponseStream()))
			{
				//Use a JavaScriptSerializer to transpose the JSON Response (sr.ReadToEnd()) into a RecaptchaResponse object. Alter the 'Success' string of this object to a bool if possible
				bool success = false;
				bool.TryParse(new JavaScriptSerializer().Deserialize<RecaptcaResponse>(sr.ReadToEnd()).Success, out success);

				//Return a value that denotes if this reCAPTCHA request was a success or failure
				return success;
			}
		}
	}
	catch (Exception ex)
	{
		//Catch any exceptions and write them to the output window (better logging required in future). Return false at the end of this method, issue occurred
		System.Diagnostics.Debug.WriteLine($"An error occurred whilst validating the ReCaptcha user response. Type: { ex.GetType().Name } Error: { ex.Message }.");
	}

	//If we hit this portion of the code something definitely went wrong - Return false
	return false;
}

Lines fourteen and twenty two are of the most interest here. On line fourteen, you will be required to insert your site ‘Secret key’ into a request to the siteverify address we mentioned earlier. The response that needs to be appended to this string is equal to the reCAPTCHA information you gleaned from the client. You’ll notice that line twenty two makes use of a RecaptchaResponse type; which is basically an object wrapper used to contain information from the deserialised JSON response (as part of a reCAPTCHA check). This is outlined as follows:

/// <summary>
/// Represents an object (constructed from JSON)
/// that outlines a reCAPTCHA Response, and the pieces
/// of information returned from a verification check.
/// </summary>
public class RecaptcaResponse
{
	#region Automatic Properties

	/// <summary>
	/// The success status of the reCAPTHCA request.
	/// </summary>
	public string Success { get; set; }

	/// <summary>
	/// The Error Descriptions returned (Possibly to implement
	/// in the future).
	/// </summary>
	//public string ErrorDescription { get; set; }

	#endregion Automatic Properties
}

The actual JSON returned from the response stream takes the following form, so it is possible to extract error codes also if you desire (for me, I’m ripping a simple boolean out of this based on the success value):

{
  "success": true|false,
  "error-codes": [...]   // optional
}

On a very last note, cited in the code above but to reiterate, this link was invaluable:

Code Project reCAPTCHA Validation Example

That’s about it for a basic end to end sample.

The API documentation (and the steps listed on the reCAPTCHA site after registration) are pretty good, so you should be in safe enough hands:

reCAPTCHA API Documentation

Thanks all and take care until the next time.

Modernizr – Detecting Screen Size Changes

A brief titbit today, but one I felt was worth sharing and has come in handy for work/personal projects recently for me.

I’ve had a couple of requirements to gracefully show/hide and adjust web page layouts based on screen sizes (and screen re-sizing). I came across the following solution which works pretty damn well.

First things first, you’ll need Modernizr, which is in essence a feature detection javascript library. In this case, however, I’m using other features to react to browser re-sizing. There’s a few options for obtaining this for your projects but, as far as Visual Studio is concerned, I used the Package Manager Console using the following command:

Install Modernizr via the Package Manager Console.

Install Modernizr via the Package Manager Console.

Once installed, we end up with the javascript library included under the default Scripts folder:

Modernizr in Scripts Folder.

Modernizr in Scripts Folder.

On installing the package, as I didn’t specify a specific version, I end up with the following declaration in my packages.config file (part of my ASP.NET MVC project) – 2.8.3 denoting the most recent version:

<package id="Modernizr" version="2.8.3" targetFramework="net452" />

Next up, simply chuck the usual script element into your page to reference the library – Now you’re all set!

<script src="~/Scripts/modernizr-2.8.3.js" type="text/javascript"></script>

The following snippet shows the basic scaffolding code to start capturing screen size changes (I’ve declared this code in my jQuery document ready function). The doneResizing function is tied to the window resize event and you can easily use Modernizr to read and react to the screen size as required:

//Function to react to screen re-sizing
function doneResizing() {
	if (Modernizr.mq("screen and (min-width:868px)")) {
		//Implement jQuery/JS to handle a larger screen (i.e. Laptops/Desktops). In my case adding/removing a class to show/hide elements
	}
	else if (Modernizr.mq("screen and (max-width:867px)")) {
		//Implement jQuery/JS to handle a smaller screen (i.e. Tablets/Mobiles). In my case adding/removing a class to show/hide elements
	}
}

//Call doneResizing on re-size of the window
var id;
$(window).resize(function () {
	clearTimeout(id);
	id = setTimeout(doneResizing, 0);
});

//Call doneResizing on instantiation
doneResizing();

Currently, I’m using this to show/hide element containers within a web page based on screen size (and apply/remove a few classes on the fly to ensure everything looks as it should on desktop, tablet and mobile displays). It appears to function very well, one worth investigating for your own projects. See here for the original Stack Overflow article detailing ideas surrounding this concept (including other CSS related solutions).

Bye for now!

jQuery is just a little bit sexy!

Cramming the word ‘sexy’ into the title was a sure-fire way of drumming up some attention. I’m happy to resort to dirty tactics as I’m still rocking my noob colours :-). It’s time to take a trip down the yellow brick, urm, jQuery road? Yes, I’ve said it now, so I’m sticking with it. I’ll start this in the way I mean to continue; with all of you wondering whether I’m mentally stable…..moving on!

I’ve been having a tonne of fun with this awesome JavaScript library. So much so, I think I’ve probably been driving all of my work colleagues a little bit nuts talking about it. I’m really not winning many friends here I’m sure but jQuery is, urm, just a little bit sexy dare I say it (sorry Claire, I’m sure I’ll pay for this later!).

I’m positive that I won’t need to tell too many people what this funky little API is all about, most developer buddies I have spoken to know of it, or are well versed (much more me than) in the wonders of what this has to offer.

jQuery allows you to perform HTML manipulation and traversing of the DOM (using CSS class selectors) as well as orchestrating some neat animation tricks.

I’ll aim to cover this API in further detail but I wanted to do a little ‘bear’ bones post to get this started (sorry, I couldn’t help it, bad joke I know!).

You’ve got a couple of choices on how to bring jQuery into scope; you can use a CDN (Content Distribution Network) or simply reference it from a known directory path. This can be done by dropping one of the following into the head element of the web page:

<!--Using the jQuery CDN (and using a designated version)-->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

<!--Using the Google CDN (and using a designated version)-->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

<!--Using a downloaded version of the file (stored within the _js directory of the website in this case)-->
<script type="text/javascript" src="_js/jquery-1.11.1.min.js"></script>

I’ll dodge the downloaded file vs CDN debate for now and just concentrate on jQuery’s usage, mainly due to the fact that I get the impression this incites violence among normally civilised folk.

For the purposes of a quick showcase I’ll utilise the jQuery ready function (as we’re going to be manipulating loaded HTML I want to make sure that this process is fully completed before the tinkering begins – Placing code in this function removes the possibility of us attempting to reference unloaded parts of the page).

Immediately beneath the script tag created to bring jQuery into scope bang in the following code:

<!--Add the long-hand ready function declaration to perform actions once the page HTML is loaded-->
<script type="text/javascript">
	//Long hand ready function declaration
	$(document).ready(function () {
		//Code goes here, for instance...
		console.log("Hello world! In the ready function!");
	});
</script>

I’ve decided though, with barely a second thought for the poor long-handed approach, to adopt the short-hand declaration myself:

<script type="text/javascript">
	//Short hand ready function declaration
	$(function () {
		//Code goes here, for instance...
		console.log("Hello world! In the ready function!");
 	});
</script>

You’ve got some choices in regards to how you want to target your code on the various elements found on a given web page. In general, at least for me so far in a very basic sense, I’ve been targeting elements by id, class and the actual tag type (element type) as follows:

<script type="text/javascript">
	//Short hand ready function declaration
	$(function ()
	{
		console.log("Start of ready...");

		//Get access to a DOM element (pure JavaScript) using traditional means. You'll only have access to normal JavaScript members
		var headerContainer = document.getElementById("HeaderContainer");
		console.log(headerContainer.innerHTML);         //Getting container html

		//Retrieve a 'jQuery Object' based on 'id'. You'll get access to jQuery specific members this way (equals awesome). Notice the use of hash in this scenario
		var $headerDiv = $("#HeaderContainer");
		console.log($headerDiv.html());                 //Getting container html

		//Retrieve a 'jQuery Object' based on CSS Class (representing all objects using that class). Notice the use of a period before the class name
		var $specialParagraph = $(".SpecialParagraph");
		console.log($specialParagraph.text());          //Getting element content

		//Retrieve a 'jQuery Object' by tag type (again, representing all objects using that element type). Just specify the element type using a string, no special prefix required
		var $h1Elements = $("h1");
		console.log($h1Elements.text());                //Getting element content

		console.log("End of ready...");
	});
</script>

Here, you can see that there are a couple of nuances when compared to selecting elements via pure JavaScript. The first is the use of the ‘$’ character, which is basically short-hand for specifying ‘jQuery(“selector”).function()’ – Essentially you’re using saying, “hey, I want to work with a jQuery Object please.”. Next up, you’re required to pop in a couple of parentheses and between these you provide a string specifying a ‘selector’, in turn denoting what kind of element/s you are trying to retrieve, and ultimately manipulate. Using an ‘id’ requires you to prefix the value with a ‘#’ and a CSS class requires a ‘.’ prefix. Grabbing elements by type doesn’t require a specific prefix at all so just place in the element you’re looking for and you are good to go.

In the examples above I have stored the DOM Objects and jQuery Objects in variables before operating on them. So far, I’ve been lead to believe that some developers prefix jQuery Object variables with a ‘$’ just to avoid any ambiguity in relation to any DOM Object variables sitting nearby, so I’ve followed this format. Anyone who stumbles along this with thoughts on whether this is correct please feel free to drop me a comment; I’d love to know how developers have decided to proceed in regards to variable naming conventions in production level code.

Just for simplicity, I’ve utilised the innerHTML property on the DOM Object and the .html() and .text() functions on the jQuery Objects (to get the selected elements HTML and text content respectively) and pushed these out to the console. The results of this can be seen below:

Various jQuery selectors in action.

Various jQuery selectors in action.

In order to have a little play around and provide a few simple illustrations of jQuery’s usage I’ve knocked up, what I’m sure you’ll agree, is some of the worlds greatest HTML markup (added to the pages body element) – Booyah:

<div id="HeaderContainer">
	<h1>jQuery Test Site</h1>
	<p>Welcome to the wonderful jQuery test website where we are going to do, urm, not a hell of a lot really.</p>
	<p class="SpecialParagraph">Only people who like craft beer see this paragraph.</p>
</div>
<div id="MainContainer">
	<h2>Here is a list box of my favourite things:</h2>
	<select id="GreatThingsListBox" multiple="multiple">
		<option>Chocolate Cake</option>
		<option>Chocolate Brownie</option>
		<option>Chocolate Something or Other</option>
		<option>Craft Beer</option>
		<option>Video Games</option>
	</select>
</div>
<div id="AnotherContainer">
	<button style="height: 35px; width: 75px" id="ClickMeButton">Click Me!</button>
</div>

So, I won’t be winning any awards for that! I’ve been staring at the colour palette of the test site whilst creating this post and I’m definitely starting to feel a tad nauseous; get the sick buckets at the ready :-).

Firstly, lets take a look at a quick example that shows the simplicity of jQuery at work. The first code snippet shows my attempt at using JavaScript to retrieve all ‘option’ elements on the page. After retrieval, I do a loop through the found elements and call setAttribute to add a title attribute based on the text value of the option:

<script type="text/javascript">
	//Short hand ready function declaration
	$(function () {
		//Possible approach, using pure JavaScript, for adding title attributes to 'option' elements
		var greatThingsListBox = document.getElementsByTagName("option");

		for (var i = 0; i < greatThingsListBox.length; i++) {
			greatThingsListBox[i].setAttribute("title", greatThingsListBox[i].text);
		}
	});
</script>

Here’s the same thing using jQuery (using the .each() function to iterate over the found ‘option’ elements).

<script type="text/javascript">
	//Short hand ready function declaration
	$(function () {
		//Set the title attribute on every option element (based on the options value) - using jQuery
		$("option").each(function () {
			$(this).attr("title", $(this).text());
		});
	});
</script>

The .each() function can be passed a normal JavaScript function name (which will run for each item selected), but in this case I’ve used an anonymous function call. Within this function, and this is something that I really love, it’s a real cinch to get hold of the jQuery Object currently in scope using the ‘$(this)’ syntax (this is the current ‘option’ element). Not specifying the $(this) enables you to act on each element as a traditional DOM element if you want/need to. From a keystrokes perspective, and I think readability, we’re onto a winner.

This is the end result of the above jQuery code (my cursor is placed over the List Box item):

Title attributes (resulting in tool tips) added to each list item.

Title attributes (resulting in tool tips) added to each list item.

Looking at the page, you’ll notice that we have a very special paragraph implemented in the ‘HeaderContainer’ div. If you’re not a craft beer drinker like myself then I would really like to hide this element from view (p.s. beer comments/recommendations welcome to!). jQuery provides a very tidy and convenient way to accomplish this task via the use of the .hide() function.

Note: from this point forward I’ll be omitting the ready function declaration to simply emphasise the jQuery code snippets themselves:

//Hide the paragraph with the '.SpecialParagraph' CSS class
$(".SpecialParagraph").hide();

This removes the paragraph from view as show below:

Paragraph hidden via jQuery.

Paragraph hidden via jQuery.

A quick sniff around the DOM using your browser development tool of choice will indicate that jQuery has applied a style to the element in reaction to the .hide() function call (style=”display: none”). I think you’ll agree this is nice and simple, and with the power of using CSS selectors it’s quite easy to target a number of elements simultaneously. Also, for me, it’s just so darn readable; I’ve really found the syntax incredibly easy to pick up and play with. It’s clear to see that one of the core crowd pulling powers of jQuery is that it’s not all that intimidating and papers over some of the inherent complexities of JavaScript quite nicely. Put simply, it’s bonza!

Once you’ve brought a shiny jQuery Object into scope you are free to draw on a concept called ‘Function Chaining’ where multiple functions can be called on the object using a single statement. Syntactically and aesthetically, coming from a C# background with a serious love of LINQ and extension methods, this ticks all of the right boxes for me.

The code snippet below first hides our special paragraph (using the CSS class applied as the selector), then applies a small piece of custom CSS using a construct called an Object Literal (essentially, property/value pairs) and finally uses the .slideDown function to elegantly animate the paragraph into view, over the specified time frame:

//Retrieve a jQuery Object representing elements with the SpecialParagraph class and hide them on load (just the one is this case). But this time,
//use 'function chaining' and apply some custom css (or we could have called addClass to apply some kind of style) and animate the paragraph/s
//so they 'slide' down into view
$(".SpecialParagraph").hide().css(
	{
		"background-color": "black",
		"color": "red"
	}).slideDown(1500); //Slide down into view over 1.5 seconds
Paragraph sliding into view (with a bit of custom CSS applied).

Paragraph sliding into view (with a bit of custom CSS applied).

Hooking up to events is also a doddle. For example, to hook up a click event to a selected element/s you can call the .click() function and pass it an anonymous function or an existing raw JavaScript function that performs the required task, as below:

//Rig the ClickMeButton's (selected by id here) click event up (tied to an anonymous function in this case)
$("#ClickMeButton").click(function () {
	alert("Click me clicked. I could really do some complicated work now!");
});
//JavaScript function to handle the click
function respondToClick() {
	//complicated code goes here
	alert("Click me clicked. I could really do some complicated work now!");
}

//Short hand ready function declaration (included in this example to provide context)
$(function ()
{
	console.log("Start of ready...");

	$("#ClickMeButton").click(respondToClick); //Could just be a raw JavaScript function

	console.log("End of ready...");
});
Example of a click event firing using jQuery to tie the event up to the element.

Example of a click event firing using jQuery to tie the event up to the element.

Moving further down this lovely yellow brick road, and this is something I’ve really enjoyed playing around with, it’s possible to call the jQuery .on() function to bind multiple events at the same time. As before, you can hook in raw JavaScript functions or anonymous functions, the latter seems to be the order of the day from what I’ve learnt so far (and rightly so, they are ace!). In the next code snippet I’m concurrently binding a click, mouse enter and mouse leave event to a button (again, selected by ‘id’) to build a slightly more interactive element (i.e. chopping and changing styles depending on whether the mouse is over the element):

//Simultaneously hook up the ClickMeButtons click, mouseenter and mouseleave events to various anonymous functions. 'On' comes in handy for 'event delegation'
//which I'll cover in a future post
$("#ClickMeButton").on(
	{
		"click": function () {
			console.log("click.");
			alert("Click me clicked. I could really do some complicated work now!");    //Handle a 'click'
		},
		"mouseenter": function () {
			console.log("AltStyle added.");
			$(this).addClass("AltStyle");                                               //Add the AltStyle to this element on 'mouseenter'
		},
		"mouseleave": function () {
			console.log("AltStyle removed.");
			$(this).removeClass("AltStyle");                                            //Remove the AltStyle from this element on 'mouseleave'
		}
	});
jQuery 'on' function example in motion.

jQuery ‘on’ function example in motion.

The on(). function has a very unique part to play in relation to the concept of Event Delegation, which I’ll cover fully in a later post. To serve as a very brief example, you may have an existing unordered list (ul) element on a web page, simply with no list items yet (li elements). The list items are dynamically created at some point after the page has loaded, perhaps on a button click for instance. In this scenario, if you wanted to tie a click event to each list item, you would have to do it on creation of each element (plus each item would require a separate handler which might not be all that yummy once the list becomes larger). This couldn’t be achieved on page load as the elements wouldn’t exist yet. With Event Delegation it is possible to palm off the click event to the parent unordered list element on load for any list items added later on to respond to, reducing stress levels and hair loss for the developer.

Rounding off the ‘cool’ factor of jQuery I wanted to show you an example of the hover function with a simple animation routine plugged in. I’ve rigged the code formatting a little to make this a little more readable. As I am used to C# formatting I still find the default placement of braces a little annoying from time to time when formatting via Visual Studio. Here’s the weird and wonderful snippet anyway:

//Utilise the hover function on the ClickMeButton that allows you to specify two anonymous functions (or tie in two existing javascript functions). The first one
//handles mouseenter and the second one handles mouseleave. In this example we are using .animate() to manipulate a buttons height/width. The jQuery UI API allows
//you to animate colour transitions and allows you to utilise some interesting 'easing' functions if you bring this into scope also
$("#ClickMeButton").hover
	(
		//Mouseenter
		function ()
		{
			console.log("Entering element.");

			//Make the button larger over half a second. Calling .Stop prevents animations from 'queuing' up
			$(this).stop().animate
				(
					{
						"height": "70px",
						"width": "150px"
					},
					500
				);
		},
		//Mouseleave
		function ()
		{
			console.log("Exiting element.");

			//Make the button smaller (set back to the original size) over half a second. Calling .Stop prevents animations from 'queuing' up
			$(this).stop().animate
				 (
					 {
						 "height": "35px",
						 "width": "75px"
					 },
					 500
				 );
		}
	);
Button before the hover event fires.

Button before the hover event fires.

Button after the hover event fires.

Button after the hover event fires.

The hover function is a compound function that enables the developer to simultaneously handle the mouse enter and mouse leave events in a single statement. I class this as simple syntactic sugar, but I love it all the same (give me lambdas and anonymous methods any day thank you!). This probably boils down to the fact that I’m easily pleased by the smaller things in life.

As the snippet above shows, the hover function is taking two separate anonymous functions as arguments. I’ve coded these functions to manipulate the elements height and width properties, using the .animate() function, to alter the values over a specified time frame.

jQuery UI, another branch off from jQuery, enables more complex animation effects to be kicked off (such as animating an elements colour properties). It’s certainly something to check out if you’re finding any of this interesting.

If you want an easy way to add, remove, copy and move HTML content on the fly easily then you’re really in luck here. There are a good number of functions built-in that will enable you to get your head down and deal with the task of handling changing HTML content dynamically. This next example illustrates one of the more basic functions, .append(), which enables you to specify a string of HTML content to place at the end of the selected element/s:

        //When theClickMeButton is clicked append HTML to the List Box (select element)
        $("#ClickMeButton").click(function () {
            //Add a new hard-coded option to the List Box (this would obviously be a much more dynamic example)
            $("#GreatThingsListBox").append("<option>Coding</option>");

            //Grab the last 'option' element on the page and set it's title attribute based on the text value (giving us a nice little tool tip)
            //You could do this by using: $("option").last().attr("title", $("option").last().text()); but storing the jQuery Object in a variable saves on processing (i.e the re-selection of the element)
            var $lastOptionOnPage = $("option").last();
            $lastOptionOnPage.attr("title", $lastOptionOnPage.text());
        });

This last snippet introduces the Event Object, which can be specified as a function parameter (which the engine is implicitly passing for use) and used within an anonymous function. This stores handy nuggets of information about the event that has been fired. In this case, I’m just pushing screen co-ordinates to the console to illustrate where a click occurred:

//Using the event object (any parameter name can be picked, I'm using 'evt') and pulling out the current screen co-ordinates on click
$(document).click(function (evt) {
	console.log("X Co-ord: " + evt.pageX + ", Y Co-ord: " + evt.pageY);
});
The Event Object in action.

The Event Object in action.

The post is nowhere near as short as I would have liked but I have developed a bit of a soft spot for jQuery so I’ve gone over the top. Why the hell not I guess, it’s free, reliable and heavily used and distributed under an MIT licence, what’s not to like! Whilst I’m on a ‘love rant’ I may as well mention that an extensive amount of Plug-Ins are available, adding to the fun in my opinion. It’s also incredibly easy to draw out hidden and selected elements using jQuery (i.e. from a set of check boxes, for example), so read up if you’re interested. I hope you’ve enjoyed the first, real, coding post. Enjoy, like, comment, subscribe, talk to me about craft beer and code, etc. Whatever takes your fancy.

I haven’t decided on my next topic yet but I’d like to get something out of the door by the end of the week, so watch this space. Cheers to Pete for the jQuery book you’ve loaned me and to Claire for reading through this (it would have been much messier without your intervention!).

DISCLAIMER: All of the code snippets were ruined seconds before posting by the proof reading tool so I had to mend them on the fly, with any luck I’ve caught all of the screw ups!

Useful links:

jQuery Website
jQuery API Reference Guide
The Missing Manual Series JavaScript and jQuery

Cheers all!