CodingMonk

New Fruit in the 2010 New Lease Resolution

Jim Fisher — Sun, 18 Jul 2010 04:16:26 GMT

So...

What's up?

It's, uh, already that time again, isn't it? Another year, another renewed lease for my domains. I'm pleased to say that, true to my 2009 new lease resolution, I was able to successfully produce an unprecedented two posts in a year! Amazing, right?

Ahem.

Yes, well. Despite my somewhat limited blogging, things have been reasonably active on the world's technology front. The last twelve months have brought us a new version of Visual Studio, Silverlight, Expression Blend, Subtext, various Android phones, the Nook, and that other company released the iPad among other things.

I confess that I've been nursing a bit of envy at that last one with touch interface, so a few months ago took the plunge and bought some new Apple hardware. Expect the next year here at the Monk to bring articles describing a how to develop on these devices, especially the iPad, written from a Windows-man's perspective.

Hopefully we'll see more than two. This one, categorized under "iOS" on the "Zone menu" to the left, should kick us off and explain just what kind of crazy has possessed me.

Postcards from Apple Land: A Venture into Enemy Territory

Jim Fisher — Sat, 17 Jul 2010 00:50:29 GMT

I don't know what's gotten into me. Some creepy form of mid-life crisis I suppose, but yes. I can confirm the rumors are true:

I bought a Mac.

As I rationalized it to an associate, this doesn't mean for me what it may for others:

"When people say they decided to get a Mac, it often means they replaced their PC with a Macintosh. Fat chance. I've still got my main workstation (Win7), my test box (Vista), my general purpose server (Win Server 2008), my Tablet PC (Vista), my living room Media Center (Win7), my MAME-based arcade machine in the game room (XP), plus a slew of Windows laptops, net-books, and desktops used by my wife and kids or sitting in the garage waiting for the right project to come along.

"I haven't exactly thrown Microsoft away and moved over to the dark side."

Yes, cognitive dissonance and I are good friends.

So what events led to me committing the eighth deadly sin?

It was actually a progression. My wife gave me an iPhone for my birthday (much as Eve tempted Adam with an Apple, I believe) and I had the opportunity to experience firsthand the tactile interface and infrastructure Apple has put together for developers to sell their work. Shortly after, I picked up an iPad. Same touch interface, same application infrastructure, much bigger screen. I just couldn't help myself.

It took all of a minute for the developer in me to raise his head and begin eyeing it as a fresh, new platform with a prebuilt, thriving distribution network. Development for the iPad seems like something too big not to look into. And, of course, you can only do that on a Mac (or a Hackintosh, but I looked into that and it seemed less trouble to just buy the Mac mini).

So yes, I've an iPhone, an iPad, and a Macintosh.

And it makes me feel kinda dirty.

You may say I'm a Judas, but I'm not the only one.

One thing is for certain: I'm not alone. Since the release of the iPhone, internet forums and newsgroups have be inundated by developers asking if there's a way to write apps for these devices from a Windows machine and while I've seen a little headway in this department with so-called "jail broken" devices, and promises of bigger things to come, for now Apple has taken steps to ensure that nearly all iPhone/iPad development is restricted to those machines running OSX. Because of this, I'm confident that right now there are quite a few Windows developers in the same boat I am, looking to find their way around the development offerings of Apple and hoping to realize their iOS solutions.

In Lennon's words: "Imagine all the people".

If recording my experiences along the way can help save trouble for others... well, that's what CodingMonk is all about, right? Following the convention, I've added a new category to the site: "iOS", since this is Apple's operating system for all of their so-called iTouch devices: "iPod Touch", iPhone, and iPad.

Disclaimer

Despite my affinity for Windows, I should confess up front that I haven't started this journey as a complete n00b to non-Microsoft offerings. I spent a decade or so paying hobbyist homage to Linux, so Apple's shift to Posix compliancy with OSX translates into a measure of fluency for me. Augmenting this is the mental osmosis accompanying a few years sharing my study with my wife's "Macintoy". So I'm not really jumping into waters uncharted. As such, when I record my explorations, I might paint the Apple landscape less critically than some fellow Windows fan-boys feel I ought. To those peers of mine, please accept my sincere apologies. That said, I've spent the last couple of decades with a decided aversion to the Macs in general and Apple specifically. This too may influence my opinions against the Mac unfairly, so to the Apple aficionados out there, ditto.

Next article I'll dive a little into the technologies.

Downloads and Watermarks

Jim Fisher — Sun, 02 May 2010 08:02:34 GMT

I was able to find some time and put a little work into the site this weekend. The end result is a presentation for the site downloads. The downloads folder has been there for a while, slowly collecting files which either accompany postings or I just find useful to put there, but it hasn't had a unified face.

Well, now it does. You'll find it by following the "Downloads" link in the "action menu" across the top of the page.

Here you'll find items such as the TextboxEditMask or the sample Java Script Application Code Library (JACL), both of which have been discussed in previous postings. Additionally, you'll find a couple of things that have no accompanying articles, such as the TextboxWatermark behavior, or the DatabaseProxy wrapper which I've been using since .Net 1.0 to streamline my SQL Server access.

As I write more articles, I'll continue to post any code samples here, but I'll also continue to throw things out there with little or no documentation. Feel free to download and toy around with anything there.

The TextboxEditMask Behavior

Jim Fisher — Fri, 14 Aug 2009 08:14:13 GMT

Behaviors, which implement a mechanism for wrapping control functionality into reusable blocks, were introduced in Expression Blend 3. They're not a new concept; packaging control event handlers in a separate, reusable class has been possible since .Net was first introduced. What is new is the seamless integration with a Visual Designer (in this case, Expression Blend). Behaviors enable a truly great design-time experience when applying custom functionality to UI controls. Something that, until now, has required an unwieldy amount of custom code.

The TextboxEditMask behavior, as you might guess from the name, adds edit mask functionality to a textbox. It comes in both Silverlight and a WPF flavors. You can:

Download the source code as a Visual Studio 2008 project and compile it yourself, or
You can just Trust the Monk with the pre-compiled DLLs.

[Note: the above two links reference the 1.1 version of this behavior]

Behaviors: the Quick Run Down

This isn't a tutorial on behaviors, so I won't delve too deeply into the details of their usage, but at the time of this writing they really are a relatively new feature on the Expression Blend landscape, so a quick step through of their use is in order:

Step one: Reference the DLL. For this article, choose either:

CodingMonk.Wpf.Behaviors.TextboxEditMask.dll
CodingMonk.Silverlight.Behaviors.TextboxEditMask.dll

depending on your project type.

Step two: Drag the behavior from your "Assets" pane and drop it on to a control (in this case, a TextBox control). This creates an instance of the behavior and applies it to the control.

Finally: Select the behavior you've just applied from the "Objects and Timeline" pane:

Properties of the TextboxEditMask

After selecting an instance of the TextboxEditMask behavior, three custom properties will show in the "Properties" pane:

The first, EditMask, holds the pattern to be enforced. This mask should conform to the CodingMonk Edit Mask notation (version 1.1). The notation is relatively easy to learn, especially if you've had experience with more exhaustive notations such as Regular Expressions.

The second parameter, MatchCaseToMask, is a checkbox. This is off by default, rendering the edit mask case-insensitive. This means when a letter appears in an edit mask, either the upper or lowercase version of that letter is allowed. If the pattern calls for the capitol letter "A", the lowercase "a" would also be accepted and displayed as lowercase. Checking this box causes the text to conform to the case of the pattern. In this example, the lowercase "a" would still be allowed as input, but it would be rendered in uppercase in the textbox.

The final parameter, PadEmptyBehavior, is a drop down list with the two possible options:

InferCharacter
UseUnderscore

These effect what is displayed when backspaces and deletes occur. Since edit masks are typically fixed width, the backspace and delete keys have the effect of replacing the next and previous character. InferCharacter, the default, makes a decision based on allowable characters in the pattern. The alternative, UseUnderscore, simply enforces an underscore for character positions not yet filled in.

Coding Considerations

Although behaviors are currently an Expression Blend feature, TextboxEditMask allows you to set its properties and call methods from within your source code as well. To do this, you must first get a reference to the behavior. A static dictionary is provided at the class level, which allows you to lookup instances of the TextboxEditMask by the control they are applied to. For example:

TextboxEditMask phonemask = TextboxEditMask.Instances[tbPhoneNumber];

So changing the behavior's properties at runtime is straightforward:

phonemask.PadEmptyBehavior = TextboxEditMask.PadEmptyCharacter.UseUnderscore;
phonemask.EditMask="(###)###-####";

The TextboxEditMask behavior offers an additional helper property, MaskCompliantEmptyText, for your code. This property provides a string of text that effectively represents an empty value which is compliant to the current EditMask property. This is helpful when clearing a field to nothing:

tbPhoneNumber.Text=TextboxEditMask.Instances[tbPhoneNumber].MaskCompliantEmptyText;

Which, following the previous lines of code, would set the textbox display to:

(___)___-____

It's worth pointing out that the edit mask doesn't try to outthink you (the developer), and it doesn't try to undo what you assign in code. So if your edit mask defines a pattern meant for a time in 12 hour format:

[ 01]#[*[ 0]#|1[0-2]]:[0-5]# [AP]M

But you pre-populate it with:

malum in se

Don't be surprised if users find your app unintuitive.

Site Cleanup and New Lease Resolutions

Jim Fisher — Mon, 10 Aug 2009 08:22:09 GMT

Every 12 months I'm faced with the task of paying annual fees to renew the lease on my domains. When the time comes, and it always does, I'm accosted with a familiar pang of guilt: How little attention I pay my poor, neglected site. Am I consistent in sharing with the rest of the world the things I can contribute? Do I frequently post the my hard-earned solutions today to help some poor souls faced with the same problems tomorrow?

A quick review usually dates my last blogs sometime around... last year's domain renewal date.

For shame!

I shake my head, disappointed in myself, and reach for my credit card, resolutely declaring that this year will be different! This year, I always say, I will blog prolifically. People will come to my site and find what they need. After reading my blog, they will immediately stand and dance a jig for the obscure, yet pressing answers that they find. This time, I proclaim, my annual renewal fee won't be for naught!

And this year it's true. I swear it!

Actually, this New Lease's Resolution couldn't have come at a better time. Only a few short weeks ago Microsoft released a new version of Expression Blend, a product that I have come to hold in high regard despite my initial distaste and skepticism. Packaged with the new version of Blend is a formalization of a pattern which has been floating around in various forms for several years now. In Blend, the approach is called "Behaviors" and the UI makes using behaviors a blissful experience. Behaviors will definitely be a topic of those promised blogs.

For now, I've put a little work in on the site. A few additional empty Zones appear to the left, place holders for the content I've just sworn to deliver. If you're familiar with my site, a fan with nothing better to do than avidly follow my two blogs a year (I know you're out there), you might also notice the absence of previously existing zones related to "Interactive Fiction". When the site was in development, these articles were borrowed for the purposes of testing with actual content. If you are looking for these articles, you can still find them at www.OnyxRing.com.

Finally, I've stepped out of my box and updated the site with respect to browser compatibility. It was built originally for IE6, but after a bit of work, it now renders appropriately in newer versions (like IE8) as well as Firefox and Opera. If your browser disagrees, drop me a line and let me know.

CodingMonk Edit Mask Notation (version 1.1)

Jim Fisher — Sun, 09 Aug 2009 23:15:23 GMT

Typing in a text box is the most common means by which programs collect information from a user. Whether collecting a date stamp, a product key, or a phone number, specific pieces of information often have restrictions on their form.

For example, a person typing in a text box may choose to enter their work phone in a number of different ways:

555-1212
(800)555-1212
Same as Home
1-800-555-1212
800.555.1212

Each of these is meaningful to human eyes, but if your system needs to use this information in some way to, for example, sort, search, or power an auto-dialer, a consistent format is needed.

The most common way of enforcing a format in text is with post-input validation. That is, when the user finishes entering text, the system checks to see if the input conforms to an expected pattern. If it doesn't then the user is notified with a message resembling:

"Please use the following format to enter your number: (###) ###-####"

And this reactive approach works, technically speaking, but at the price of the user experience.

Edit mask controls allow the system to perform validation proactively, while the user is typing. If a keyed-in character doesn't comply with an expected value (the control's allowable "mask "), then it is ignored. In the previous phone number example, letters would be discarded so input such as "Same as Home" is never a possibility. As an additional advantage, edit mask controls are typically drop-and-go, requiring no additional coding. Instead, the input constraints they perform are defined by a notation. So one control could enforce a phone number pattern, then enforce a product key pattern, then enforce a weather code pattern, all by changing its "edit mask" notation.

There are a number of edit mask controls out there and all vary in intricacy. Some are quite simplistic in nature, supporting a limited list of pre-defined masks, while other are considerably less basic. On a scale from basic to sophisticated, the notation utilized in Coding Monk edit masks leans more heavily toward the sophistication side of the scale; however, this does not necessarily mean that the notation is more complex out of the gate. Simple needs mean simple notations; as edit mask needs grow in complexity, so do the edit mask patterns.

This document serves the dual purposes of reference and tutorial, defining the core notation, explaining how to use it, then finally giving examples of common edit mask patterns.

Note:

This document is distributed in a variety of media formats. If you are not viewing this online from the CodingMonk site and want to ensure the latest version, it can be found at the following URL:

http://codingmonk.com/archive/2009/08/09/codingmonk-edit-mask-notation.aspx

Quick Reference: Reserved Notation Characters

The following table lists the reserved characters used in Coding Monk's edit mask notation. In later sections, we'll explain in more detail about each of these; however, after the nuances of the notation have been digested, this tables can serve as a place to refresh your memory. Note that any character not listed here is interpreted as a literal.

Type	Character(s)	Description
Wildcards	#	A numeric digit.
	<	Any letter converted to lowercase.
	>	Any letter converted to uppercase.
	&	Any letter, regardless of case.
	@	Any alphanumeric character.
	!	Any alphanumeric character, converted to lowercase.
	^	Any alphanumeric character; converted to uppercase.
	_ (underscore)	Any character at all.
Groups	[	Begins a grouping of mask characters.
	[*	Begins a validation expression.
	]	Closes the grouping or validation expression.
	- (hyphen)	Used to define ranges of characters within groupings.
Validation	*	Used alone outside of a group to identify the start of a validation range.
Escape	\	Used to indicate that the next character should "escape" its reserved status and be interpreted as a literal character.
Repeat Expression	{n}	Where n is a number, this notation causes the preceding expression to be repeated, appearing a total of n times

Edit Mask Construction

Edit mask expressions can be complex if the edit mask requirements are complex. That said, most uses of an edit mask are basic and the more complex masks are few and far between. By the end of this document, you'll have all the tools you need to make sophisticated masks. But first, we'll cover some basic concepts.

Literals and Constants

As mentioned above, any character that is not listed in the Reserved Notation Characters table is a literal. This just means that these characters have no special meaning to the edit mask. The letter "A" simply represents the letter "A". A literal character specified by itself, which is to say an "ungrouped" literal, defines the only possible character in a given position. We call this lone-literal a constant since it cannot be changed.

The following expression demonstrates seven constants. Notice that positioning literals next to each other does not group them. They are still constants, just sequential ones:

abcdefg

In the above mask notation, the first position allows only the lowercase letter 'a', the second position only the letter 'b', the third 'c', and so on. Since each of the character positions associated with this mask allow but one possible character, they are typically filled in and locked before input begins. The user cannot change these constants. Clearly, this expression serves no purpose but that of example. For true user input, we rely on groups and wildcards.

Groups and Ranges

Groups are characters delimited by brackets ([…]) and are used to define options against which a single character can be matched. To demonstrate, let us modify our previous example by wrapping it in brackets and making it a group:

[abcdefg]

Unlike our previous example which defined seven input positions accepting one value each, this example defines a single input position accepting one of seven possible values. That is, this grouping defines a character position into which the user may type one of the letters 'a', 'b', 'c', 'd', 'e', 'f', or 'g'.

As a convenience, within groups the hyphen (or "dash") also acts as a reserved character used to represent a range of sequential alternatives. Using this technique, our previous example could have been defined as:

[a-g]

It is also possible to intermingle ranges with other character options within brackets, so that:

[xza-fj]

expands into:

[xzabcdefj]

which defines a single position allowing one of nine different characters. Note that the hyphen's special status as a reserved character is limited to groups. Outside of groupings, the hyphen is considered a constant.

Now for a glimpse forward: Brackets can also define validations. Brackets with an asterisk as the first character in their contained sequence ([*…]) are validation patterns. These are wholly different than the groupings described in this section and are mentioned only because they are delimited in a similar way (with brackets). For more on this subject see "Validation Expressions a.k.a. Regular Expressions" later in this guide.

Wildcards

Wildcards are devices used to avoid some of the tedium associated with building common groupings. There are eight special characters that are classified as wildcards. We listed them in the quick reference above, but we'll cover them again here with a little more context:

# - A numeric digit. This is equivalent to: [0123456789] (or [0-9]).

< - Any letter converted to lowercase; similar to [a-z].

> - Any letter converted to uppercase, similar to [A-Z].

& - Any letter, regardless of case ([a-zA-Z]).

@ - Any alphanumeric character; manually constructed as: [a-zA-Z0-9]

! - Any alphanumeric character; converted to lowercase. This is similar to [a-z0-9] except that capitol letters are converted rather than discarded.

^ - Any alphanumeric character; converted to uppercase. Similar to [A-Z0-9]except that lowercase letters are converted rather than discarded.

_ - Any character at all. If constructed manually, this would be a very large group indeed.

Wildcards can stand on their own, looking for all the world like a constant, but actually acting as group in its own right. Wildcards can also be embedded within proper groups, coupled together with literals, ranges, and other wildcards. For example, a four-digit hexadecimal number can be enforced with the following:

[#A-F][#A-F][#A-F][#A-F]

which could be expanded to:

[0-9A-F][0-9A-F][0-9A-F][0-9A-F]

Escape

The backslash (\) is also referred to as the escape character. It is used to "escape" the special meanings of all reserved characters (including itself). For example, the following expression:

[abc#]

will accept any one of the twelve characters: 'a', 'b', 'c', '0', '1', '2', '3', '4', '5', '6', '7', '8', or '9'.

A similar expression with a slash "escaping" the wildcard ("\#") changes things:

[abc\#]

The above notation signifies one of only four characters: 'a', 'b', 'c', or '#'.

Repeat Values

When repeating a complex character pattern a few times, or even a simple pattern several times, it is often useful to specify a repeat value. This is accomplished by wrapping a numerical value in braces immediately following the character pattern to be duplicated. By doing so, the previous example of accepting a four-digit hexadecimal number can be reduced to:

[#A-F]{4}

There are very specific rules which govern repeat values. Most of these are intuitive but we state them here in the interest of clarity:

Repeat values apply to the complete pattern for an input character, which means that they cannot occur within groupings. Typically, a repeat value is specified immediately following a group. When braces occur within brackets, they are simply interpreted as literals and so will be included in the list of acceptable input.
The repeat value must be numeric. If the value contained within the braces cannot be translated into a number, the braces will again be interpreted as character literals.
The repeat value is adjusted to include the token being repeated. That is, the parser decrements the value by one to account for the character position already defined. In the previous example with a repeat value of 4, the parser repeats the grouping three additional times (4 minus 1). This means that repeat values of one and zero have no effect. Neither suppresses the previous character pattern, and neither repeats that pattern again.

Validation Expressions (a.k.a. Regular Expressions)

So far, all of the functionality we've covered falls under the category of "iterative expressions", that is, expressions that test one-character of input at a time. For simple patterns, iterative expressions are all we need concern ourselves with. By the time the user finishes entering values into a social-security expression:

###-##-####

or a phone number pattern:

(###) ###-####

we are guaranteed to have data that is formatted as we require it, but for more complex types of data, the iterative expression falls short. Consider the following expression for a 24 hour clock:

[012]#:[0-5]#

This example pattern works well for most of the mask, accepting minutes in the range of 00 to 59 and eliminating the possibility of minutes input as 60 or above. The hour portion works reasonably well too. It allows us to enter 00 to 23 while excluding 30 or above. While this is close to what we want, it is not quite right since it also allows hours from 24 to 29 to be input. Alone, both 2 and 9 allowable. It is only when they are used together that one disallows the other. Clearly we need something more than iterative expressions to validate input.

As it happens, there is another type of notation which lends itself well to this sort of validation: regular expressions.

This is not a guide on regular expressions, there are many of those available on the internet. They are pertinent to this document, however, because they can be embedded within edit mask notation to serve as "validation expressions." To do this, we prefix a regular expression with a validation marker ('*') and enclose it in brackets as we would a grouping. The shortcomings of the previous time example can be solved by inserting the appropriate regular expression, enforcing a true 24 hour clock pattern:

[012]#[*[01][0-9]|2[0-3]]:[0-5]#

With this revision, when a user attempts to enter an invalid hour such as 29, the edit mask compares the input against the validation expression. Upon failure the caret is moved back so that the user can try again.

Note that the regular expression tests only the input from the start of the validation bracket to the previous validation marker (or the start of input if one does not exist). To limit the range of characters, you may place a single validation marker (without brackets) at the start of the pattern to input. For example, the following will allow input of two letters followed by a two-digit number between 01 and 16 (e.g.: AK16):

&&*[01]#[*0#|1[0-6]]

The validation expression test only the input since the validation marker (underlined in this example), which excludes the first two letter characters.

Sample Useful Expressions

The following are a handful of sample patterns. It should be apparent by now that this list is by no mean exhaustive, but these are included here for your convenience:

Phone number:

(###) ###-####

Social Security:

###-##-####

24 hour clock:

[ 012]#[*[ 01]#|2[0-3]]:[0-5]#

12 hour clock:

[ 01]#[*[ 0]#|1[0-2]]:[0-5]# [AP]M

Date (between 1/1/1900 through 12/31/2199):

[ 01]#[*[ 0]#|1[0-2]]/*[ 0123]#[*[ 012]#|3[01]]/*[12]#[*19|2[01]]##

A note on limitations in validation: this pattern enforces the date as much as possible in the current spec. Only values between 1 and 12 are accepted for month and only values between 1 and 31 are accepted for day; however, version 1.1 of the CodingMonk edit mask notation does not support context between separate validation expressions. So rules limiting the number of days to 30 for months 4,6, 9, and 1, as well as 28 or 29 days for month 2 depending on the year are not yet possible. Look to revision 1.2 to support this.

Percentage:

###[*100| ##| #]%

Temperature in Celsius or Fahrenheit (between 0.0 and 199.9 degrees):

[ 01][ #]#[*###| ##| #].# [CF]

IPv6 address:

[#A-F]{4}:[#A-F]{4}:[#A-F]{4}:[#A-F]{4}:[#A-F]{4}:[#A-F]{4}:[#A-F]{4}:[#A-F]{4}

Subtext & JavaScript

Jim Fisher — Mon, 18 Aug 2008 04:52:34 GMT

It's been a few months, but I've finally gotten around to finishing an article promised months ago about configuring Subtext 1.9.5b to support images when blogging from Word 2007. As chance would have it, this comes just a week after Subtext 2.0 is released.

Additionally, I've updated and posted a document written a few years ago but never released offering ways to organize your JavaScript library. This article comes along side a new zone to this site: JavaScript.

Tips for Building a JavaScript Library

Jim Fisher — Mon, 18 Aug 2008 03:19:40 GMT

You're an experienced developer. You learned a long time ago how to make your code generic and factor it for optimum reusability, neatly organizing it into tight, independent packages. Need a multithreaded web scrapper? You have a C# assembly that does that, thank you. Logging to the event viewer from T-SQL? No problem, there's that script you developed a few years ago. Want transformed text embedded in a graphic? Got it covered. The toolkit you've built over the years equips you to easily handle almost any task.

Almost.

Well… There is that bit of untidiness with your JavaScript. But everyone has that, right? I mean, with the hundreds of snippets smattered across the internet how could anyone keep those straight? Sure, you've made the obligatory attempt. You put the most often used routines into a single common include file. But the file grows with almost every new project, and each project leveraging this file uses only a fraction of its contents. The practice of monolithic includes is… unsatisfying.

Fear not. There is a better way.

About this Article

This article describes some of the impediments that make fashioning and maintaining a library in JavaScript troublesome and discusses some techniques for surmounting these obstacles. These techniques have been adopted by CodingMonk and are manifest as the JACL (JavaScript Application Code Library) framework. As such, most of the examples are given in that context, yet the techniques described here lend themselves equally well to a personal implementation.

The code depicted here has been tested under both the Firefox and Internet Explorer browsers, including Microsoft's implementation of HTAs (HTML applications). I suspect that these techniques could also be ported to additional browsers (e.g. Opera, Safari) with minimal effort.

Before going further, I'd like to make it clear that my way is not the only way. There are a number of gifted JavaScript developers around the world and I expect there exist several additional techniques not covered here. Please keep in mind that what works well for me may not fit well in the preferences of another developer.

What Makes a Code Library?

A fundamental preconception that people have when they hear the word "library" is that it is a collection of smaller parts. Although I can lump all of my scripts into a single reusable file and call it "Jim's library", that doesn't really hold true to the spirit of the word. Likewise, just as we wouldn't checkout every book from the shelves of a real library when researching English history, we shouldn't have to download the complete code when we're only using one or two of its features.

So, our library should be organized into functional modules from which we can pick and choose what we need.

This deceptively simple diktat is absent from the majority of JavaScript "libraries" available on the internet. Why? Because modules inject unexpected complexity into a library, especially highly functional ones leveraging other modules as dependencies. We'll identify some for these complexities and address them now. When we're finished, we'll have a basis upon which to build a working, expandable framework for our JavaScript library.

Modules Including Modules

As a code library matures, it's almost a given that one module will eventually need to include another. In JACL, for example, the Log module is automatically included by the Core module, so logging functionality is always available. Another example: each of JACL's self-updating controls leverages an AJAX implementation housed in the ServerRequest module.

So how do we include a JavaScript file from within another JavaScript file? Obviously the most common way to include JavaScript from HTML is with the script tag:

So from within a JavaScript file, one possibility is to leverage document.write() to inject customized script tags whenever a library module needs to meet a dependency. A la:

document.write( "<script src='http://www.codingmonk.com/jacl/jacl.js'> </script>");

One complication associated with dynamic inclusion of JavaScript: it is not immediately obvious when the included file has successfully loaded. Despite their similarities, it's easy to forget that the above two lines are not exactly equivalent. To be precise:

The first, declared within the HTML document, includes the JavaScript file while the page is first loading, but before scripts are run.
The second, processed after the page has finished loading and declared scripts are running, identifies subsequent scripts that the browser should load when it gets the opportunity.

So as rule: JavaScript included from JavaScript is not immediately available, but JavaScript included from a tag in the unmodified HTML document is.

To demonstrate, we can do this:

<html>

jacl.appMain = function(){alert("Something wicked this way comes...");};

</script>

</html>

But we can't we do this:

<html>

document.write( "<script src='http://www.codingmonk.com/jacl/jacl.js'></script>");

jacl.appMain = function(){alert("Something wicked generates an error...");};

</script>

</html>

Because the second example produces an error message in the spirit of "jacl is undefined".

A more sophisticated alternative is to leverage the browser DOM, like so:

<html>

var o=document.createElement("script");

o.src="http://www.codingmonk.com/jacl/jacl.js";

o.onreadystatechange = function(){

if(this.readyState == "loaded"){

jacl.appMain = function(){alert("Something wicked this way comes...");};

}

};

document.body.appendChild(o);

</script>

</html>

Use of the DOM to dynamically load JavaScript provides a solution to our problem in the form of the onreadystatechange event. This event fires only when the script has loaded completely, at which point we can reference functions and objects provided by the included file with impunity.

Initial Module Inclusion

Despite the DOM example in the last section, the practice of including JavaScript from JavaScript gains us nothing when used where traditional HTML script tags are possible. If used appropriately, it enables us to manage our library entries and their dependencies intelligently, but it is still necessary to include the first module by hand.

This brings us full-circle to the first code snippet listed in this article:

As it turns out, there is considerable usefulness in including an initial module as we would include a traditional script file. It provides for us select core routines without having to wait for a load event, including implementation of principals discussed above which load modules programmatically. Additionally, it gives us a place to perform library initialization. This can include, among other things, an application-defined entry point where we can be certain all library modules are loaded and ready.

To demonstrate, below is a working example of an HTML page leveraging JACL's Plot module to draw a sine wave. For those that are curious, it can cut-and-pasted into an html file and viewed it in any browser.

<html>

<body>

jacl.use("jaclPlot");

jacl.appMain=function(){

jacl.plot.setOrigin(50,100);

jacl.log.info('Graphing sine wave...');

for(var t=0;t< 300;t++)

jacl.plot.point(t,Math.sin(t/30)*30);

};

</script>

</body>

</html>

Notice that our initial inclusion of the now familiar JACL Core module is done explicitly as an HTML tag. This ensures that the library's objects (in this case the jacl object) are present, as are library defined code. In the JACL framework, this includes the use method, which is simply a refined implementation of the DOM principals discussed in the previous section, and the appMain method which is similar in principal to the onreadystatechange event but fires only once when all modules have finally been loaded.

Avoiding Multiple Inclusions

Another complexity inherent in the practice of modules-including-modules occurs when two modules share the same dependency. If not handled, the same module can be included twice. The worst case scenario results in self-referencing recursion and a page that never finishes loading.

The simplest solution is to set a flag when a module is included for the first time, doing nothing on subsequent inclusions. By leveraging our object hierarchy, this is almost laughably easy as the individual objects created by a module act as flags simply by virtue of their existence:

if(jacl.plot==null) { //already created?

jacl.plot=new jacl_plot(); //no? then let's create an instance

// implementation goes here

}

The only drawback to this is that, while easy, the approach must be enforced across all library modules. A better alternative, one that can be implemented in the library object itself is to track which modules have been already been requested and don't add them via the DOM more than once.

Establishing a Library's Location

Astute observers will notice one important nuance in the sine wave example:

jacl.use("jaclPlot");

The use method does not require a fully qualified file path. At first glance this seems a trivial feature. After all, if we need to specify the URL when we include one module, it is only a small inconvenience to provide the URL with subsequent inclusions. The real problem arises, again, when modules include other modules. In the example where we included modules with the DOM, the path was hard-coded, as in:

o.src="http://www.codingmonk.com/jacl/jaclPlot.js";

This isn't going to do us any good if we try to access our library locally, or if we move it to a different domain. What we need is for the module to determine the library's location relative to the client. As it turns out, this isn't too difficult. Since we're including an initial core module with a fully qualified filename all we have to do search the document's script objects and parse the path from the correct one:

var path="";

for(t=0;t<document.scripts.length;t++){

var val=document.scripts[t].outerHTML.toLowerCase();

if(val.indexOf("jacl.js")==-1) continue;

var s=val.indexOf("src=\"");

if(s!=-1){

s+=5;

path=val.substring(s,val.indexOf("jacl",s));

break;

}

So the use method knows to expand:

jaclplot

into

http://www.codingmonk.com/jacl/jaclplot.js

by using the resulting path variable. Of course, storing the path as a global variable clutters the namespace. This is just one of several advantages of leveraging an object hierarchy for our JavaScript library…

Organizing a Hierarchy

The best, most useful of libraries can suffer and die because it is not kept organized. As libraries grow, they become more difficult to keep arranged. No matter how many modules your library is broken down into, if the net result is just a chaotic bundle of routines, then the library hasn't helped as much as it could.

Namespace hierarchies help us to stay organized. More than just factoring code into modules, this technique structures our code in precise and predictable ways. Notice from our examples how every use of the JACL library stems either directly or indirectly from the global jacl object. JACL's implementation of the previous path-finding example populates a member variable rather than a global one:

jacl.path

By doing this, we need not worry ourselves with the possibility of naming collisions, where another module or otherwise appropriated script defines a variable named "path" too.

Continuing the review of the fully working sine-wave example given previously, notice that JACL's logging module adds an object which encapsulates various pieces of logging functionality:

jacl.log.trivial("Here is a message");

Other JACL modules go to greater lengths to categorize their code:

jacl.input.textbox.applyEditMask(tbInput, "###-##-####");

How diverse you choose to make your hierarchy is, of course, a personal preference.

Review a real implementation

As was pointed out numerous times, the techniques proposed in this article are more than theoretical. For a complete working example, one moderately more fleshed out, I highly recommend taking a look at the most recent implementation of Coding Monk's JACL framework:

www.codingmonk.com/downloads/jacl.zip

Happy coding!

Configuring Subtext for Blogging with Word 2007

Jim Fisher — Mon, 18 Aug 2008 03:02:12 GMT

As part of my political agenda, in a recent post I walked through the steps of configuring Word 2007's blogging features to work with Subtext. At the end of that article, I promised to review the code changes required to make Subtext accept pictures from Word 2007. The fix I detail here consists of relatively minor code changes, limited to two c# files in the Subtext.Framework project:

MetaWeblog.cs
MetaWeblogAPI.cs

If you regularly compile the Subtext source code, you'll find making these changes a snap. If not, you might find it easier to skip the rest of this article, navigate to your site's bin directory, rename the Subtext.Framework.dll file and drop this one in its place.

Before moving forward, I should note that the changes described are against the Subtext 1.9.5b code base and future versions of the code base probably have this incompatibility addressed, so a bit of advice: make sure which version of Subtext you are using before you begin digging into the internals.

MetaWeblogAPI.cs

If you crack open the MetaWeblogAPI.cs file (under Subtext.Framework.XmlRpc) and search for the newMediaObject method, you'll find the following under the IMetaWeblog interface:

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]

mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject);

Note the blogid parameter is of type object, unlike every other method in the interface, which all support blogid parameters of type string. The easiest fix in this module is to change the parameter type to string, and I suspect that this alone might solve the issue, but a more thorough approach, one that leaves compatibility for other applications that may actually use the object-based blogid, is to add a more specific declaration or two. I chose this path of overkill, rather than that of minimalism by adding support for both string and int types; while not strictly necessary, it was quite easy to do. The full definition of the newMediaObject declaration appears below, with the additions surrounded with a dotted border:

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(string blogid, string username,
string password, mediaObject mediaobject);

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(int blogid, string username,
string password, mediaObject mediaobject);

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject);

These are, of course, only slight variations on the original declaration.

MetaWeblog.cs

Having declared the additional forms of newMediaObject that Subtext will support, we are half way complete. The final changes that are to be made are contained in the MetaWeblog class. Search for the implementation of newMediaObject and you'll find the original signature:

public mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject)

Note the blogid parameter with the type object. I found it best to not change the existing code. Instead, we need only to implement the two additions defined for the interface supporting the two alternate parameter types. Implementing pass-through methods for this is the least painful of approaches:

public mediaObjectInfo newMediaObject(int blogid,
    string username, string password,
    mediaObject mediaobject)
{
    return newMediaObject(blogid.ToString(), username,
        password, mediaobject);
}
public mediaObjectInfo newMediaObject(string blogid,
    string username, string password,
    mediaObject mediaobject)
{
    return newMediaObject((object)blogid, username,
        password, mediaobject);
}

And that's pretty much it for changes to Subtext. After we compile this and deploy the resulting modified Subtext.Framework assembly, Subtext should support images from Word 2007.

As Part of My Nonsense…

Jim Fisher — Sun, 17 Aug 2008 16:33:28 GMT

If you've been reading my blog for long, you may have noticed a common trend across some of my larger pieces: a bit of text expressing background to the article and indicating that it is part of a larger, personal effort:

"As part of my political agenda…"
"As part of my endeavors toward evangelizing the free world…"
"As part of my plan to stick it to the man…"

It doesn't take much review to realize that these are nonsensical statements, not to be taken literally, which serve as a form of unapparent signature when my articles are viewed individually, but which clearly mark my work when viewed as a whole.