Milan Adamovsky's Blog

Fastest Loop in JavaScript

2011-12-15T14:40:00.000-08:00

UPDATE: Turns out that the benchmark yielded skewed results. The quest goes on for the holy grail of fastest loops.

Leverage CSS when resizing HTML elements using JavaScript

2011-08-12T20:37:00.000-07:00

The inspiration for this article comes from me seeing, to this day, major frameworks like ExtJS using JavaScript as a shortcut to re-size HTML elements on a page - a task that CSS is much better suited for.

You may now be asking yourself: What exactly is the problem?

The problem is that when JavaScript is used to manipulate elements on the page, it will give a slower performance than if we leave it up to CSS. This means a deteriorated user experience.

Many web developers resort to JavaScript to allow a user to re-size a column, row, content area, or any other element on a page. This is usually done by assigning a calculated value to the width or height of the element via JavaScript. This works. It gets the job done. It's just not as responsive to the end user. Until now most developers have settled for this behavior under the premise there is no alternative. But there is. Read on.

A basic understanding of how a browser renders a page will help appreciate the solution to the problem, while at the same time gain a better understanding for what the problem is.

Web Page Load Sequence

This is an extremely high-level overview of the way a web page gets rendered on the screen:

DOM
CSS
JavaScript

The reason this is a high-level overview is because technically all of these steps happen sequentially in the order they appear on the page. This means that the DOM is being parsed by the browser, so it starts reading the HTML tag, then it hits the <head> tag where it then downloads the CSS, then JavaScript, then it executes the JavaScript as it continues loading the DOM, where it can again find more JavaScript before the DOM is fully loaded. Going into further detail is beyond the scope of this article.

Evidently the load order cannot be put into words as easily as we may want it to be, but one thing that is clear is that the CSS is applied faster than JavaScript - and this is key.

By simplifying the understanding of the load order to the aforementioned sequence it becomes easier to understand that we should try to leverage CSS wherever possible.

JavaScript Re-Sizing

A simple example of re-sizing would be a two column layout where we want the left column to be re-sizable.

Needless to say when we re-size Column 1 the second column's width must be adjusted accordingly. This is where the faux-pas occurs in today's web development: Both of the columns' widths are calculated and adjusted accordingly.

For simplicity's sake I'm keeping the example down to two columns, but in real life applications these will be all sorts of elements that will be re-sized depending on something else being dragged, re-sized, or slid.

Simply put, today, if we adjust A, we need to calculate its new width or height, and substract or add the difference between the old width/height and the new width/height accordingly to B, C, D, etc... on the page.

CSS Re-Sizing

Whenever I lead front-end development teams or conduct workshops there is a simple rule to developing websites that I promote: "Develop for fluidity or elasticity and then fix it (if necessary)."

In other words, I encourage my teams to develop markup in such a way that the layout is elastic (or fluid) so that if requirements ever change in regards to dimensions, the effort won't require any markup, CSS, or JavaScript adjustments. Another benefit is that developing for elasticity requires a higher order of discipline and knowledge, so it inherently enforces adherence to cross-browser compatibility development and web standards.

Once the web-page is set for elasticity (or fluidity), it can then be set to whatever fixed dimensions without compromising the page's integrity. This is not the case inversely. Another side-effect becomes that swapping elements in and out of the markup becomes more flexible, and most of the times the elements around the altered element will automagically fall into place - because we coded it to be fluid. As a result, this flexibility has prompted me to name this layout coding style a flexible layout.

I like disciplined development. This is the difference between coding and engineering a solution.

Engineering websites for elasticity requires the markup to be coded in such a way to maximize the use of CSS for all internal calculations and relying less on JavaScript where not necessary. This means we can completely by-pass the JavaScript engine for layout - as we should. CSS works so intimately with the browser, any changes to the styling of an element has a virtually immediate visual effect.

Normally however, elastic or fluid layout are usually reserved for the anticipation of a browser re-size (e.g. if we re-size the entire browser, we don't want the website to break.).

This is a great idea, but why limit ourselves to a browser re-size? We can apply this same concept to every element on the page; but how do we do that if CSS doesn't support JavaScript-like calculations? After all, we need to calculate the new width according to user's interaction.

Solution

The proposed solution does not rely purely on CSS as this would usually be impossible since the re-sizing of an element occurs upon a user's interaction. This means that we need to still rely on JavaScript for some of the calculations, but as I mentioned above we should try to limit this to a minimum. This is exactly what we will do.

The idea is very simple. We will calculate only one of the columns via JavaScript and let the other columns follow blindly via CSS. In other words: We will only explicitly calculate one value as opposed to however many values there are columns.

The way we accomplish the above is by letting the JavaScript give an explicit value of one of the re-sized elements. The other elements that are dependent on those dimensions to figure out how wide or tall it should be (such as a sibling column or row) will then simply have a respective width or height value of auto. This is where the magic happens.

Now because we leave the width or height value to auto we can now leverage the CSS engine to calculate the values for us - rather than have JavaScript do it.

This will give us something similar to this:

In the above example simply move the mouse on top of the drag bar (the dark gray bar), and you will notice your mouse pointer change to let the bar be dragged left or right. Doing so we can see how at any given time only one of the sides is being calculated by JavaScript while having the other side handled by the CSS engine.

For the sake of being able to show this example inline in this page I had to make some minor adjustments to the code, so follow the code examples rather than trying to view the source of the live example within this page.

We can then use this same principle recursively, and at any given time have JavaScript (the slower of the two) perform only one calculation while letting the CSS engine (the faster of the two) handle all others.

Had we not done this we would have to set the explicit value to the one element, and then set another explicit value on all elements that are dependent on this value. As you can imagine, this could easily turn to many many many calculations, with each slowing down the performance of the web application or website.

Step 1

The first thing we want to do is take care of our markup. As a good front-end developer we will usually work on our markup first, followed by the CSS, followed by JavaScript, and finally followed by fine-tuning where all three technologies will be juggled to get the desired result.

The markup is pretty straight forward.

The above example can be implemented with something simple as:

 <body id="index_container">

   <div id="menu_container">

     <div class="drag_content horizontally right">

     </div>

   </div>

   <div id="content_container">

   </div>

 </body>

The above example is simple enough to understand the needed moving parts to get the above implementation going. Below we will make a full fledged multi-frame layout to show how easy it is to extend the layout.

 <body id="index_container">

   <div id="menu_container">

     <div class="drag_content horizontally right">

     </div>

   </div>

   <div id="content_container">

     <div id="header_container">

       <div class="drag_content vertically down">

       </div>

     </div>

     <div id="main_content">

       <div id="sub_nav_container">

         <div class="drag_content vertically down">

         </div>

       </div>

       <div id="sub_main_content">

         <div id="body_content">

           <div id="navigation_content">

           </div>

           <p>

             Here goes some content

           </p>

         </div> 

       </div>       

     </div>

     <div id="footer_container">

       <div class="drag_content vertically up">

       </div>

     </div>

   </div>

   <div id="ad_container">

     <div class="drag_content horizontally left">

     </div>

   </div>

 </body>

Copy and paste this into an HTML file alongside the given CSS at the bottom of this article to see the output.

The naming convention is pretty self-explanatory of the roles of the various elements - with a few exceptions. Don't let this be confusing. Feel free to begin with the simple example and gradually move your way up.

You will notice a few elements that have the class drag_content. These elements are the "drag bars" that allow a user to hold and drag them to re-size the element. In other words this is a simulated control just like a button, drop-down, or scroll-bar would be.

We further enhance the drag bar by giving it some intelligence on what it is allow to do. The one piece of information we give it is the direction a user can re-size it. This is helpful to give the user a visual cue by changing the mouse pointer to the respective image so the user knows which way to drag. A class value of horizontally means the user can drag left to right, and a value of vertically will let the user know to drag top to bottom.

The last piece to the puzzle is to understand what the up, down, left, and right mean.

Each of these drag bars are actually inside the containers. This means that you have to decide in which container the drag bar will actually be. Once that is decided you have to decide on which of the walls the drag bar should be.

Step 2

Naturally the next step becomes the actual definition of the various classes and ids. This means CSS is our next technology of concern.

Take a minute to go through the CSS below.

*

 {

  margin: 0;

  padding: 0;

 }



body

 {

  background-color: #bcbcbc;

  height: 100%;

  width: 100%;

 }



p 

 {

  background-color: #fff;

  border: 1px solid #000;

  left: 10px;

  padding: 12px;

  position: absolute;

  right: 10px;

  top: 50px;

  width: auto;

 }

 

.down

 {

  bottom: 0;

 }



.drag_content

 {

  background-color: #5a5a5a;

 }



.horizontally:hover

 {

  cursor: e-resize;

 }



.horizontally

 {

  height: 100%;

  position: absolute;  

  top: 0;

  width: 5px;

 }



.left

 {

  left: 0;

 }



.right

 {

  right: 0;

 }



.up

 {

  top: 0;

 }

 

.vertically

 {

  position: absolute;  

  left: 0;

  height: 5px;

  width: 100%;

 }



.vertically:hover

 {

  cursor: s-resize;

 }



#ad_container

 {

  background-color: #a7a7a7;

  height: 100%;

  position: absolute;

  right: 0px; 

  width: 100px;

 }



#body_content

 {

  background-color: #fff;

  border: 1px solid #000;

  height: auto;

  position: absolute;

  left: 10px;

  right: 10px;

  top: 10px;

  bottom: 10px;

  width: auto;

 }



#content_container

 {

  background-color: #d6d6d6;

  height: 100%;

  left: 100px;

  position: absolute;

  right: 100px;

  width: auto;

 }



#footer_container

 {

  bottom: 0px;

  background-color: #bbb;

  height: 100px;

  position: absolute; 

  width: 100%;

 }



#header_container

 {

  top: 0px;

  background-color: #848484;

  height: 100px;

  position: absolute; 

  width: 100%;

 }



#main_content

 {

  background-color: #e0e0e0;

  width: 100%;

  top: 100px;

  position: absolute;

  bottom: 100px;

  height: auto;

 }



#menu_container

 {

  background-color: #a7a7a7;

  height: 100%;

  position: absolute; 

  width: 100px;

 }



#navigation_content

 {

  background-color: #fff;

  border: 1px solid #000;

  height: 20px;

  left: 10px;

  position: absolute;

  right: 10px;

  top: 10px;

  width: auto;

 }



#sub_main_content

 {

  background-color: #e0e0e0;

  width: 100%;

  top: 100px;

  position: absolute;

  bottom: 0px;

  height: auto;

 }



#sub_nav_container

 {

  top: 0px;

  background-color: #bbb;

  height: 100px;

  position: absolute; 

  width: 100%;

 }

The first thing that can be observed is the clean organization of the CSS. This is always good housekeeping that I cannot stress enough. In my workshops I always take a minute to remind developers to take time to follow the intuitive way of organizing that I describe in this post.

We are not going to explore why we use all of the various CSS properties as that is out of scope for this post.

The main point to understand on the CSS is that with respect to sizing, it defines the default - or starting dimensions - of the various containers. Remember: the goal of this type of coding is to minimize the use of JavaScript and maximize the use of CSS. In this case all definitions are handled by CSS, so no worries here - with one caveat: only size one side and leave the other side's dimension set to auto.

Let's break it down.

#content_container

 {

  background-color: #d6d6d6;

  height: 100%;

  left: 100px;

  position: absolute;

  right: 100px;

  width: auto;

 }



#menu_container

 {

  background-color: #a7a7a7;

  height: 100%;

  position: absolute; 

  width: 100px;

 }

The first thing to observe is the position. Notice that in this type of setup all of the containers need to be absolutely positioned. The reason for this is because we want them to conveniently cover all available space within their respective areas. If this doesn't make sense, don't worry about it, just know to position: absolute the containers that you are interested in be re-sizable.

The second thing to notice is that in our simple example above, our left container is the menu_container with a default width of 100px (which can be any value you desire) and our right container is the content_container that has a width set to auto.

Now this is the interesting part: We have one of the containers' width set to a numeric value and the other container's width set to auto.

The container that gets the numeric value is the container whose width will be changed via JavaScript upon a user's interaction (e.g. dragging). The JavaScript code responsible for this can be found below in Step 3.

Assuming a user drags the bar to the right 80 pixels; this would cause JavaScript to take the existing width (100px as defined by CSS above) and adds 80 pixels (had the user dragged it to the left, it would subtract 80 pixels). In this case it would result at a final width of 180px - and we only did this one addition, no subtraction (or vice-versa). Neat.

The next step is to take that number (180px) and apply it to the other container (whose width is set to auto) but not to the width but rather to its left in this case (but it could be right, top, bottom depending on the direction of the drag bar). The reason we need to do this is to allow the width: auto to know the area it needs to cover. Keep in mind that this is a calculation that is done by the CSS engine so it's okay.

You will notice that any container that has a width of auto has both a left and right value. This is necessary for width: auto to work as we would expect it to.

The final thing to notice from the more complex example is that these same principles apply respectively for any direction the containers can be re-sized to. This means we can apply everything we've learned up to this point and make the necessary adjustments for it to make relative sense.

At this point as a quick recap: Copy the markup and the CSS of the complex example above to see how it all falls together.

A great exercise is to try to add a new row or column that can be re-sized following the aforementioned principles.

Step 3

Here is an example of how the code could work using jQuery. Keep in mind that though I use jQuery in this example, but the logic would work the same with any library, framework, and/or core JavaScript.

$(document).ready(function() {



  var resizeModel = {};

  resizeModel = {

                 direction : {

                              axis : '',

                              name : '',

                              sizing : '',

                              padding : ''                              

                             },

                 elements : {

                             a : '',

                             b : ''

                            },

                 namespace : 'resizer',

                 initiatedBy : null,

                 mouseState : 'idle'

                };

 

  $(this).bind(['mouseup', resizeModel.namespace].join('.'), 

               function (eventObject) 

                {

                 resizeModel.mouseState = 'up';

                })

         .bind(['mousemove', resizeModel.namespace].join('.'), 

               function (eventObject)

                {

                 if (resizeModel.mouseState == 'down')

                  {

                   var viewportSize = $(window)[resizeModel.direction.sizing]();

                       clientAxis = resizeModel.direction.axis,

                       paddingCSS = {},

                       offSet = resizeModel.direction.offset,

                       elementSize = resizeModel.direction.name == 'left' || resizeModel.direction.name == 'up' 

                                      ? viewportSize - eventObject[clientAxis] + 2

                                      : eventObject[clientAxis] - offSet + 2;



                   paddingCSS[resizeModel.direction.padding] = [elementSize,'px'].join('');

                   resizeModel.elements.a[resizeModel.direction.sizing](elementSize);

                   resizeModel.elements.b.css(paddingCSS);

                  }

                })

         .delegate(".drag_content",

                   ['mousedown', resizeModel.namespace].join('.'),

                   function () 

                    {

                     resizeModel.initiatedBy = $(this);

                     

                     var resizeParent = resizeModel.initiatedBy.parent();

                     

                     resizeModel.elements = {

                                             a : resizeParent,

                                             b : resizeModel.initiatedBy.hasClass("right") || resizeModel.initiatedBy.hasClass("down") 

                                                  ? resizeParent.next()

                                                  : resizeParent.prev()

                                            };

                     resizeModel.direction = resizeModel.initiatedBy.hasClass("down")

                                              ? {

                                                 axis : 'clientY',

                                                 name : 'down',

                                                 offset : resizeModel.elements.a.offset().top,                                                 

                                                 sizing : 'height',

                                                 padding : 'top'

                                                }

                                              : resizeModel.initiatedBy.hasClass("left")

                                                 ? {

                                                    axis : 'clientX',

                                                    name : 'left',

                                                    offset : resizeModel.elements.a.offset().left,                                                    

                                                    sizing : 'width',

                                                    padding : 'right'

                                                   }

                                                 : resizeModel.initiatedBy.hasClass("right")

                                                    ? {

                                                       axis : 'clientX',

                                                       name : 'right',

                                                       offset : resizeModel.elements.a.offset().left,                                                       

                                                       sizing : 'width',

                                                       padding : 'left'

                                                      }

                                                    : resizeModel.initiatedBy.hasClass("up")

                                                       ? {

                                                          axis : 'clientY',

                                                          name : 'up',

                                                          offset : resizeModel.elements.a.offset().top,                                                          

                                                          sizing : 'height',

                                                          padding : 'bottom'

                                                         }

                                                       : 0;

                

                     resizeModel.mouseState = "down";

                    });

          

});

The one point worth mentioning is that all these events are bound to the document's events since the events we are interested in are global events. This is why you will see the events bound to $(this). The rest of the code is self-explanatory.

At this point simply combine the markup, CSS, and JavaScript to see it all come together. Don't forget to use FireBug or a comparable tool to observe everything in real-time we covered.

Internet Explorer 6's 1px Gap Bug Solution

2011-01-16T12:04:00.000-08:00

If you are still coding for Internet Explorer 6 ("IE6") cross-browser compatibility, you may have encountered the 1px gap bug. In brief, this bug adds a gap on absolutely positioned elements when the parent container's width is an odd number.

Problem

It took me a while before I had a real-life encounter with this bug. On the right is an illustration of what the bug looks like in IE6. If you want to see the HTML in IE6, visit this link by Paul O'Brien where he has a good write-up of the problem. Again, you will only see the problem when you visit the link using Internet Explorer 6.

In my case I wanted to create tabs that have a little 1x1 pixel div in the upper left and upper right corners of the tabs to give the illusion of a very subtle "rounded" corner. Obviously, this is a scenario where one pixel make and breaks the illusion. Consider the magnified illustration to the right as a depiction of the tab where the two squares are 1 pixel in height and 1 pixel in width.

The illustration to the left shows the intended illusion. The image is magnified 20x to give a clear visual of the effect. It becomes clear that we need the right div to be flush with the container to achieve the desired result, and that being one pixel off would ruin it.

As a reminder, this only happens in Internet Explorer 6 when the width of the container is an odd number (e.g. 155 pixels).

My initial code looked something similar to this:

<div id="tab_container">
   <ol>
     <li style="width: 155px">
       <div style="left: 0px; position: absolute; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
       <div style="right: 0px; position: absolute; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
       <a href="">
         Some random tab text
       </a>
    </ol>
 </div>

The idea was to have the two 1 pixel divs absolutely positioned in the upper corners without floating (though I did try with float: left and float: right just the same) - to no avail. The 1 pixel gap bug kicked in.

In the above I use inline styling for illustration purposes only. The width of 155 pixels is also hard-coded just for illustrative purposes - this width would usually be dynamically calculated via the CSS engine depending on the content of the tab. Furthermore, there are some CSS styling on the ol and li elements to get them to show as inline tabs. I do not include these style properties in this blog as not to clutter the topic at hand. You can find the complete code in the attached zip file (coming soon).

Solution

Upon scouring the Internet, you will quickly see that there is no practical solution. The solution presented by Paul O'Brien works well with defined widths, but if we have the luxury of hard-coding dimensions, we may as well just nudge the dimensions for IE6 in our stylesheet and keep our markup clean from clutter markup.

The goal of good web development is to keep your markup as lean as possible, meaning keeping various helper wrappers to a minimum. Keep this in mind.

Having said that, what do we do in fluid layouts where widths can change dynamically? Simple. We stop and think.

Thought Process

To many programmers CSS is a step away from black magic. We tend to want to solve problems programmatically and when that fails we just keep throwing more and more patchwork to the mess until something sticks. Some will actually stop and think, and solve the logical problem almost to the effect of a riddle (as opposed to attempt to calculate a solution to a math-like problem). In other words, CSS is not black magic - we can still apply logic to solving the problem rather than just pure trial and error (or just giving up and resorting to JavaScript as a last resort.)

So let's break down the issue.

We know the problem only happens in Internet Explorer 6.
We know the problem only happens when the width of the container is an odd number.
We know the problem only happens on elements within the container that have an absolute position.
We know of the solution presented by Paul O'Brien where we statically position the element within a container of a fixed width.
We know there is no known solution to the problem.

What was the last point on the list?! No solution!? Yes, it's true. There is no known solution that tackles the problem perfectly - but here I will present how I overcame the problem.

Let's break down what we are going to try to achieve for a solution.

The one technical cause to the effect we know that we cannot rely on is position: absolute. This CSS attribute is off the table.
We want to be able to keep our elements flush with the container even in a dynamically changing width of the container. In other words, fixed values are off the table.
Do not use JavaScript for a CSS problem!! JavaScript is off the table.

We have pretty much cornered ourselves into a seemingly impossible dilemma: solve a seemingly unsolvable problem. So as I said, our solution may or may not be perfect for every situation, but it may lend itself to many scenarios similar to mine. So this is where we stop and think.

What we have to do is see what other alternatives we have to absolute positioning, and that would be static and relative positioning. We know that the solution by Paul O'Brien relies on the static positioning - and we also know that for it to work we need to specify a fixed width container, so it will not lend itself to our fluid layout requirements. This leaves us with getting creative with seeing how we can use the last option: relative positioning.

We know that when we float divs in any browser, including IE6, they can grow the container relatively well - without rendering the 1 pixel gap. This means all we have to do is just split the divs in two logical areas:

Fixed width content - content whose width will never change
Dynamic width content - content whose width may change based on content

The rectangles in the image illustrate a mental picture of how we cut up the content of the elements. These areas in turn simply need to be floated left, and they will then fill out the container to the respective width - perfectly.

The new code will then simply look something like this:

<div id="tab_container">
   <ol>
     <li>
       <div style="float: left; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
       <div style="float: left">
         <a href="">
           Some random tab text
         </a>
       </div>
       <div style="float: left; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
    </ol>
 </div>

There is one small problem remaining though: If we float the elements, they will simply be rendered side by side, as shown on the image to the right - but we want the content to take up the full width of the container, as we would if the corner divs were absolutely positioned.

This is where the beauty of negative margins come in.

Normally if we deal with scenarios as mine, where we only deal with one pixel widths, we can get away with having the divs floated side-by-side. This is because we may actually want some padding around the content to separate it from the edges of the container. If this is not the case, we can simply compensate for the fixed content widths with negative margins.

<div id="tab_container">
   <ol>
     <li>
       <div style="float: left; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
       <div style="float: left: margin-left: -1px; margin-right: -1px">
         <a href="">
           Some random tab text
         </a>
       </div>
       <div style="float: left; height: 1px; width: 1px">
         <!-- comment needed for 1x1px div in ie6 -->
       </div>
    </ol>
 </div>

Notice in the above code that all we do is just tack on a negative margin that equals the width of the fixed content. This means that in my case since the corner divs are 1 pixel wide, my dynamic content div's margin will take a negative 1 pixel width on the left and right. This will yield the result as shown to the left.

We have effectively mimicked the effect of position: absolute by using position: relative. Furthermore we have a relatively unobtrusive cross-browser solution where we do not need to have extra markup, and most importantly this solution works as well in a fixed width as it does in a fluid width!

I hope you enjoy it, and feel free to leave your questions in the comments section below.

You can see a demo page by clicking here. You can download a copy of the demo page by clicking here.

jQuery Plugin Pattern 2.1

2010-11-16T07:06:00.000-08:00

After having release the jQuery Plugin Pattern 2.0 I encountered a few situations where the pattern would cause for my plugins to crash and burn - not a good thing to happen with a pattern you are trying to advocate. These were mere failures of that version that paved the way for the improved pattern. Behold version 2.1!

Goals

This pattern tackles a few wish-list items of mine that I could not find an easy solution to using the official jQuery plugin pattern. In this post I'm going to list all the goals I'm trying to achieve with this pattern so you can decide if this pattern is for you.

Backward compatible with jQuery standard plugin authoring method
1. Syntax would be $(selector).plugin(args)
2. Make plugin chainable
3. Allow this to refer to the selected element
4. Allow methods to be called the jQuery way (as parameters to the plugin)
Allow Object Oriented Programming inside plugin
Allow to expose the OOP object instead of the jQuery object
1. Allow classical OOP concepts such as inheritance
Allow n-depth levels of methods a la OOP
Allow plugin to act as a namespace
1. Syntax would be $(selector).plugin.method()
2. Make namespace easily changeable in the event of a naming conflict
Allow plugin to be called as a hybrid of standard jQuery mixed with OOP
1. Syntax would be $(selector).plugin(args).method()
Make version a publicly exposed attribute as a standard
Allow for an easy way to expose public interface
Allow for a plugin initializer
Encourage use of closure based getters and setters
Promote a standardized persistent config accessor

If you have experience writing plugins you will quickly observe some of the above items would be difficult to achieve using the official pattern. I am not saying mine is better or worse, but my goal is to marry Object Oriented Programming with jQuery. That's right: I want to be able the pattern to be a mere wrapper around my Object Oriented code to allow it to be connected to other plugins and to be able to internally take advantage of jQuery's magic - such as its selectors.

Barebone Pattern

Below is a barebone version of the pattern that would usually be copy/pasted into your plugins and then filled in with your own code between the [BEGIN YOUR CODE] and [END YOUR CODE]. Take a time to study the code below and then we will examine a real-life example.

/* jQuery Plugin Pattern 2.1
 * Author: Milan Adamovsky
 *
 * This pattern allows you to write jQuery plugins a lot faster, more consistently,
 * and less error prone.  Furthermore it allows namespacing, OOP integration, along
 * with other technical benefits.  
 *
 * There are two "global" (but local) helper methods available throughout each plugin
 * and they are:
 *
 *   getPluginClass() 
 *   getPluginName()
 *
 * The getPluginClass() returns the definition of the entire plugin code.  Usually 
 * this is not needed by the plugin author (you), but in the rare event you would
 * need it, here it is.  It is used internally by the plugin pattern.
 *
 * The getPluginName() returns the name of the plugin's jQuery namespace as defined
 * by the initPlugin() method (which is something you, the author, defines).
 *
 * Attention to JSLint users: this code will not pass due to some advanced paradigms
 * in use, though efforts have been taken to minimize these.  Priority was given to
 * functionality and syntax correctness so that YUI Compressor can properly minify
 * the code.
 */ 

(function($)
  {
   initPlugin({
               name : 'asyncLoader'  // plugin name 
              });
   
   //----plugin class -- BEGIN--------
   function getPluginClass()
    {
     return function (args)
      {
       // Version - directly exposed to be access via $(...).plugin.version
       this.version = '1.0';
      
       // Public Methods - wrappers containing a reference to the actual function 
       this.someMethodA = someMethodA;   // non-chainable method
       this.someMethodB = _(someMethodB);    // chainable method
       
       this.rc = jQuerify;       // required plugin pattern code

       // getConfig - always used to contain class/plugin arguments
       function getConfig()
        {
         return undefined;       // we define this via setConfig()
        }
  
       // setConfig - always used to set class/plugin arguments, usually used indirectly via initConfig
       function setConfig(args)
        {
         getConfig = function()
                      {
                       return (args);
                      };
        }      
  
       // initConfig - sets default values via jQuery's extend()
       function initConfig(args)
        { 
         setConfig($.extend({
                             chainable : true,     // false - this allows us to do something like $(...).plugin(args).method()
                                                   //         this returns the object as the output
                                                   // true  - otherwise, by default, it will assume jQuery native functionality of chainability
                                                   //         this returns what jQuery expects for chaining
                             properties : {}       // any properties that you want to be passed to the plugin.
                            }, args));
         return (this);
        }
  
       //---[BEGIN YOUR CODE below]-------
       //   [Class methods / properties]

       function someMethodA(args)
        {
         alert('This is our non-chainable method!');

         return (this);    // we return this to allow classic OOP
        }
        
       function someMethodB(args)
        {
         alert('This is our chainable method!');

         // we don't have to return anything since the _() takes
         // care of chainability. 
        }
     
                
       // initConfig - gets called to set defaults for plugin
       initConfig(args);   // Pattern code - usually just copy/paste
       
       // we put our logic after the method definitions to keep JSLint a
       // little happier.
        
       //---[END YOUR CODE above]----

       function _ (fn)      // local function that facilitates chainability
        {
         return function (args)
                 {
                  return this.prototype.rc(function () 
                                            { 
                                             fn.call(this, args); 
                                            }); 
                 };
        }
        
       function jQuerify(args)  
        {
         if (typeof args == 'function')
          {
           return $.fn.curReturn.each(args);  // handles chaining of method
          }
         else
          {
           initConfig(args);
           
           return getConfig().chainable       // checks for chaining in main plugin
                   ? $.fn.curReturn           // returns chainability hook
                   : $.fn[getPluginName()];   // returns OOP object hook
                                              // getPluginName() is defined in initPlugin()
          }
        };
      };
    }

   if ($.fn.curReturn === undefined)          // checks if a plugin has already loaded environment
    {
     $.fn.extend({                            // if not then it extends jQuery object.
                  curReturn: null,            // declares placeholder
                  jQueryInit: jQuery.fn.init  // saves original jQuery init method
                 });
      
     $.fn.extend({                            // now we overwrite jQuery's internal init() so we
                                              // can intercept the selector and context.
                  init: function( selector, context ) 
                         {
                          return jQuery.fn.curReturn = new jQuery.fn.jQueryInit(selector, context);
                         }
                 });
    }
        
   function initPlugin(args)
    {  
     getPluginName = function()
                       {
                        return args.name;    // sets getPluginName() to return jQuery plugin name
                       };
                       
//     console && console.log(["Initialize", args.name, "plugin."].join(' '));                    

     try                                       // meat 
      {
       var classCode = getPluginClass(),       // get a reference to the plugin OOP code
       _p = new classCode({});                 // instantiate plugin Class (which is OOP)
       $.fn[getPluginName()] = _p.rc;          // insert instantiated plugin into jQuery namespace
       $.extend($.fn[getPluginName()].prototype,_p);  // augment jQuery internals
       $.extend($.fn[getPluginName()],_p);            // same here.
      }
     catch (error)
      {
       alert(error);                           // in case something breaks let us know.
      }

    }
   
  })(jQuery);

Pros & Cons of JSLint

2010-11-13T18:20:00.000-08:00

Douglas Crockford is unquestionably a well respected figure in the JavaScript world, with many contributions for all of us to use, re-use and build on. JSLint is one such contribution and this article will explore it very briefly.

JSLint

As a JavaScript developer striving for quality code you may already have run your code through JSLint. This nifty tool is what is called a static code analysis tool which basically means that it does not execute the code but rather analyzes it without actually running it for any potential problems. This is good and bad.

To put it in plain English, JSLint is not a pre-compiler. It will not try to run the code to see if there are any syntax errors that will prevent the code from running. As a matter of fact, syntactically the code may be flawless, but what JSLint does is points out areas of the code that may lead to unpredictable or unintended results.

A simple example would be writing code that inadvertently creates an infinite loop. Syntactically this is bug-free code, but an analysis could identify this potential problem as something you did not intend to do.

This tool, meant to help at identifying potential issues with the code, has made it into build systems where a build will break in the event of an unsuccessful JSLint pass. In other words, if JSLint isn't happy with the front-end code, it will prevent back-end code from building. You may agree this is somewhat extreme to have an entire build be dependent on JSLint - but alas, this is what is happening out there, and I will show how this is a horrible idea.

Pros

The benefits of incorporating JSLint into the arsenal of tools for a front-end developer are numerous. It effectively identifies various areas of potential problems and brings them to light in need of attention. This could be anything from a missing semi-colon, to a duplicate variable definition, highlights reserved keywords that may be used, and other common coding mishaps.

The tool comes with various switches that allows for fine-tuning to achieve a tailored level of restriction.

Another indirect non-technical benefit is that we can use Douglas Crockford's extensive experience to find issues with our code that our lesser trained eye could not detect as easily, if at all. On the flip-side, this can also work to our detriment.

Cons

As stated above JSLint is sometimes part of a build system that causes a build to fail based on a failed JSLint pass. It is almost too easy to sell this idea to management for the following reasons:

Douglas Crockford
1. The Good Parts
2. JSON
Code Quality
and the list goes on...

Essentially what it boils down to is follow the leader. History has shown us a few times what happens when we follow the leader without putting some thought into it, and this is exactly what I am trying to encourage for you to do.

Needless to say, this is not what the tool is meant for as a static code analysis tool. It's like using Windows' Notepad to write Visual Basic applications - it's possible, but not what it's intended for. It's the wrong tool for the wrong job.

To me this tool is a great utility to help identify potential issues to give the web developer another pair of eyes, but ultimately it rests on the developer's competency and expertise to make the call of whether or not to follow JSLint's suggestions. Keep in mind JSLint takes a somewhat heuristic approach to the analysis, so it will not always guess your intentions correctly.

So let's just run down a few issues with this tool that I've encountered and why I would not make the recommendation to use this as anything more than a suggestive tool in your arsenal - but definitely not as a pre-requisite to a successful build.

Problem at line xx character xx: 'xxxxx' is a function.
This happens commonly in closures where a function wants to overwrite itself. This is not an error but JSLint would break a build - even with quite lenient switches turned on.
Problem at line xx character xx: 'xxxxx' was used before it was defined.
This happens when you try to call a function before you defined it. In other words JSLint expects your main code after all function definitions. This is not always preferred since it requires for you to always scroll down past all your functions risking tripping something along the way - not to mention slow down your productivity. This is debatable of course.
Problem at line xx character xx: Expected an identifier and instead saw 'package' (a reserved word).
JavaScript has many reserved words and amongst them is the word package. So while you should refrain from using reserved words, this error even pops up in a hash key being a reserved word.
```
 var myPackage = args.package;
```
It is clear to us that this can never be in conflict with the reserved keyword since it will never occupy the same namespace.
Problem at line xx character xx: 'xxxxx' used out of scope.
This is an example where JSLint fails to identify proper scoping of a variable. If you declare a variable inside an if statement, followed by a condition that checks against that variable, this error emerges.
```
if (1)
 {
  var x = 1;
 }
if (x)
 {
  ...
 }
```
As we can see the variable is not scoped (since if statements don't scope a variable in JavaScript), so the above code should not throw an error.

I could continue the list but the point is not to break apart JSLint but merely to show that there are some common practices that could incomprehensibly break a build, and why it should not be relied upon as a one size fits all solution.

Finally The Big Bang

I want to make sure it is understood that I don't discredit the utility of JSLint, but to the contrary: we have to credit the tool for what it is and not go crazy using it for something that it is not. I think Douglas Crockford would himself be astounded of how much faith some companies or individuals put into this tool.

If you are still a proponent of using JSLint for all your code quality needs, run the source code of JSLint through JSLint itself to see for yourself that it itself does not pass JSLint. Here is the code (minified), jQuery uncompressed, YUI uncompressed, and feel free to continue checking other well respected source codes to see how big of a chunk of the Internet would go dark if their builds relied on JSLint. Enjoy.

Points of Argument

Here are a few issues brought up by readers of this post that I feel are good to add as part of the post for you to be able to make a more sound decision on how you will choose to use JSLint in your workflow.

JSLint isn't intended for minified code

Minifying code yields valid JavaScript just as same as an experienced JavaScript developer might. In other words, a minifier may do things that an experienced JavaScript developer might intentionally do as well, that JSLint would flag as an error - as it does with minified (and possibly optimized) code.

Closure based Getters & Setters in jQuery

2010-11-12T06:48:00.000-08:00

Recently I wrote an article about how to effectively privatize your getters and setters by using closures. In this article I want to quickly show how you can use this in a practical sense when you develop in jQuery.

Problem

One of the most common pitfalls of a jQuery developer in my experience has been the lack of focusing on performance. The focus has generally been on task completion. This means the job will get done, but it won't be done with performance efficiency in mind.

One of the most abused features of jQuery in this domain, is coincidentally the most used feature of jQuery: selectors (e.g. $(element)). Let's take a look at a silly example.

$(function() 
   {
    for (var x = 10; x > 0; x--)
     {
      x % 2 
       ? $('#someDivId').hide() 
       : $('div#someDivId').show();
     }
   });

In the above example we can see that we select the same div (assuming we follow the W3C standard of assigning unique ids).

We are somewhat inefficient in that we use the jQuery selector each time to access the same element, forcing jQuery to crawl through the DOM each time. This is inefficient, and a solution is available.

Best Practices

Before I dive into how a closure based solution could help, I will illustrate the commonly used solution as a best practice.

$(function() 
   {
    var divSelector = $('#someDivId');
    for (var x = 10; x > 0; x--)
     {
      x % 2 
       ? divSelector.hide() 
       : divSelector.show();
     }
   });

What is happening here is that we capture the element in a variable that we then re-use. This way we tap into jQuery's magic only once to find the element and leverage that spent effort in all subsequent references to that same element.

This is going in the right direction since our goal is to try to be as efficient as possible. However there is a drawback to the above good practice. Can you guess?

Let's take the next example.

$(function() 
   {
    var divSelector = $('#someDivId');

    aFunction(divSelector);
    bFunction(divSelector);

    function aFunction(args)
     {
      for (var x = 10; x > 0; x--)
       {
        x % 2 
         ? args.hide() 
         : args.show();
       }
     }

    function bFunction(args)
     {
      for (var x = 20; x > 0; x--)
       {
        x % 3 
         ? args.hide() 
         : args.show();
       }
     }

   });

The above example is extremely silly in its functionality, but we merely want to illustrate a concept.

What do we see happening above? The good practice of capturing the element in a variable and re-using the variable. This is great but it pollutes the lexically scoped global namespace. This means we have divSelector available to aFunction and bFunction globally if we wanted to completely ignore the passed in argument to each function respectively. In other words, we could directly access divSelector from within either of these functions instead of reading args. What is the problem you might ask?

There are a few. One of them is a polluted namespace, but the second one is that of guaranteeing data integrity. Since it is in the scoped global namespace any function can directly access it and modify it - circumventing any error handling logic that may have been defined either in a getter or setter.

Solution

This is where we use a closure based getter and setter as described in my earlier blog post.

$(function() 
   {
    function getDiv()
     {
      var divSelector = $('#someDivId');

      getDiv = function()
                {
                 return (divSelector);
                };

      return getDiv();
     }

    function setDiv(args)
     {
      getDiv = function()
                {
                 return (args);
                };
     }

    aFunction();
    bFunction();

    function aFunction()
     {
      var args = getDiv();

      for (var x = 10; x > 0; x--)
       {
        x % 2 
         ? args.hide() 
         : args.show();
       }
     }

    function bFunction()
     {
      var args = getDiv();

      for (var x = 20; x > 0; x--)
       {
        x % 3 
         ? args.hide() 
         : args.show();
       }
     }

   });

I haven't followed the good practice of alphabetizing my functions to make it clearer. I've kept the getter and setter at the top so you can clearly see the new code. Take a minute to understand it.

Good. What is happening here is that the getter assumes the default value of the intended div. The getter captures it on first iteration, then the getter overwrites itself by re-defining its own code (yes, it's able to do it), self-executes its new self, and returns the new function definition that then gets executed by the caller's parenthesis. This is a closure based getter.

The benefit of using this solution is that you don't pollute the scoped global namespace, you ensure data integrity, you properly encapsulate the information to ensure security, and it is available just the same as a global variable would be - except with all these great extra benefits.

The one drawback is the code gets a little bigger, but that is the cost of having more reliable code. Once we minify the code, it will be virtually indifferent.

Finally I will leave you with a clean version of the code as I would implement it.

$(function() 
   {
    aFunction();
    bFunction();

    function aFunction()
     {
      var div = getDiv();

      for (var x = 10; x > 0; x--)
       {
        x % 2 
         ? div.hide() 
         : div.show();
       }
     }

    function bFunction()
     {
      var div = getDiv();

      for (var x = 20; x > 0; x--)
       {
        x % 3 
         ? div.hide() 
         : div.show();
       }
     }

    function getDiv()
     {
      var div = $('#someDivId');

      getDiv = function()
                {
                 return (div);
                };

      return get();
     }

    function setDiv(args)
     {
      getDiv = function()
                {
                 return (args);
                };
     }
   });

Pitfall

There is one pitfall when using this with jQuery: The selected jQuery object gets frozen in time.

This means that if you use the above, you will be able to edit the contents just fine of the selected jQuery object, but it may not necessarily reflect in the browser.

Let's look at an example.

$(function() 
   {
    function getDiv()
     {
      var divSelector = $('#someDivId');
      divSelector.html('Hi');

      getDiv = function()
                {
                 return (divSelector);
                };

      return getDiv();
     }

    function setDiv(args)
     {
      getDiv = function()
                {
                 return (args);
                };
     }

    aFunction();
    bFunction();

    function aFunction()
     {
      var args = getDiv();

      args.html('Hello');
     }

    function bFunction()
     {
      var args = getDiv();

      alert(args.html());  // this will say 'Hello' but the element on the page
                           // will still say 'Hi'.
     }

   });

Closures with Getters and Setters in JavaScript

2010-10-28T18:40:00.000-07:00

Whenever we are working on Object Oriented code the best practice is to have getters (also known as accessors) and setters. The benefits of these are beyond the scope of this blog post, but if you aren't using them yet do yourself a favor and read up on them and use them.

JavaScript is a forgiving language that allows us to get away with bad practices. Unfortunately, even with best intentions we may not always be aware of the hidden pitfalls we develop as we go. One of them is the cluttering of the namespace.

Problem

In this example we will assume that we are a relatively well versed JavaScript developer and we want to use private getters and setters within our class. Let's take a look at a simple class.

function StudentClass(args)
  {
   this.greet = greet;

   var _data = {
                firstName : '',
               };
   
   function getFirstName()
    {
     return _data.firstName;
    }

   function greet()
    {
     alert(getFirstName());
    }

   function setFirstName(args)
    {
     _data.firstName = args;
    }

   setFirstName(args && args.name ? args.name : '');

  }

  var student = new StudentClass({ name : "Milan Adamovsky" });
  student.greet();

Best Practices

Above we observe a few good conventions and practices:

Proper Class naming convention (PascalCase as per Java de facto convention)
Constructor
Private Getter
Private Setter
Exposed public interface (this.greet)
Alphabetized functions
Used underscored variable to imply private variable

Can we see an issue with the above implementation? We sure can: The namespace is cluttered with a private variable that can be accessed directly if we choose to bypass the getter and setter. Urgh!

Solution

Is there a way we can keep our private variables truly private? Yes there is. I challenge you to think a little bit about it. You have a hint: the title of this blog post :)

Okay, challenge is over, now this is where the fun truly begins. Let's rewrite the above code excerpt with a truly private variable that cannot be accessed directly any other way than the getter.

function StudentClass(args)
  {
   this.greet = greet;

   function getFirstName()
    {
     return undefined;
    }

   function greet()
    {
     alert(getFirstName());
    }

   function setFirstName(args)
    {
     getFirstName = function ()
                     {
                      return (args);
                     };
    }

   setFirstName(args && args.name ? args.name : '');

  }

  var student = new StudentClass({ name : "Milan Adamovsky" });
  student.greet();

This is some cool stuff! We can immediately notice that there is not one single variable in the encapsulated global namespace of the Class (e.g. _data in the first example).

Break Down

Closures are a powerful concept, but most developers can't find an obvious use for them. Next time you go to an interview, tell them it's perfect for private getters and setters ;) In case someone like me interviews you and wants an explanation, here it is.

Step 1

The first thing we do is create the getter and setter. We need both as not to throw any errors (there are ways around this, but let's keep it simple). This is why we have this :

function getFirstName()
    {
     return undefined;
    }

We want getFirstName to be in the namespace of the Class but we don't want it to actually return anything. It's essentially just a memory place holder for the real getter to come.

Let me repeat this: The declared getter returns nothing because we will overwrite the getter with the actual value through a closure. We actually need to do it this way so that we can get away with not having to have a global variable (e.g. _data).

Step 2

This leads us into the setter that happens to be the closure for the getter.

function setFirstName(args)
    {
     getFirstName = function ()
                     {
                      return (args);
                     };
    }

Take a minute to look at this and it will make sense.

Essentially what is happening is when we set the value we overwrite the respective getter with a new function that returns the passed in parameter to the setter. In our example, that would be the args variable.

The args variable, you will notice, is passed in via setFirstName(args) and captured in the anonymous function that is then assigned to the variable getFirstName which occupies the same namespace as the getFirstName function. Voilà! There is no way to access args unless you use the getter.

Berkeley DB not found on Fedora 8

2010-10-03T09:00:00.000-07:00

My preferred Operating System to work on is FreeBSD, but recently I was working on a project on a Fedora AMI on the Amazon EC2 platform. There are a few differences between the two systems and I have to develop a cross-platform script.

The binary I was trying to compile was the Apache Portable Runtime utility called apr-util which is needed to compile the Apache web server. As you may already know, one of the prerequisites is Berkeley DB.

Compilation

Whenever developing cross-platforms scripts or applications it is important to rely on tarballs as opposed to native OS package systems such as FreeBSD's ports, Linux' rpm or yum. The main reason for this is that doing manual compilations gives you granular control over the dependencies, patches, and compilation options that may and may not be better suited for cross-platform operations. That is assuming that the goal is to have an identical binary cross-platform.

To compile apr-util we use the following sequential commands:

./configure  --with-apr=/usr/local/apr/bin/apr-1-config --with-berkeley-db=/usr/local/BerkeleyDB.4.8
make
make install

The pre-requisite is that apr and Berkeley have already been installed on the system. In the example above we use Berkeley 4.8 but feel free to use the latest version.

Problem

The problem that we encounter when we compile apr-util manually is the following:

checking for Berkeley DB... not found configure: error: Berkeley DB not found.

This error message indicates that the linker was unable to find Berkeley DB libraries to compile against. This gives us enough information to immediately figure out that the problem lies with a tool called ldconfig.

Solution

The solution involves calibrating the linker to be aware of where the Berkeley DB libraries can be found, and this is exactly what we will do.

It may at first seem that we should focus on fixing something in the files of apr-util but the real solution lies with Berkeley DB.

When Berkeley DB is compiled we simply need to expose the various paths to the linker.

echo /usr/local/BerkeleyDB.4.8/lib > /etc/ld.so.conf
ldconfig
export CPPFLAGS="-I/usr/local/BerkeleyDB.4.8/include"
export LD_LIBRARY_PATH="/usr/local/BerkeleyDB.4.8/lib/"
export LDFLAGS="-L/usr/local/BerkeleyDB.4.8/lib"

I normally extrapolate the path into a variable such as $BERKELEY_PREFIX but for sake of clarity I've avoided that in the examples. Feel free to do so however since it makes your code more manageable and flexible. Doing so the code would look like this:

export BERKELEY_PREFIX=/usr/local/BerkeleyDB.4.8
echo $BERKELEY_PREFIX/lib >> /etc/ld.so.conf
ldconfig
export CPPFLAGS="-I$BERKELEY_PREFIX/include"
export LD_LIBRARY_PATH="$BERKELEY_PREFIX/lib/"
export LDFLAGS="-L$BERKELEY_PREFIX/lib"

Just a little bonus.

Continuing with our solution, what we accomplish with the above is adding the path of where Berkeley DB libraries can be found to the linker configuration file (ld.so.conf). Be very careful to append the path to the ld.so.conf as not to overwrite any existing contents of the file. This is simply done by ensuring you use '>>' as opposed to '>' as shown above. Consider this a word of caution.

Once the path is in your ld.so.conf you will simply need to run the linker ldconfig to make it aware of the changes. This will suck in all libraries. We can then verify that they have taken effect by listing all the libraries that ldconfig is aware of.

[root@server ~]# ldconfig -p | grep libdb
libdbus-1.so.3 (libc6,x86-64) => /lib64/libdbus-1.so.3
libdbus-1.so.3 (libc6) => /lib/libdbus-1.so.3
libdbus-glib-1.so.2 (libc6,x86-64) => /usr/lib64/libdbus-glib-1.so.2
libdbus-glib-1.so.2 (libc6) => /usr/lib/libdbus-glib-1.so.2
libdb-4.8.so (libc6,x86-64) => /usr/local/BerkeleyDB.4.8/lib/libdb-4.8.so
libdb-4.6.so (libc6,x86-64) => /lib64/libdb-4.6.so
libdb-4.6.so (libc6,x86-64) => /usr/lib64/libdb-4.6.so
libdb-4.6.so (libc6) => /lib/libdb-4.6.so
libdb-4.6.so (libc6) => /usr/lib/libdb-4.6.so

We can see from the above output that we have two Berkeley DBs installed on the system. One of them is version 4.6 and one of them is our new version 4.8. If you choose to install any other version your output would reflect an entry with the selected version respectively.

FreeBSD listing

In FreeBSD the ldconfig switch to see the listing above is -r instead of -p. You would thus run the command below:

[root@server ~]# ldconfig -r | grep Berkeley

Though in FreeBSD the libraries may not even be listed at all if we simply add the path of Berkeley DB to the search path as such:

ldconfig -m /usr/local/BerkeleyDB.4.8/lib

However as long as it is in the search path the linker will find the libraries at compilation.

Automation

At this point you should already have fixed the problem. You do not need to do anything anymore. The information below is just a little extra.

You can take it a step further by doing a conditional check ensuring you do not clutter your /etc/ld.so.conf file by not appending the path if it already exists.

export BERKELEY_PREFIX=/usr/local/BerkeleyDB.4.8
if [[ "$(grep $BERKELEY_PREFIX/lib /etc/ld.so.conf)" =~ 'lib' ]]; then
  echo $BERKELEY_PREFIX/lib >> /etc/ld.so.conf
  ldconfig
fi
export CPPFLAGS="-I$BERKELEY_PREFIX/include"
export LD_LIBRARY_PATH="$BERKELEY_PREFIX/lib/"
export LDFLAGS="-L$BERKELEY_PREFIX/lib"

The above would usually be put in an automation bash script.

jQuery Plugin Pattern 2.0

2010-09-25T11:05:00.001-07:00

After having developed the original jQuery authoring pattern a few issues caught my attention that kept me unhappy with that pattern. Luckily I had found workarounds for the few shortcomings I identified, but having to keep these in mind during development was a pain and did not provide for as a robust solution as I'd like it to be.

Time to review the pattern and start from scratch. You will see that this is a more elegant solution with all kinks ironed out.

Criteria

I still want to have a pattern that allows me to write plugins that meet these criteria:

that maintain only one entry in jQuery's namespace
that allow secondary methods
access to selector
access to $(this) through secondary methods

The good thing is that because this pattern uses jQuery's conventions, you do not have to learn anything new - no new framework, no new names, no new trickery, just simple straight forward jQuery programming mixed with Object Oriented JavaScript programming.

Research

I do encourage everyone to read the official jQuery plug-in authoring tutorial. This is pretty simple and straight forward, and in this article I will refer to it as the "normal method".

Another great read is Mike Alsup's plugin development pattern. His tutorial is closer to what my pattern tackles.

Goal

As with my original pattern, in this new pattern I also want to be able to have global access to the selector along with the $(this) object regardless of how many levels deep I am in my methods (e.g. $(selector).x.y.z()). This is something that jQuery does not natively support, and is limited to making the selector and $(this) available only to the main plug-in (first level as in $(selector).x()).

Solution

First I want to begin with giving a complete example of how a very basic plugin is developed using my proposed pattern so you know what you'll be dealing with.

Behold... the new plugin pattern!

(function($)
  {
   $.fn.extend({ 
                _plugin: null, 
                jQueryInit: jQuery.fn.init 
               });
    
   $.fn.extend({
                init: function( selector, context ) 
                       {
                        return jQuery.fn._plugin = new jQuery.fn.jQueryInit(selector, context);
                       }
               });
    
   function MyPluginClass(args)
    {
     
     var _config;
     
     this.version = '1.0';
    
     this.show = _(showMessage);
     
     initConfig(args);

     function getConfig()
      {
       return _config;
      }

     function setConfig(args)
      {
       _config = args;
      }

     function initConfig(args)
      { 
       setConfig($.extend({
                           chainable : true,
                           className : 'MyPluginClass'
                          }, args));
       return (this);
      }

     function showMessage(args)
      {  
       var myDiv = $(this);
           
       var config = getConfig();

       alert('My Plugin is ' + config.className);
              
       return (this);
      }
   

     function _ (fn) 
      {
       return function (args)
               {
                return this.prototype.rc(function () 
                                          { 
                                           fn.call(this, args) 
                                          }); 
               }
      }
      
     this.rc = function (args)
      {
       if (typeof args == 'function')
        {
         return $.fn._plugin.each(args);
        }
       else
        {
         initConfig(args);
         
         return getConfig().chainable
                 ? $.fn._plugin
                 : $.fn.createBox;
        }
      };
       
     
     }

     var _p = new MyPluginClass({});
     
     $.fn.pluginName = _p.rc;
     $.extend($.fn.pluginName.prototype,_p);
     $.extend($.fn.pluginName,_p);
     
    })(jQuery);

At first it may seem a little counter-intuitive, but much of this code you will simply copy and paste without having to understand. All you need to understand is where your code goes and a few simple rules to follow and you will write really cool plugins.

Usage

The above dummy plugin would be called as such

$(document).ready(function() 
 {
  $(selector).pluginName.show();
 });

Before we break down the pattern I want to show why we go through this process and how cool your plugins will become.

This pattern is fully backwards compatible to jQuery's suggested use. This means you can still use the traditional form of calling your plugin (if you want) as shown below.

$(selector).pluginName(args);

So we got backwards compatibility covered. But where is the magic?
The official jQuery pattern promotes the use of plugins are stand-alone widgets more or less that can be customized by way of tweaking various publicly exposed options. This is where my pattern diverges.

$(selector).pluginName(args);
$(selector).pluginName(args).method();
$(selector).pluginName.method()
$(selector).pluginName.object.method()
$(selector).pluginName.object.method(args)

All of the above are valid syntax when coded using this pattern, and yes, it's still chainable as long as you adhere to jQuery's plugin conventions to make it chainable. Sweet!

Still working on the write-up... follow my blog for updates. Gotta go get some sleep...

Questions & Answers

Here are a few questions asked by jQuery developers introduced to this new pattern. I am also linking back those questions asked in forums or other places.

Why break away from the common pattern of $(selector).plugin("method", args) for secondary methods?

The "common pattern" is specific to jQuery but unconventional to programmers coming from other backgrounds. My pattern does not break away from the jQuery way, but extends the possibilities by merging the two. Remember that this pattern is still backwards compatible with jQuery's convention.

This pattern allows for you to stick to the way jQuery promotes specifying methods, as well as stay with the conventional way of coding methods as done in most object oriented languages. In a sense it welcomes a wider audience of developers to develop plugins for jQuery.

Using an Object Oriented convention allows you to leverage all the benefits that OOP yields and integrate those into your jQuery plugins.

It simplifies having a granular syntax for your plugins. The whole concept of objects is to be able to interconnect them easily - this pattern makes it easy since it provides for a gateway to expose core JavaScript OOP.

Consider this pattern like an extended namespace: All the methods within the plugin belong to the plugin where it is safe to return an object in the traditional OO sense, and the selector continues to be passed on until you are ready to expose it for chainability.

Contextual Indent

2010-08-01T00:30:00.000-07:00

There are many different coding conventions that have developed over the years to make coding easier, faster, and intuitive. Amongst these convention lies an important component: indentation.

As is the case with many standards and conventions, indentation is not immune to debates and criticism. Whether you are a spacer or a tabber you have undoubtedly felt strongly about the respective conventions, but this indentation style will cater to spacers - or people who use spaces to indent code. Finally this will show that there is a good reason to use spaces as opposed to just it being a personal preference.

In this article I'm introducing a convention I've perfected over my many years of programming in both back-end as well as front-end technologies. The name I've assigned it is: contextual indent. The reason will become clear below.

Ultimately the purpose of this indentation style is to let the code guide your eye intuitively and attach instinctual sense of what it sees without having to put much thought into it.

What Is Indention

In an earlier article I had introduced my arguments for using spaces instead of tabs to indent your code. I went a step further by suggesting one space is all you need. Not four, not two, but only one space to demarcate indentation. This will prove useful for this indentation style.

Before we continue however we should take a minute to clarify what an indentation represent. Having a solid understanding of this concept is important to be able to agree with anything else in this article. If you disagree with the fundamental concept, you will not understand the benefits of this indentation style.

An indentation in code represents a relationship in the abstract sense. It indicates that whatever is indented belongs to or is controlled by whatever it is relatively indented to.

if (true)
 {
  alert('hello');
 }

Above we can see that the braces belong to the if statement, and the alert statement belongs to the braces that is in turn controlled by the if statement. We can see a hierarchy. This is the same hierarchy we want to preserve aesthetically in our code by way of indentation.

Contextual Indentation Guidelines

There are several guidelines that should be followed to successfully implement this indentation style. The best way to illustrate these is by way of examples.

Braces

In programming braces often denote a block of code, and sometimes even scope. Wherever braces are used we can follow the same indentation convention. This applies to functions, if statements, loops, with statements, and all other language specific functionality that involves braces.

A function can also represent a method, subroutine, class, or any other derivative that is similar in concept to a function. These are all indented in the same way.

function myFunctionName(args
 {
  ....
 }

We can see that the opening brace is on its own line as is the closing brace. This will allow for the opening and closing braces to line up perfectly, and give a sense of scope immediately and visually. This will become more important as one develops advanced code where anonymous functions may get defined anywhere in the code.

function myFunctionName(args)
 {
  return (function ()
           {
            ....
           });
 }

The above shows an anonymous function being returned. We can see that the function's braces are still indented with one space relative to the context (the return function's definition). This is how we derive the name of this indentation style.

if (condition)
 {
  if (second condition)
   {
    ...
   }
  else
   {
    ...
   }
 }
else
 {
  ...
 }

The last example shows how a nested if statement is supposed to be indented as well as illustrate the earlier point that the same style applies to any construct that involves braces regardless of whether it is an if statement or function.

Ternary Operator

Many times we will want to use a ternary operator (?:) instead of an if statement. This is usually the case during variable assignments.

var myVariable = (condition)
                   ? true
                   : false;

The above example shows how the condition is on its own line, and the actual operators are lined up underneath each other. This alignment is most useful when we have nested ternary operators, but is also useful to immediately see the alternative paths visually.

var myVariable = first condition
                  ? second condition
                     ? true
                     : false
                  : false;

The above is very clear. Next I will show you how it would look if we flattened it.

var myVariable = first condition ? second condition ? true : false : false;

Even with this overly simplified example it is still difficult to follow the logic of this nested ternary operator in flattened view. It becomes clear that taking the extra time to indent the code properly yields great savings when it comes to reading your code, and more importantly when having others read your code.

Objects

The beauty of Object Oriented Programming is the ability to interconnect different objects to alter the final behavior. This beauty can quickly become a long-winded chain of objects that can be difficult to read.

objectA.objectB.objectC.objectD.methodDA(paramA,paramB).objectE(params).methodEA(paramA,paramB)

While the above example is fictitious, it is actually shorter than many real-life examples may be. The point is that it can become difficult to read.

Using contextual indentation the rule becomes to have one object/method per line with the exception of the first one. Re-writing the above example results in the code below.

objectA.objectB
       .objectC
       .objectD
       .methodDA(paramA,paramB)
       .objectE(params)
       .methodEA(paramA,paramB)

As you can see, we align the dots. In languages that use other signs, such as Perl or PHP that use arrows (e.g. ->), we would simply vertically align those.

The reason we want to align the dots up front is because it suggests what follows is related to what's before it.

The above illustrates how to properly indent the objects. We observe another data set that causes the code to look to busy: Arguments.

Arguments

As with objects arguments can quickly become a long list of information that can be difficult to visually separate. The contextual indent provides a solution for this as well.

function(paramA,paramB,paramC,paramD,paramE,paramF,paramG);

Again, the above does not illustrate a real-life example, but it could very well be similar to the above. Furthermore, in the case of OOP it is possible to have several chained objects or methods that take parameters as shown in the example above for Objects.

Re-factoring the above would yield the output below.

function(paramA,
         paramB,
         paramC,
         paramD,
         paramE,
         paramF,
         paramG);

Unlike objects we can see that in this case we don't align the commas up front. As a matter of fact the above is just coincidentally that the commas are vertically aligned, but depending on the length of the parameter this would not be the case, nor is there any visual value to doing so. As a result, we just keep the commas at the end regardless of how they appear visually.

Again, unlike objects the parameters or arguments are not related to each other - it's just a list.

Fixing the objects example would yield the output below.

objectA.objectB
       .objectC
       .objectD
       .methodDA(paramA,
                 paramB)
       .objectE(params)
       .methodEA(paramA,
                 paramB)

It become obvious real fast what belongs to what at first glance - unlike its serialized predecessor.

Having said all of this regarding arguments, keep in mind that most of the time this can be avoided by the use of HARP.

SVN Merge Branch To Trunk with minimal Tree Conflicts

2010-06-29T18:08:00.000-07:00

After having spent (too) much time trying to figure out how to get around receiving Tree Conflicts when I merge my branch with my trunk I have finally found a solution. I'm a little disappointed that SVN makes this task somewhat difficult, but this is not surprising since apparently SVN is not designed for branching according to Apache's best practices.

Development Environment Setup

In my development environment I prefer to branch off my trunk into dev projects in a very pessimistic way: Let me mess up with no negative impact.

In other words I want to isolate my active development into its own sandbox to where I can have the peace of mind that I am free to experiment, corrupt files, corrupt code, and do anything I want with no consequences. This is what drives progress: experimentation. How can you have progress if you're scared to try new things?

As a result of this I work in isolated branches. These branches are then gradually merged into the trunk as I develop and become happy with some code worthy of making it into the trunk.

SVN layout

A typical setup will look something similar to this:

/projects
         /projectA
                  /branches
                           /active
                  /tags
                  /trunk
         /projectB
                  /branches
                           /active
                  /tags
                  /trunk
         /projectC
                  /branches
                           /active
                  /tags
                  /trunk

As you can see it conforms the Subversion's recommended layout. Chances are that you are already setup this way.

Server layout

Here is where I begin to deviate from the recommended setup: Instead of having a branch and a trunk checked out, I only checkout a branch. It is silly in my opinion to check out the trunk for every project. Leave the trunk in SVN and only worry about your active branch (in your active development environment that is).

In my setup I never work on the trunk directly. Consider the trunk as the folder that contains pre-finalized code. That's right, read this again, no trunk development.

A typical setup on my server will look something similar to this:

/home/milan/projects/
                     projectA/
                     projectB/
                     projectC/

Each of these projects is actually a checked out branch of the trunk. This I do with a simple svn checkout command as in:

mkdir -p /home/milan/projects/projectA 
svn co svn+ssh://local.svn.server/usr/repository/svn/projects/projectA/branches/active /home/milan/projects/projectA
svn co svn+ssh://local.svn.server/usr/repository/svn/projects/projectB/branches/active /home/milan/projects/projectB
svn co svn+ssh://local.svn.server/usr/repository/svn/projects/projectC/branches/active /home/milan/projects/projectC

This is neat because nowhere do we have to see the words "trunk" or "branch". This is perfect for developers who do not want to fiddle in SVN lingo and who may rely on an in-house developed build script. As far as the developer is concerned there is only a set of source files that then somehow get magically placed in a repository.

Either way it's clean and compact for every developer at all skill levels.

Branch Merging

There are many resources online discussing how to merge branch to trunk or trunk to branch. What we will not find of as much is how to merge our branches in such a way as to avoid the annoying tree conflicts.

A tree conflict can occur for many reasons. In my case the conflict occurred on files that were either added or deleted in my branch but somehow were not making it out or in to the trunk after a merge.

To narrow the example down even more, when the trunk had a file for example, and I removed the file from my branch, it would still stay in the trunk even after a branch to trunk merge. What did I get as a message to help me out in resolving this? A tree conflict. Great. That tells me nothing.

Merging Convention

The SVN book's solution on how to merge my branch back to the trunk, we find we would have to do something like this:

$ cd projectA/trunk
$ svn update
At revision 405.

$ svn merge -r 341:HEAD svn+ssh://local.svn.server/usr/repository/svn/projects/projectC/branches/active
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

# ...examine the diffs, compile, test, etc...

$ svn commit -m "Merged projectC branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.

Notice how it relies on having a trunk checked out. To me that's a no no. Not only that but to find the 341 number one would have to run a command such as:

svn log --stop-on-copy

One would then have to find the last entry and take the revision number of that entry. It's a mouthful but I wrote another article how to speed up that step as well.

Problem

As mentioned before the common problem are tree conflicts from added and deleted files between the trunk and checked out branches. This means that when we run a svn status we will have a bunch of "C" characters appearing next to files in conflict that will need to be resolved prior being able to do a svn commit.

This is painful and not only that but when you svn resolved the file and successful svn commit it still doesn't reflect such changes onto the trunk when merged. What the heck!?

Okay so I'm sure there is a technical reason for why this is happening, but quite frankly this is not something SVN should cave in on and be sufficiently smart to figure out what we want to do.

Solution

My solution is actually a lot simpler than the aforementioned official version and the files that we add or remove in our branch will actually get added or removed from the trunk after a merge.

In my example we assume we only have a branch checked out and no trunk. This means that my example will assume you're working in a checked out branch. That's it.

cd projectA/
svn up
svn delete someFile
svn commit
svn up
svn switch svn+ssh://local.svn.server/usr/repository/svn/projects/projectA/trunk
svn up
svn merge svn+ssh://local.svn.server/usr/repository/svn/projects/projectA/trunk \
 svn+ssh://local.svn.server/usr/repository/svn/projects/projectA/branches/active
svn commit
svn up
svn switch svn+ssh://local.svn.server/usr/repository/svn/projects/projectA/branches/active
svn up

It may appear convoluted at first, but after you understand that you need to run a svn up to avoid mixed-revision working copies it begins to make sense.

What it boils down to is this:

Add/delete your files in your branch
Switch your branch to become your trunk
Merge your branch into this trunk
Switch back your working directory to become your branch again

This allows you to not have a separate checked out trunk and a separate checked out branch.

Merge Tool

You have by now undoubtedly come across a tool that exists to facilitate branch merging called svnmerge.py. You can always use it, but that's another prerequisite for your system ;)

SVN one-liner: Get branch creation revision

2010-06-28T12:35:00.000-07:00

It is sometimes useful to know at what revision a project was branched. Mostly this is used for merges, which in turn may be automated in build systems. This is where a one-liner may be useful.

SVN Log

We know that svn log --stop-on-copy let's us see when a codebase was branched off. This is usually the last revision number in the list generated by this command. The question is: how do we extract this revision number?

Solution

The one-liner assumes a relatively full UNIX installation that contains the tools grep, tail, and sed. If your system doesn't have either of them, install them.

svn log --stop-on-copy | grep r[0-9] | tail -1 | sed 's/r\([0-9]*\)\ .*/\1/g'

The above one-liner gets all revisions, takes the last line, and then uses some regular expression magic to extract the revision number at which time the branch was created (this is an assumption based on good SVN housekeeping).

FreeBSD Makefile Local Variables

2010-06-12T14:22:00.000-07:00

It is sometimes useful to have local variables in a Makefile that are available only to certain targets. In GNU make this is possible, however in the make utility included in FreeBSD's distribution the only local variables available to us are the make's seven included local variables. In other words, in FreeBSD there is no mechanism to have local variables - but there is a way to simulate it.

GNU make

In GNU make we can create local variables by specifying them on the target line as such:

target: SOMEVAR=1
      @echo "I see " ${SOMEVAR}

This will yield the following output:

I see 1

GNU make is great, but what if we don't have gmake installed? This is where we have to get a little creative.

FreeBSD's make

The out-of-the-box make utility that comes with FreeBSD has some built-in features that we can use to simulate local variables. The above code would normally throw an error on FreeBSD saying something to the effect that SOMEVAR=1 target doesn't exist since it treats it as a dependency unable to understand the gmake local variable declaration construct. Boohoo.

The solution is pretty simply. We can translate the above GNU make code into FreeBSD native make code:

.ifmake target
SOMEVAR=1
.endif

target:
        @echo "I see " $(SOMEVAR);

The variable will still be global, but it will only be defined if the intended target is called upon. We can effectively wipe it out with an else statement if we don't want it to be available on any other targets. Again, this is just simulated, not a real local variable. This is very useful when you want to do some advanced conditional tasks on targets. I like to use this to maintain one target that can adapt to Apache 1 and Apache 2 accordingly (e.g. when compiling PHP).

Multiple Monitors via USB

2010-06-04T13:10:00.000-07:00

If you are looking to extend your workspace with multiple monitors but you do not have many video ports, there is an alternative solution: monitor-over-USB.

In my setup I have five (5) monitors, but my laptop only has one video port and one digital video port. This means that my hardware limits me to two (2) monitors. To extend this I got three Arkview USB 2.0 Display Adapters. It supports up to six (6) adapters, which means I could go as much as eight (8) monitors.

While they work relatively well there are some small quirks with some of them. In this post I will describe some issues I have with them and how I manually solve them in case you encounter the same.

Troubleshooting

Monitor doesn't turn on at system boot

This is an interesting issue and there are several things to try when this happens.

The first thing you have to make sure of is that the Arkview adapter powered on properly. It seems that this is the root of all evil with screens not displaying anything.

The next thing you want to try is unplug the adapters that did not fire up. There are two ways you can do this:

Unplug the USB side of the adapter and re-plug it back in. This may be sufficient to get it back up and running.
Unplug the USB and the video cables of the adapter, replug the USB side into the adapter and then replug the video side. It may take a second for the green light to come back on.

If the above don't work, try to unplug all adapters that failed and try the above in different orders. You do not usually have to unplug the adapters that did fire up properly in order to get the failed ones to work.

Convert mod_rewrite to mod_perl

2010-04-24T20:00:00.000-07:00

We know that mod_perl allows us to take over much of Apache's work flow. This holds true for any mod_proxy directives and functionality as well.

In this article I want to show how we can easily do some advanced mod_rewrite stuff using purely mod_perl and without having to use LWP for any proxy activity (as some modules do)!

I want to take this a step further though: I want to do this by giving a configuration in mod_rewrite and then I want to translate this into mod_perl so you can draw the parallels on what needs to happen in mod_perl that correlates to the corresponding functionality using mod_rewrite and mod_proxy. Strap yourself in for we're entering some really exciting territory, and I know documentation out there for this type of comparison is really scattered and scarce.

We will explore this example using mod_perl 1 so it reaches a wider Perl audience. The thinking is that there's easily accessible documentation on mod_perl 2's equivalents to mod_perl 1's features.

Rewrite Goal

In this example we want to accomplish the following:

Rewrite visible URL in browser's location bar
Proxy content from another location
Make content appear under the newly rewritten content.

In this example we will use the following URIs:

Original URI: http://www.adamovsky.com/cgi-bin/show_page.pl?hello.html
Desired URI: http://www.adamovsky.com/show/hello.html
Display content from: http://www.adamovsky.com/long/folder/hello.html

Are you excited yet or what? Strap yourself in, this is going to get exciting.

Apache Setup: mod_rewrite

The first thing we want to do is configure our Apache so that it will be able to support our desired setup. If you need a refresher, read some Apache configuration docs here.

We will need two virtual host directives. One will serve as the user facing virtual host, and one will be a background virtual host that will serve the proxied content. The reason we do it this way is because it will demonstrate a setup that will allow for more complex setups. In other words, you could get away with just one virtual host for both the front and back end in most instances, but again, I want to assume a wider audience.

Public Virtual Host

The user facing, or public, virtual host entry would look something like this:

<VirtualHost _default_>
   ServerName adamovsky.com
   ServerAlias www.adamovsky.com
   DocumentRoot /home/path/to/adamovsky.com
   RewriteEngine on
   RewriteCond %{REQUEST_URI} ^/cgi-bin/show_page.pl$
   RewriteCond %{QUERY_STRING} ^(.+)$
   RewriteRule ^(.+)$ /show/$1             [R]
   RewriteRule ^/show/(.+)$ http://10.15.1.5/long/folder/$1  [P,L]
 </VirtualHost>

In case this is a little confusing, here is what is happening:

First we try to match the URI without the query string
Next we match the query string to make sure it conforms to what we need (this would usually be a more complex regular expression)
If the conditions are true, we will rewrite the URL in the location bar
The new rewritten URL will now make a proxy request to the back end virtual host

The [R] stands for rewrite, and the [P,L] stands for proxy and last as in this being the last rule of the rewrite ruleset that matches the given condition (in case you have other rulesets for other conditions).

Private Virtual Host

The virtual host block that will be responsible for actually delivering the content that is proxied will look something like below. Note that we will use a private IP address. This can be any private IP address or public IP address though you will not need to have a public IP address as it would be a waste. In our example we use 10.15.1.5 as our private IP address.

<VirtualHost 10.15.1.5>
   ServerName adamovsky.com
   ServerAlias www.adamovsky.com
   DocumentRoot /home/path/to/adamovsky.com
 </VirtualHost>

This example is simple yet advanced in concept. Take some time to pause, absorb, and understand what is going on. This will empower you to further develop rulesets that will be a lot more complex.

The back end, or private, block could be anything. It could be a lighttpd server instead, a lightweight Apache instance, or even a remote server. To keep this example simple however we will do everything on the same server.

Apache Setup: mod_perl

What follows is the equivalent functionality as described above. If you have not read the above example do so now.

You might be asking yourself and why are we doing this? There are many reasons for this but the main reason is in the event where you have a complex setup that needs a rewrite map. This is where this solution will really shine since with a rewrite map (assuming it's a Perl script) will load up a Perl instance each time (think CGI and not mod_perl). We're talking rapidly decreasing performance on an active website.

If nothing more, use this as a guide to see how to circumvent mod_rewrite for complex setups just to further your understanding of mod_perl for this purpose.

Public Virtual Host

The only block of the two that needs to be modified is the public facing one since the back-end block is just a dummy block serving files.

<VirtualHost _default_>
   ServerName adamovsky.com
   ServerAlias www.adamovsky.com
   DocumentRoot /home/path/to/adamovsky.com
   PerlTransHandler RewriteModule
 </VirtualHost>

That's right: we have removed all mod_rewrite specific directives and replaced them with a PerlTransHandler which points to our Perl module called RewriteModule.pm.

Now whenever an incoming request is handled, we pass it off to mod_perl instead mod_rewrite.

Perl Module

The final piece to this puzzle is the actual mod_perl handler. Again, keep in mind that this is merely a translation of the equivalent mod_rewrite rulesets listed above.

package RewriteModule;

use Apache::Constants qw( :common REDIRECT );

$| = 1; 
my $source_url = 'http://10.15.1.5';  # have this reflect your private IP

sub handler {
 my $r = shift;
 return &parse_uri($r);
}

sub parse_uri {
 my $r = shift;
 my $hostname = $r->hostname;
 my $uri = $r->uri;
 my $query = $r->args;

 if ($uri =~ /^\/cgi-bin\/show_page.pl$/ && $query =~ /^(.+)$/)
  {
   $r->headers_out->set('Location' => "http://www.adamovsky.com/show/$1");
   $r->status(REDIRECT);
   $r->send_http_header;
   return DECLINED;
  }

 if ($uri =~ /^\/show\/(.+)/)
  {
   return DECLINED if $r->proxyreq;
   $r->proxyreq(1);   # this is equivalent to [P]
   $r->args($query);  # this sets the query string
   $r->uri("http://$source_url/long/folder/$1");
   $r->filename( "proxy:http://$source_url/long/folder/$1" );
   $r->handler('proxy-server');
   return OK;
  }

 return DECLINED;  # in case neither if()'s validate
}

1;

Again, this is a very specific example with much hard-coded paths, URIs, etc. This is just to show the concept, but you should modularize the code to fit your needs.

If this doesn't excite you, I don't know what will.

Advanced CSS Style Order

2010-04-16T18:47:00.000-07:00

There are as many opinions on how to organize CSS rules as there are personalities. Whenever I am put in charge of cleaning up the CSS or promulgate a best practice, without hesitation I push for the described solution. In this article I will present an enterprise level way of organizing CSS rules.

Enterprise level here is defined by how simple it is to augment, maintain, and debug in context of a team rather than an individual author.

At the end of this article it should be evident that this order offers all the benefits that will be outlined in this article. To be able to make a sound decision on how to organize your CSS you should read what others recommend. A quick Google search will yield the following:

As you can see, everyone has an opinion, and here is mine.

Benefits

It is important to me that my CSS works for me, and not the other way around. To make this happen I need the CSS to be organized in a way that guides me to where I need to be to work with the right style block. In other words, I don't want to have to waste my time looking for the right place to edit my rules, I just want to be guided there.

So how can be give our CSS file this unspoken intelligence?

This "intelligence" should yield the following benefits:

Eliminate duplicate blocks
Eliminate duplicate style properties
Easily identify CSS specificity
Minimize scrolling and searching
Facilitate copy and pasting
Make the CSS predictable
Make the CSS intuitive

You get the idea. It should virtually do all the thinking for you.

Advanced CSS Order

The key lies in sorting everything alphabetically with decreasing scope of elements. Simple as that. No funky hierarchical layout, no funky indentation, no ad-hoc ordering. This is fool-proof and we will see how it some cases it will actually benefit you technically.

body,
html 
 {
  height: 100%;
  margin: 0;
  padding: 0;
  width: 100%;
 }
 
.sprite
 {
  background-image: url('sprite.png'),
  display: inline-block;
  padding: 2px 0px;
 }

#footer
 {
  background-color: #fff
 }

The above illustrates the gist of the decreasing scope sort-order while maintaining an alphabetical order of everything.

Decreasing Scope-Order

Imagine how the CSS is applied to the elements based on the selector. If a DOM element such as div is the selector, the scope of that CSS will be all divs. A class such as .sprite will limit that scope only to those elements that have such a class defined onto them. Lastly, an id will limit the scope to a unique element. This correlates to the CSS specificity which makes it relatively simple to visualize how a CSS rule will be applied onto the document just by the virtue of its definition order within the CSS file.

Okay maybe the last sentence above was a little overly ambitious, but this is the only order that will give you anything close to that.

To recap, this means we will order our file in this order:

DOM Elements
Classes
Ids

Alphabetical Sorting

It is worth repeating that we will alphabetically sort everything. This means the selectors as well as the style properties within CSS definition blocks.

a,
div,
h1,
h2,
p
 {
  ...
 }

.entry,
.row,
.sprite
 {
  ...
 }

#footer,
#header,
#navigation
 {
  ...
 }

Take some time to soak this in. Notice how we sort the selectors alphabetically? We will do the same with properties.

selector
 {
  border: 1px solid black;
  margin-bottom: 2px;
  margin-left: 1px;
  margin-right: 2px;
  margin-top: 0px;
  padding: 1px;
  text-indent: 9999px;
  width: 50%;
  z-index: 1px;
 }

Above we can see the style properties sorted alphabetically. Give it a shot, and add a top margin and you will see how foolproof it is. The mere order of things will guide you into the right direction where you would place it, and if there already is something there it will automagically stop you from adding a duplicate style property, and instead re-evaluate the existing property and assess whether to edit it or remove it. In either case, you will not end up with a bloated CSS file by entering duplicates.

Multi-line Definitions

Some CSS developers prefer to have all definitions on one line. One of the rationales behind this is that they want to see as much as possible on the screen so they don't have to scroll.

No really.

selector  { width: 50%; margin-bottom: 2px; text-indent: 9999px; margin-left: 1px; z-in...   }
selector  { width: 50%; margin-bottom: 2px; text-indent: 9999px; margin-left: 1px; z-in...   }
selector  { width: 50%; margin-bottom: 2px; text-indent: 9999px; margin-left: 1px; z-in...   }

I'm not even going to entertain long lines in my example, but as you can imagine these can be some very looooong lines. Keep in mind that there usually is no sort-order on this line so it is next to impossible to quickly see duplicates let alone get a visual idea of what's going on without having to read through all properties. This is something that can easily be fixed by simply breaking these definitions into separate lines. No magic here.

Multi-line Selectors

The other thing I like to break up into separate lines are the actual selectors of the CSS blocks.

a,
div,
h1,
h2,
p
 {
  ...
 }

The above is how I like to do things. It's not so obvious as to why we would want to organize it this way with the above example, but I want to illustrate a point. Consider the following example.

a,
div.sprite .entry .float,
h1.sprite #deal,
h2.subtitle .center,
p a span.mail
 {
  ...
 }

A more realistic example, as the one above, clearly shows that the selectors can easily grow in length. Consistently breaking these into separate lines will make it very easy to manage these just as it is managing CSS properties when they are broken up on individual lines.

The next question is why do you put the opening bracket on a separate line? Think copy & paste.

When we modify the selectors, either adding or removing, we may trip that opening bracket if we don't pay attention. The more people deal with our CSS file the more the chances of sloppiness. To stay in line with enterprise development, we want to minimize the risks, therefore we adopt a convention that minimizes these risks.

Maintenance

The usual complaints that will arise from non-enterprise developers is that if a selector changes it will require to move around the block within the file. Yeah, so? That's called being professional and doing your job right. Stop whining.

Conclusion

We can clearly see that by simply exercising some discipline and uniformity we can achieve all the said benefits.

Try it. You won't go back to any other order. This is the new order.

Automatic SVN file handling one-liner

2010-04-13T14:40:00.000-07:00

Recently I needed a quick solution for adding and removing my source controlled files that I manage via Subversion (SVN). The constraints were that I didn't want to write a script for two reasons: it would be silly to write a script for something so conceptually simple, and I have better things to do with my time.

Problem

SVN by default requires you to manually add and delete (rm) files. This is a pain because if you have many files, you will be busy for a while.

[root@server /root]# svn status
?       milan.txt
!       test.txt

The above symbols indicate milan.txt is not checked in SVN (new file) and test.txt is in SVN but no longer on the file system (deleted).

One thing I really like is one-liners when you have access to a command prompt - especially in UNIX flavored operating systems. One-liners makes it very easy to integrate complex functionality inside other scripts, easily executable from within crontabs, perfect for System Administration, and so on.

There are several resources out there (here, here, and here to name a few) on how to accomplish the addition and removal of files that are source controlled via SVN.

Solution

My solution is just one line and thus more portable.

svn status | sed 's/^\!\ *\(.*\)/svn rm \1/' | sed 's/^\?\ *\(.*\)/svn add \1/' | \ 
sed -n '/^svn\ / p'

The output will result in the corresponding SVN commands that can then be fed to whatever you want.

svn add milan.txt
svn rm test.txt

You could feed this to xargs and bash to execute it sequentially like this:

svn status | sed 's/^\!\ *\(.*\)/svn rm \1/' | sed 's/^\?\ *\(.*\)/svn add \1/' | \ 
sed -n '/^svn\ / p' | xargs -I % bash -c %

Pretty simple no? And now you can simply copy and paste this wherever you need it. I chose to feed it to bash because that's the shell I use, but you can use whatever you want.

Following this pattern one could easily add handling for any other SVN status.

Setting up a Cloud on FreeBSD

2010-03-21T11:27:00.000-07:00

This article will explore how to create a cloud-like environment on a FreeBSD server.

Terminology

Throughout this article I will make use of certain words that may be foreign to the average user or used in a different context that may call for confusion. To synchronize our definitions, here is the list of words as used in context of this article:

cloud - The architecture that will allow a more fault-tolerant response to a request.
host - The physical server that runs the proxy and hosts all jail instances.
jail - A virtual server instance via FreeBSD's jail() command.
node - Any given building block of the cloud environment (e.g. jail, proxy, host, ...)
proxy - The proxy software running on the host (e.g. HAProxy).
repository - A shared folder containing common files.
user - An end-user making requests to your services.

Desired Architecture

Here I will attempt to give a quick snapshot of where we're headed so you can decide if this is a setup you want to mimic.

When a user makes a request it will have to figure out which node in the cloud is best suited to handle the request. The course of action happens something along these lines:

Request goes to DNS
DNS sends the request to either Server A or Server B
Selected server forwards request to internal proxy
Proxy load balances the jail nodes
Proxy proxies request to best suited jail node
Response get sent back to user.

This is a basic request/response schema. Now we have to configure it so that when one of the jail nodes are down, it can continue serving the requests transparently. Keep in mind this is a simple illustration of the concept; in production this will be replicated to as many nodes as needed. Once you understand a basic setup, you can very quickly expand it to a very sophisticated design.

Pre-requisites

We will need to download a few software packages to get the whole setup going. If you follow these steps, it should be a relatively smooth process.

FreeBSD 6.2+
Network already setup and configured
GNU make (gmake)
HAProxy
DNS (e.g. Bind, myDNS)

Not too bad. The hardest part will be having the discipline of adhering to some conventions that will be spelled out in this article. The good thing is that even if there is a lack of discipline it will not break the architecture, it will merely clutter it. In a sense this is a fool-proof design.

Naming Convention

It is important to settle on an extensible naming convention for your cloud environment. This is a fundamental key ingredient to a successful architecture that is overlooked more often than not. Here you will see a naming convention that I have come up with that is abstract, flexible, and extensible all in one.

Before we explore the naming convention itself, I want to highlight the goals this convention is intended to tackle.

The naming convention successfully considers the following points

Geographically agnostic (we don't care where the node is e.g. data center, city, country)
Owner agnostic (we don't care who the node belongs to)
Product agnostic (we don't care what software runs on the node)

In a cloud environment it is very important to decouple each node as much as logically possible. This is analogous to good Object Oriented Programming, where we abstract our classes so they can be as interchangeable as logically possible.

For our sake and purposes we want to achieve this decoupling so that the nodes can remain mobile. This means we want to be able to move them around anywhere in the cloud without having to worry about the name of the node misleading the user as to its functionality based on an out-of-sync description. If none of this makes sense or you have not thought of these points, simply follow my convention and you will be relatively safe and immune to any shortcomings accompanied by an expanding or dynamic topology.

Name Anatomy

The name that you choose is divided into three logical parts.

Purpose
Environment
Enumerator

Purpose

The purpose of a node would describe what the node's main reason for being is - or purpose. We want to keep this abstract so a purpose such as db would be preferred over oracle, mysql, or microsoft-sql. While it is highly recommended to keep the purposes abstract, it may be desired by business owners to associate what is running on the node. I don't advise it.

Take the example of everyone running Oracle in the 90's and now those same companies migrating to mySQL to lower their financial overhead (e.g. licensing fees). Had they attached what instead of purpose, they would now have to find all occurrences of oracle to mysql in all documentation, code, topology maps, etc. Time well wasted, not to mention the opportunity for human error by way of overlooking some occurrences leading to potential software failures.

Environment

The next part of a name is the environment the node finds itself under. The generally accepted environments consist of a development, staging, and production environment - commonly referred to as dev, stag, and prod. We can leverage this convention and integrate it into our name.

Sticking to the example we've used up to this point, our name looks something similar to db.dev, db.stag, db.prod thus far. This is an incomplete name! Keep reading for the full intended name. I'm just illustrating what we have accomplished up to this point.

It is important to understand that all of these environments mirror at least what's in the prod node. This means that what we see on the final product, or production, can also be found in stag and dev.

Conversely, everything we find on dev will definitely not be on stag and prod. This is stating the obvious, but I want for even the beginner to understand this, and that this architecture is actually designed to allow a developer to be able to literally crash his or her own development node without adversely effecting the rest of the infrastructure.

Enumerator

The last part is the enumerator. This is a numeric value that is simply incremented by one and can be anything. I like to use double digit (e.g. 01) as the likelihood of exceeding single digit is high, but exceeding double digit is low - in my case. Again, keep in mind that with virtual nodes (e.g. jail, vmware, xen) it is very easy to quickly pile up node names.

Finally we come up with a name such as db.dev.01, db.stag.01, and db.prod.01. This can then be sliced and diced anyhow you want with the node's integrity intact.

There is one more important caveat to the enumerator in context of the environment. Pay attention. This is very important to understand, accept, and agree on, for the sake of keeping in line with the goals of a successful cloud implementation: An equivalent enumerator across the environments does not imply mirroring.

In other words, what I'm saying is that you do not want to get trapped into thinking that db.prod.01 is necessarily a mirror of db.stag.01. On a small topology this will coincidentally be the case, but never intentionally. It can therefore very well be that when we push content from stag to prod, that we push from db.prod.03 from db.stag.01. These are then linked implicitly as opposed to explicitly. This means that we do not define this relationship by way of the naming convention. All relationships between nodes are always handled externally to the naming convention via some sort of programmatic logic (e.g. proxy, code).

The importance of the previous paragraph cannot be stressed enough. The enumerator's purpose is really to just uniquely identify the node. This will prove very helpful in a collaborative environment where each developer may each get a same purpose node, with a different enumerator, that will all push to the same staging and production environment.

Naming Convention Examples

To get you on your merry way here are some names that I like to use (keep in mind that they all have postfixes of environments and enumerators e.g. web.dev.01):

asset - Static asset server (lighttpd serving GIFs, JPGs, JS libraries)
db - Database server
proxy - Proxy server
server - Host server (physical server that runs jails for example)
web - Web server

Preparing FreeBSD

The first thing we want to make sure is that we have a clean, and that means lean, host server. We want to try to keep only the absolutely necessary software installed on the host as to minimize potential application-originating security holes as well as reducing any physical server resource hogging.

The best approach is to disable all daemons such as DNS, sendmail, Apache, inetd, and anything else. We do not need these on the host server since we will be running all of these services within sandboxed jails. How to disable these is beyond the scope of this article, but it shouldn't be that difficult. Google it.

FreeBSD Source

It is critical that when FreeBSD was installed, all the sources were installed as well. To check if this is the case check the /usr/src folder. If it is populated you're good - otherwise install it before proceeding. This will be necessary for jail creations.

Filesystem Hierarchy

There are a million and one ways you can organize your file system. In this tutorial I will follow my recommendations but do feel free to adapt any examples to your hierarchy.

Jail base
We want to keep all our jails inside one common root folder. Let that path be /usr/jails/. This means if I will setup a jail with the hostname web.dev.01.adamovsky.com, the root folder of that jail would be situated in /usr/jails/web/dev/01/adamovsky.com. You can of course choose any type of convention you want since this convention does not have any impact on the actual setup we are trying to achieve.
System File Repository
The next thing is a little controversial in setup, but assuming security precautions have been taken on your overall OS setup, this repository will make it very easy to keep all jails in sync in regards to system files. Disclaimer has been given.
The goal of this setup is to make these system files shared amongst all jail nodes:
- /etc/hosts
- /etc/resolv.conf
You can of course expand upon this list. Basically these are important files that are to be shared so that when an update is made to them they are immediately reflected in all jails automagically.
The folder I like to place all the system files is in the semantically correct folder /usr/local/share/system/. In this folder I replicate the hierarchy of the files. This means /etc/hosts would be in /usr/local/share/system/etc/hosts. Keeps it easy to navigate.
All we need to do at this point is just move the files into this shared repository.
```
mkdir -p /usr/local/share/system/etc
     mv /etc/hosts /usr/local/share/system/etc/hosts
     mv /etc/resolv.conf /usr/local/share/system/etc/resolv.conf
```
Scary stuff. We have just moved some critical files to networking away from the expected locations. Let's make some adjustments so that FreeBSD won't complain.
```
ln -s /usr/local/share/system/etc/hosts /etc/hosts
     ln -s /usr/local/share/system/etc/resolv.conf /etc/resolv.conf
```
What we have done here is symbolically link these files from the common repository into their intended locations. Coincidentally this is exactly the same steps we will follow for any jails we create. It is these steps that will allow us to have a shared system file that will automagically reflect any changes across all jails.
A word of caution: If the server relies on any NFS mounted filesystems, such mounts may fail upon a server reboot since the /etc/hosts file may not yet be available for resolving the hosts of your NFS sources. If this is the case one quick and rigid solution is to simply use the IP addresses rather than hostnames. Keep this in mind and prepare accordingly as a server reboot will happen sooner or later.

Jail Setup

The actual setup of the jail nodes is pretty straight forward. We will simply follow the steps found in the jail manual (man jail) but nothing is stopping you from using helper tools like ez-jail.

We will continue using web.dev.01.adamovsky.com in the examples to follow. Adjust this according to your needs.

D=/usr/jails/web/dev/01/adamovsky.com
     cd /usr/src
     mkdir -p $D
     make world DESTDIR=$D
     make distribution DESTDIR=$D
     mount_devfs devfs $D/dev

Preparing Filesystem

We need to make some small tweaks to the filesystem hierarchy to prepare it for some steps down the road.

Ports Collection
We need to create the /usr/ports folder within the jail so we can mount the Ports Collection into the jail. This will be important for when we will want to add extra applications within the jail.
```
mkdir -p /usr/jails/web/dev/01/adamovsky.com/usr/ports
```
Once we have the folder created we can mount the ports folder of the host server.
```
mount_nullfs /usr/ports /usr/jails/web/dev/01/adamovsky.com/usr/ports
```
Let's not forget about the boot-up process and add this line to /etc/rc.local too.
```
echo "mount_nullfs /usr/ports \
     /usr/jails/web/dev/01/adamovsky.com/usr/ports" >> /etc/rc.local
```
Shared Repository
The next thing we want to do is create a folder that mirrors our shared repository /usr/local/share/system. The reason for this is because we only want one mount point rather than always having to mount individual files.
```
mkdir -p /usr/jails/web/dev/01/adamovsky.com/usr/local/share/system
```
As mentioned before, we will repeat the same steps and symbolically link the system files into their respective locations. Let's do it.
```
cd /usr/jails/web/dev/01/adamovsky.com
     rm etc/hosts etc/resolv.conf
     ln -s /usr/local/share/system/etc/hosts etc/hosts
     ln -s /usr/local/share/system/etc/resolv.conf etc/resolv.conf
```
Notice the etc paths are relative to the folder you changed into.
At this point if you make a change in the host server's /etc/hosts file for example you should see the changes in the jail's /etc/hosts file (in our example that file would be /usr/jails/web/dev/01/adamovsky.com/etc/hosts).

Configure Jail

There is one more critical thing we need to do: setup the startup configuration for the jail. This will ensure the jail is booted up properly in the event of a server reboot. These same settings will be used for starting the jail manually.

Open up the file /etc/rc.conf. In this file we need to make sure that the following few lines exist and if they don't add them.

jail_enable="YES"
  jail_set_hostname_allow="NO"
  jail_list="dev"
  jail_interface="bge0"
  jail_procfs_enable="YES"

Pay attention to what needs to be configured here. The two directives we're interested in are jail_list and jail_interface.

jail_list
This is the only line that will need to be edited every time a new jail is added. It essentially stores the list of all the jails that are defined so FreeBSD knows what jails to boot-up for example.
This is a space separated list of all the defined jails. The jail name is what needs to be entered here. This name is defined in the actual jail definition; read below.
jail_interface
This actually determines which network card interface the jail's network is supposed to be attached to.
You can find your interface by running the command ifconfig -a. Once you have the interface name simply define it as the jail_interface.

Other than these two directives the other settings will remain pretty untouched as your architecture grows.

Jail Definition

The next thing we need to do is configure the actual jail's properties such as IP address, hostname, etc...

Again, open up /etc/rc.conf in the host server and add the following (if it's not already in there):

jail_dev_hostname="web.dev.01.adamovsky.com"
  jail_dev_ip="10.2.2.10"
  jail_dev_rootdir="/usr/jails/web/dev/01/adamovsky.com"
  jail_dev_devfs_enable="YES"
  jail_dev_exec_start="/bin/sh /etc/rc"

This is the template for a jail definition. Copy and paste this every time a new jail is added. There should be one set of the aforementioned configurations for every jail and configured accordingly.

The naming convention that the jail() command expects is jail_jailname_*. This means that whenever an entry is made into /etc/rc.conf, the directives will need to be adjusted to reflect the name of the jail that is being setup. In our example we use the name dev but it could be anything.

One important directive here is the jail_dev_ip. This directive defined what IP address our jail will be listening to. This can be any IP address you want, but since our setup will not require it to have direct external access we can get away by assigning an internal IP address (see Private Network Wikipedia entry for internal IP address ranges or consult your Network Administrator).

Save /etc/rc.conf and exit; you are done with that file - for now.

Starting Jail

At this point we are ready to start up our newly created jail. We will use the standard jail tools for our jail administration. You can later automated some of these tasks but at this point it is important that you understand what is going on.

/etc/rc.d/jail start dev

The above command will start the jail with the jail name "dev" - which we defined in the jail definition up top.

Install Software Inside Jail

Now we're ready to setup whatever software we want inside the jail. To keep our example simple I will limit this to installing the bash shell as it is my preferred shell to work with.

Let's enter the jail.

We need to find the jail id of our jail. To do so we use the command jls which will list all the running jail.

[root@server /etc]# jls
   JID  IP Address      Hostname                      Path
     3  10.2.2.10       web.dev.01.adamovsky.com      /usr/jails/web/dev/01/adamovsky.com

We are ready to enter. All we need to do is call the command jexec 3 sh. This assumes the jail id is 3 - but it will be whatever number is displayed using the jls command above. In our example it happened to be 3.

At this point you should have gotten a new command prompt. To ensure that you are in the correct jail check the hostname using the hostname command. This should reflect whatever hostname you assigned to the jail in your jail definition.

Install Bash

What follows is the process to install any software from the ports collection.

As mentioned above we will install bash as an example. So let's get to it.

cd /usr/ports/shells/bash3
   make clean install

We need to make sure to do a clean install whenever we install anything from the Ports Collection since it's linked against the host server's ports tree. This means that if that same package has already been installed on the host server there will be files that will make the jail ports tree think that the package has already been installed within the jail as well. The clean keyword during the make process takes care of this misconception by the build system.

Remember to follow this piece of advice when installing any ports.

Okay we're done with prepping the jail system. Let's jump back to the host server. Simply type exit at the jail command prompt and that will take you back to the host.

Repeat all the above jail steps to setup another jail (e.g. web.dev.02.adamovsky.com).

Setting Up HAProxy

Here is where the magic happens. We need to setup a proxy on the host server that will act as the load balancer for all our jails.

fetch http://haproxy.1wt.eu/download/1.4/src/haproxy-1.4.2.tar.gz
   tar -xvzpf haproxy-1.4.2.tar.gz
   make -f Makefile.bsd REGEX=pcre DEBUG= COPTS.generic="-Os -fomit-frame-pointer";
   gmake install

Okay so I'm making a leap of faith. The setup that I did used haproxy 1.3.22, but I'm sure it will work with a more recent version as well. If not, feel free to download an older version of haproxy to get the gist of it and make any needed adjustments to make it work under 1.4.x or the latest version.

That was pretty easy. Next let's configure the proxy.

Configure HAProxy

The configuration of the proxy happens in the file at /usr/local/etc/haproxy/haproxy.conf in my example, but you can adjust it to reflect your location of the file.

Here is a copy of how the haproxy.conf file would look for our example, assuming two jail nodes, and that your external/outside facing IP address of the host server is 222.222.222.222 (obviously tweak this to reflect your true IP address).

global
        log 127.0.0.1   local0
        log 127.0.0.1   local1 notice
        daemon

  defaults
        log     global
        mode    http
        option  httplog
        option  dontlognull
        option redispatch
        retries 3
        maxconn 2000
        contimeout      5000
        clitimeout      50000
        srvtimeout      120000

  frontend web_proxy
        bind 222.222.222.222:80
        acl is_web_dev hdr_beg(host) -i web.dev
        use_backend web_dev_cluster if is_web_dev

  backend web_dev_cluster
        option httpchk
        option httplog
        option httpclose
        option forwardfor
        balance roundrobin
        server web.dev.01 10.2.2.10:80
        server web.dev.02 10.2.2.11:80

I'm not going into detail as to what does what as it would become too involved. What you need to do however is understand the basics of how to configure HAProxy. Comment on this post if you are interested in having me break this down in a separate article.

Once the changes have been made to the haproxy.conf file we need to completely stop the HAProxy daemon and then start it back up. A regular kill -HUP will not do. We need to kill -9 the process and start it back up.

If this is a first install, to start the haproxy all we need to do is call it.

haproxy -f /usr/local/etc/haproxy/haproxy.conf -p /var/run/haproxy.pid

Make sure to add this line to /etc/rc.local as well to ensure proper start-up at boot-up of the host server.

echo "haproxy -f /usr/local/etc/haproxy/haproxy.conf \ 
   -p /var/run/haproxy.pid >> /etc/rc.local

Great, now we're done with the TCP proxy. Next we will need to setup a DNS proxy which happens to be a UDP proxy - something that HAProxy is not suitable for.

Setting Up DNSProxy

The other port that is important in this setup is dnsproxy. This is a UDP based proxy server specifically developed for DNS proxying. We will want to use this under the assumption that we are running a DNS service within a jail node. It would be best to follow the above jail setup steps to setup a new jail for DNS only called dns.prod.01.adamovsky.com following the convention of our examples. Adjust the name to your liking.

cd /usr/ports/dns/dnsproxy 
   make clean install

This should be a relatively simple setup. Make sure to run this on your host server and NOT within a jail since it is the host server that is the acting proxy for all services.

Configure DNSProxy

The configuration file for DNSProxy is /usr/local/etc/dnsproxy/dnsproxy.conf - open it up and edit it to look something like this:

#
# dnsproxy 1.15 configuration file example
#

#
# Authoritative server
#
authoritative           10.2.2.12       # Internal IP of DNS jail
authoritative-port      53              # It's port. Defaults to 53.
authoritative-timeout   10              # Seconds to wait for answers.

#
# Recursive resolver
#
recursive               10.2.2.12       # Internal IP of DNS jail
recursive-port          53              # It's port. Defaults to 53.
recursive-timeout       90              # Seconds to wait for answers.

#
# Local address and port of dnsproxy
#
listen 222.222.222.222
port 53

#
# Security features
#
#chroot /var/empty
user nobody

#
# Internal networks (allowed to do recursive queries)
#
internal 10.2.2.12
internal 127.0.0.1

Here we assume that a jail for DNS was setup on the IP address 10.2.2.12. However if you choose to run a DNS service within another jail simply use the IP address of that jail. I prefer to segregate my services into individual jails.

Configure Boot-Up

Next we need to make sure that DNSProxy is started up automatically when the server reboots.

In /etc/rc.conf add the line

dnsproxy_enable="YES"

After everything is done fire it up.

/usr/local/sbin/dnsproxy -c /usr/local/etc/dnsproxy/dnsproxy.conf -d

Checking Setup

At this point you have a basic understanding for what is needed to setup FreeBSD to act as a cloud environment. Consider this a framework for whatever you want it to do. Feel free to comment any improvements, additions, or changes you've made with your setup.

Let's run through a checklist to make sure we've done everything:

Configured and started network on host
Setup jails
- web.dev.01.adamovsky.com
- web.dev.02.adamovsky.com
Started jails
- Started Apache** inside all jails
- Started BIND** inside all jails
Started HAProxy
Started DNSProxy

** = This assumes you are using the most popular software packages for a given service, but you can run whatever software package you want as long as it listens on the configure ports.

jQuery a-tools plugin insertAtCaretPos() bug solution

2010-03-20T17:22:00.000-07:00

Andrey Kramarev is the author of the excellent jQuery plugin called a-tools that allows advanced text selection manipulation of HTML form elements.

After having reported a bug that he resolved rapidly in his new version (a-tools 1.3.1), there is another bug that I found in Internet Explorer (tested in IE7 and IE8) that I feel deserves an article as it is easily circumventable and you may find yourself stuck in a deployment environment where upgrading is not a simple option. Knowing Andrey, he will undoubtedly have a fix by the time this article reaches you.

Before proceeding, check the repository to see if a newer version than 1.3.1 is out, and if you have the freedom to upgrade, do so. Otherwise, if your code is constrained by having to continue using 1.3.1, read below.

Problem

The problem lies in the insertAtCaretPos() function when used on a <textarea> HTML element.

The way to duplicate the problem is to try to insert something into a textarea element that hasn't gotten focus, doesn't have any content in it, and make sure to use Internet Explorer as a browser. You can test this using the official demo page at http://www.ampparit.com/projects/a-tools/demo.html if you don't want to create your own test page.

Demo Page

If you do choose to use the official demo page, simply try to enter text into the input field next to the Input following text to the caret position and click the button. Your content should appear at the very top of the document to the left of the page title.

Pressing the button continuously will result in every other click to insert the text at the top of the page, and every click in between into the correct input field. Weird, isn't it?

Solution

The cause of the problem appears to be some sort of incorrect caret positioning handling. Knowing this, the solution will become a little clearer to understand.

Before we begin hacking away, it's worth mentioning that luckily the hack is cross-browser compatible and will not interfere with browsers who handle a-tools properly, such as FireFox.

Intended Code

Normally if we wanted to insert the letter a into a textarea HTML element using this jQuery plugin, the code would look something like this:

$('textarea').insertAtCaretPos('a');

As we can see, a one-liner.

Hacked Code

We will need to add some caret manipulation code to help a-tools staying synchronized with the caret's position.

     var element = $('textarea'),
         caretPos = element.getSelection().start,
         isTextarea = element.is('textarea');

     if (isTextarea && caretPos == 0 && element.val().length == 0)
      {
       element.setCaretPos(2);
      }

     element.insertAtCaretPos('a');

     if (isTextarea)
      {
       caretPos = element.getSelection().start;
       element.setCaretPos(caretPos + 1);
      }

I used the isTextarea variable to make it clear what code is needed only for textarea elements. Make sure to put a conditional around it if your form consists of different HTML form elements as this solution will mess up the normal functionality of non-textarea elements.

Explanantion

Let's take a minute to understand the logic behind this code.

First we need to figure out if the textarea that we're dealing with is empty. This is necessary as the bug doesn't show up on elements who are no longer empty.

     ...

     if (isTextarea && caretPos == 0 && element.val().length == 0)
      {
       element.setCaretPos(2);
      }

     ...

If this proves to be an empty textarea, we need to tell a-tools to set its internal caret position to 2.

The reason for this magical number is that zero doesn't work probably because the official a-tools documentation states 1 as being the beginning of the field, and 1 not working as far as resetting the internal caret position. So we increase it to 2; somewhat crude of a method but it works.

     ...

     if (isTextarea && caretPos == 0 && element.val().length == 0)
      {
       element.setCaretPos(2);
      }

     ...

Internally we have now instructed a-tools to focus on the textarea and not target the main document. This fixes that weird behavior of having the content inserted at the top of the document on every other click rather than inside the input field.

Next we call the normal insertAtCaretPos() and since we have told a-tools to focus on the textarea at caret position 2 (which doesn't exist since the textarea is empty), it will do the next best thing and put it at the beginning of the textarea. Urgh, what a hack!

The hack is not over though. Next we need to still help a-tools out.

     ...

     if (isTextarea)
      {
       caretPos = element.getSelection().start;
       element.setCaretPos(caretPos + 1);
      }

The above code only applies for textarea elements, so we want to have a conditional around it.

What we do next is get the current caret position after the text has been inserted, and force the internals of a-tools to increment it by one. This will ensure that next time we call a-tools it doesn't lose track of its caret position to prevent it from trying to insert the text at the top of the document on every other attempt.

I haven't tried it, but if you will insert a longer string than just a character, you may have to account for the length when resetting the caret. The code might then look as such:

     ...

     element.insertAtCaretPos(insertedString);

     if (isTextarea)
      {
       caretPos = element.getSelection().start;
       element.setCaretPos(caretPos + insertedString.length);
      }

Follow this solution and you can get away with continue using a-tools 1.3.1 at the cost of a slightly bigger code.

Hand tool stuck in Photoshop CS4

2010-03-11T06:02:00.000-08:00

Recently I was working with Photoshop where all of a sudden the hand tool was the only tool available to me. It was almost as if I was in a modal state disallowing me any operations.

Troubleshooting

The way I went about finding a solution to this problem was to check that I didn't have any special keys stuck on my keyboard that could alter the behavior of Photoshop. Nope, all clear. No shifts, no alts, no stuck function keys, etc.

Next I tried to identify any menu items that were checked that I did not intend to have checked. Everything seemed to be set normally.

Finally I did a quick Google search and found the solution.

Solution

Follow these simple steps:

Enter the Edit menu
Select Preferences
Select General
Click the Reset All Warning Dialogs

Problem solved.

NFS Input/Output Error in FreeBSD

2010-03-05T21:04:00.000-08:00

I had recently experienced some of NFS shares no longer available. Trying to access them yielded an Input/Output Error with no errors logged on either the client or server side.

This article will quickly explain how I went about debugging and fixing it.

Troubleshooting

The first thing I did was check if the shares were listed. This can be achieved with a simple df command. The chances are your problematic NFS shares will not show up when running df.

At first you may think that the NFS client cannot mount the NFS shares. This is incorrect. The shares are mounted, since you can access them (except it will yield the Input/Output Error) and it can be umounted. That's right, the NFS shares are mounted, just inaccessible.

The next step is to check the /var/log/messages log file on both the NFS client and server machines. These will most likely be of little help. If there are some helpful error messages, follow those as you may be experiencing a different problem with identical symptoms.

The last step to ensure that the NFS is working properly and the shares are mounted, try to unmount them! This can be done with the command umount /mounts/nfs/share (where /mounts/nfs/share is replace with your actual NFS share). You can then try to run the command once more and it should tell you the NFS share cannot be unmount since it's not mounted. In other words, it was unmounted successfully the first time aaaaand it also means that it was mounted to begin with.

At this point we have done our due diligence in gathering as much superficial information as we can to assess the state of the problem. Let's try to solve it now.

Solution

The solution is pretty simple, and the reason for this article is as much the solution as giving you an insight how to go about debugging NFS issues that may not log any helpful details via syslog or other logging mechanisms.

Connect to the NFS server machine (the server that runs nfsd) and find the process ID (pid) of the service mountd and kill -HUP that process. In other words simply restart the mountd process.

This will automagically solve the problem, with no need to remount any of the problematic NFS shares since they were all mounted - just inaccessible.

One Space Indentation

2010-02-27T19:33:00.000-08:00

There is always someone on every team that is rigid in their ways, lacks the skill to adapt, or is purely stubbornly set in their ways. This article is not for such people. This article is for Enterprise level developers.

Here I want to talk about indentation in coding, and how over the course of 15 years of development on both front-end and back-end systems I have determined the most effective way to indent my code. That conclusion is that one space is all you need.

Research

Whenever I introduce new concepts or ideas I like to do my due research. I was recently challenged by a fellow web developer on my indent style, with no research on his part. While I encourage debates, discussions, and questions - I do not respect unfounded statements where the individual has not done their due research before wasting everybody's time.

There are many good books covering code styles, and without going into a library and reading all these PhD authored books that are based on good research, I do encourage a basic Google search or at the very least referencing Wikipedia's Indent Style article.

My indent style follows closest the GNU style (see Wikipedia).

Tabs Are For Beginners

Many developers when starting out learn programming reading great books where code samples are illustrated to be clear for beginners. Much attention is given to the programming aspect of such books, with formatting being addressed only in the beginning - but they never evolve the formatting throughout the pages causing for the reader to blindly accept such formatting and develop a complacent mindset in that regards.

Needless to say many books use tabs to clearly illustrate indentation. This is, in my opinion, a highly exaggerated display of indentation just like teachers would use exaggerated letter sizes when teaching the alphabet. In other words, tabs are nothing more than a learning tool, training wheels, something one has to evolve away from as one gets more sophisticated.

Four spaces are tabs

Read above.

Two Spaces Are Good

They are half as wasteful as tabs or four spaces, so this is a good start.

The only place I feel that two spaces are needed is in HTML code as keeping it down to one space would lose the indentation due to the opening character of each indent, which happens to be the less than sign - or "<".

<html>
 <head>
  <title>

Using the Courier New font we can see the indentation somewhat, but with other fonts it seems to give off a visual diagonal line when connecting the lesser than signs. Adding two spaces cleans this up.

<html>
   <head>
      <title>

This only applies to HTML due to the aforementioned reason. Any brace-enabled language such as CSS, JavaScript, C, Perl, PHP, etc... only need one space indentation to remain clear. This is where the whining should stop (e.g. but I'm used to), and the will to evolve your style - not just your skill. This of course does not apply to you if you are a beginner or intermediate developer, but if you consider yourself at least a senior developer that's another story.

To be clear, even as little as two spaces are excessive, and should not be used in advanced code.

One Space Indentation

Pat yourself on the back if you're still with me for you have my respects. Here we will explore how to code like a pro.

Let's begin with a piece of code where we see how one space indentation looks like. Keep in mind that this requires training your eye, and some practice. Since when can you get good at something without practice anyway? Here is something that applies to just about everything in life: If you don't practice, you can't be that good. If I've lost you, you can still train your eye here.

if (milan == true)
  {
   while (coding)
    {
     i++;
    }
  }
 else
  {
   goto school;
  }

As we can see by combining proper alignment of braces (each on its own line) and one spaces, we effectively kill two birds with one stone:

Blocks are clearly identified by aligning opening and closing braces
Indirectly we achieve two space indentation between levels

Okay so the goto statement is bad programming, and is more geek humor in context of the code sample (e.g. if I disagree with Milan, then I may as well use other bad practices such as goto).

Now let's take that same code sample with the other indent styles.

if (milan == true) {
     while (coding) {
         i++;
     }
 }
 else {
     goto school;
 }

There you have the four space and tabs. Luckily this is a small piece of code with only two indentations - imagine a real-life example where we have multiple level depths.

if (milan == true)
   {
     while (coding)
       {
          i++;
       }
   }
 else
   {
      goto school;
   }

I used GNU style formatting for the above sample. The code looks a little disconnected to me, and still a little more in line with baby mode. Either way, this is just to show why I do not like anything more than one space.

Benefits

The benefits of keeping to the One Space Indent style as an enterprise level developer include:

Less horizontal white space
Clear indentation with proper curly bracket alignment
More code on screen without need of scrolling
Tighter visual relationship display
Stay focused on code and not scrolling back and forth
Displays on all editors with no special configurations!

Real-life Examples

While there are many cases where custom tabs may not be defined, I will collect some real-life examples that illustrate where spaces will work and tabs will fail.

Web Inspector
This is the web development debugger used for Webkit browsers. When using its built-in editor, any long lines will be auto-wrapped, not to mention tabs are displayed as tabs - with no customized view possible. Combining these two effectively guaranteed really messy debugging.
FireBug Script Debugger
This is the web development debugger used for FireBug browsers. When using its built-in editor tabs are displayed as tabs - with no customized view possible.
WordPress
Okay, so this actually encompasses most web platforms. Most of the time if you are a web developer you will not use a WYSIWYG editor - if such is offered by an online platform.

If you have any examples of where spaces work and tabs don't, feel free to comment. Likewise, if you are a tab believer, comment on when tabs will work and spaces won't display correctly.

Readings

I just had a friendly debate on this topic with a fellow web developer where he happens to be a tabber (as opposed to me being a spacer), so he had recommended this read before he had read it to its full completion. Knowing this, read the full article for a good laugh. http://www.codinghorror.com/blog/2009/04/death-to-the-space-infidels.html.

Conclusion

Every developer will get used to one style or another, and there is no functional reason to use one over the other. This is purely a personal choice that a developer who wants to evolve every aspect of him or herself and not only their technical side has to make. After all, technical know-how is only one part to being a successfully well-rounded web developer.

jQuery Plugin Pattern 2.0

2010-02-26T22:50:00.000-08:00

Time to review the pattern and start from scratch. You will see that this is a more elegant solution with all kinks ironed out.

Criteria

I still want to have a pattern that allows me to write plugins that meet these criteria:

that maintain only one entry in jQuery's namespace
that allow secondary methods
access to selector
access to $(this) through secondary methods

Research

I do encourage everyone to read the official jQuery plug-in authoring tutorial. This is pretty simple and straight forward, and in this article I will refer to it as the "normal method".

Another great read is Mike Alsup's plugin development pattern. His tutorial is closer to what my pattern tackles.

Goal

Solution

First I want to begin with giving a complete example of how a very basic plugin is developed using my proposed pattern so you know what you'll be dealing with.

Behold... the new plugin pattern!

(function($)
  {
   $.fn.extend({ 
                _plugin: null, 
                jQueryInit: jQuery.fn.init 
               });
    
   $.fn.extend({
                init: function( selector, context ) 
                       {
                        return jQuery.fn._plugin = new jQuery.fn.jQueryInit(selector, context);
                       }
               });
    
   function MyPluginClass(args)
    {
     
     var _config;
     
     this.version = '1.0';
    
     this.show = _(showMessage);
     
     initConfig(args);

     function getConfig()
      {
       return _config;
      }

     function setConfig(args)
      {
       _config = args;
      }

     function initConfig(args)
      { 
       setConfig($.extend({
                           chainable : true,
                           className : 'MyPluginClass'
                          }, args));
       return (this);
      }

     function showMessage(args)
      {  
       var myDiv = $(this);
           
       var config = getConfig();

       alert('My Plugin is ' + config.className);
              
       return (this);
      }
   

     function _ (fn) 
      {
       return function (args)
               {
                return this.prototype.rc(function () 
                                          { 
                                           fn.call(this, args) 
                                          }); 
               }
      }
      
     this.rc = function (args)
      {
       if (typeof args == 'function')
        {
         return $.fn._plugin.each(args);
        }
       else
        {
         initConfig(args);
         
         return getConfig().chainable
                 ? $.fn._plugin
                 : $.fn.createBox;
        }
      };
       
     
     }

     var _p = new MyPluginClass({});
     
     $.fn.pluginName = _p.rc;
     $.extend($.fn.pluginName.prototype,_p);
     $.extend($.fn.pluginName,_p);
     
    })(jQuery);

Usage

Before we break down the pattern I want to show why we go through this process and how cool your plugins will become.

This pattern is fully backwards compatible to jQuery's suggested use. This means you can still use the traditional form of calling your plugin (if you want) as shown below.

$(selector).pluginName(args);

So we got backwards compatibility covered. But where is the magic?

The official jQuery pattern promotes the use of plugins are stand-alone widgets more or less that can be customized by way of tweaking various publicly exposed options. This is where my pattern diverges.

$(selector).pluginName(args);
$(selector).pluginName(args).method();
$(selector).pluginName.method()
$(selector).pluginName.object.method()
$(selector).pluginName.object.method(args)

All of the above are valid syntax when coded using this pattern, and yes, it's still chainable as long as you adhere to jQuery's plugin conventions to make it chainable. Sweet!

Okay gotta run off to little Italy, will continue this later...

Remove if() statements in JavaScript

2010-02-09T10:34:00.000-08:00

Most of the time if() statements make our lives easier. It clearly depicts our intended logic flow.

Here I want to show a piece of code re-factored so that we eliminate the if() statement. After a few benchmarks however, it apparently ends up being more costly to not use if() statements! So keep that in mind...

Let's illustrate this by way of example. This will give you the idea that you can then take a run with when writing your own code.

Original Code

Here I am spelling out the code as would be written by a junior developer, or someone extremely explicit.

function someFunction(args)
  {
   var myCallback;

   if (args)
    {
     if (typeof args.callback != 'undefined')
      {
       myCallback = args.callback;
      }
     else
      {
       myCallback = function() {};
      }
     myCallback();
    }
  }

First Re-factor

Next we will re-factor the code to an intermediate developer's level.

function someFunction(args)
  {
   var myCallback;

   if (args)
    {
     myCallback = (typeof args.callback != 'undefined')
                   ? args.callback
                   : function() {};
     myCallback();
    }
  }

Great, we removed one if().

Second Re-factor

We still have an if() statement so we will try to be a little more creative and re-factor it a little more.

function someFunction(args)
  {
   var myCallback;
   myCallback = (args && typeof args.callback != 'undefined')
                 ? args.callback
                 : function() {};
   myCallback();
  }

Now we no longer have an if() statement but we do still have a ternary operator. We can get rid of that one too!

Third Re-factor

Let's step up our game to a senior level.

function someFunction(args)
  {
   var myCallback = args && args.callback || function() {};
   myCallback();
  }

Wow! No if() or ternary operator. Is there something more we can do? Yes.

Fourth Re-factor

Now we're pushing ourselves and going for guru level.

function someFunction(args)
  {
   (args && args.callback || function() {})();
  }

Amazing! We were able to remove:

Two if() statements
Variable declaration
Memory allocation

Okay so I wouldn't recommend the last re-factor in an enterprise environment where code should be maintainable and where different skill levels are collaborating. I do however encourage this type of code in core functions that will usually only be maintained by senior developers, and where performance and small footprint is the objective.

Explanation

A quick explanation of what is happening is that you check if args exists, and if it does, then you want to get the value of one of its properties (e.g. args.callback). These can both be anything you want it to be, the above is just an example. If the property args.callback doesn't contain anything, we want to assign an empty anonymous function. This way when we call it, the JavaScript doesn't crash on us. Now that we have ensured we will have a function (well, we could be more specific by adding a typeof checking for a function into the &&, but let's not over-complicate things), we are ready to execute it. To execute the function all we have to do is wrap it with parenthesis, append another pair of parenthesis, and that will do it. If this spelled out version does not clarify what the code is doing, just look at the very first version of the code as they do the same thing.

Try it!

Here is some code for you to try...

<script>
 function someFunction(args)
  {
   (args && args.callback || function() { alert('Bye!') })();
  }
 someFunction({ callback : function() { alert('Hi') } });
 someFunction();
</script>

This code will hopefully get the average JavaScript developer to think outside the box, and expand their arsenal to different ways of thinking. I'm not saying this is a solution for every situation, I'm not saying it's never a solution, I'm just saying that it is a solution.

Hope you enjoyed this little exercise.

Advanced jQuery Plugin Authoring Pattern

2010-02-07T08:36:00.000-08:00

When writing a jQuery plugin it can feel like a daunting task. In this article I will give you a template that I've created for my plugins, that you can follow when creating yours. This is my way of doing it; use it as a pattern or a tutorial.

Update: I've perfected a new jQuery Plugin Pattern 2.0 that should be used instead of the one on this page.

Research

I do encourage everyone to read the official jQuery plug-in authoring tutorial. This is pretty simple and straight forward, and in this article I will refer to it as the "normal method".

Another great read is Mike Alsup's plugin development pattern. His tutorial is closer to what my pattern tackles.

The next natural step is to look at other jQuery plugins to see how others have implemented their plugins.

Last but not least, continue reading this article.

Goal

The biggest shortcoming of the jQuery plugin authoring method is that the plugins are not designed to have methods but rather have options to interact. This is to allow chaining, so methods would essentially become other plugins.

This brings us to the next shortcoming: even if we use the "normal" method, it does not account for method conflicts of various plugins since there is no namespace. This means that if two plugins have a method called getInfo, one of them will be overwritten.

Finally, one of the other big shortcomings is that jQuery does not let you know which selector was acted on (the .selector introduced in jQuery 1.3 does not do the job in the same way as needed here).

Okay, one more: within a method it is not possible to get the selected element as you would normally with this using the normal method. This one won't make sense until we understand why we need it, and that will become obvious when we tie everything together.

Rules

There are a few rules that I have come up with that make it very simple to keep my plugins consistent:

Keep all objects, variables, functions declared alphabetically
No globals (outside of plugin definition)
Minimize "globals" within the plugin definition
Define plugin methods as hash
Declare all local functions underneath plugin hash
Provide a config() method to pass all options
Use camelCase

I highly advise these rules to be followed when using this method.

Template

Here is a blank template for a plug-in. Read it over a few times, and then we'll break it apart.

(function($) 
   {
    var config = {}; 

    var global = {
                  selected : '',
                  selector : ''
                 };

    var init = $.prototype.init; 
  
    $.prototype.init = function(selector, context) 
     {
      var r = init.apply(this, arguments);
   
      if (selector && selector.selector)
        r.context = selector.context, r.selector = selector.selector;
    
      if ( typeof selector == 'string' )
       {
        r.context = context || document, r.selector = selector;
        global.selector = r.selector;
       }
  
      global.selected = r;   
  
      return r;
     };

    $.prototype.init.prototype = $.prototype;

    $.fn.pluginName = {
                       config : function(args) 
                        {
                         setConfig($.extend({
                                            'default' : 'value'
                                            }, args));
         
                         return (getConfig());
                        },
                       methodA : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        },
                       methodB : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        }
                      };
  
    function setConfig(value)
     {
      config = value;
     }
  
    function getConfig()
     {
      return config;
     }
   })(jQuery);

That was fun, wasn't it?

Step 1: Encapsulate

The first thing we need to do is to "encapsulate" the whole plug-in definition. This means wrapping it into a self-executing function block.

(function($) 
   {
    [code]
   })(jQuery);

Nothing new here.

Step 2: Globals

In this context we declare globals within the plug-in's encapsulation. This means these variables will only be available to the plug-in and not to the real global namespace - so do not worry too much about global namespace cluttering, but do apply the same wisdom when deciding what to put into the localized global namespace, as you would in a true global namespace. Remember that as far as the plug-in is concerned, the encapsulated namespace is the global namespace. So the question becomes: what do we put in this namespace?

Options variable
Global jQuery selector information
Local methods

Not too bad.

Step 3: Options

It will become a problem to have access to the options that are passed in to the plug-in, once we introduce a namespace. Knowing this we need to accommodate this by way of globalizing the passed-in options.

(function($) 
   {
    var config = {}; 
    [code]
   })(jQuery);

While these are accessible directly since they are global in the plug-in namespace, I highly discourage this, and introduce a getter and setter function.

function setConfig(value)
     {
      config = value;
     }
  
    function getConfig()
     {
      return config;
     }

At this point they are just dummy functions, but the point is that one could easily add intelligence to this down the road. Basic getter/setter 101 concept. Stick with it, even if you don't think you'll need it.

Step 4: Selector Information

The next global is the meaty part of how I write plug-ins. Unfortunately, as of jQuery 1.4.1 we still have no way of getting the element that was selected, and we have no true way of knowing what selector was used. Let's illustrate this with an example.

$('input').pluginName();

Using the above, the input would be the selector; the $('input') would return the object of the selected element. This is how jQuery works, and it's wonderful. Inside the pluginName definition we can get to the selected element object by using $(this). The problem is that it's restricted only to the first level functions. This means, as long we use the above construct to call the plug-in we won't have a problem. The problem with that construct however is that it doesn't isolate itself into a namespace. The new construct should be:

$('input').pluginName.someMethod();

If we now try to use $(this) inside the someMethod(), it will not give us the selected element object - let alone the selector. This is what we will be overcoming, and to prepare for this we will need to maintain a global data structure that will hold on to this information.

var global = {
                  selected : '',
                  selector : ''
                 };

These will later be accessible by simply calling global.selected to get the selected element object, or global.selector to get the selector that was used to get to the selected element object. If this doesn't make sense at this point, simply do it and it will all fall into place.

Step 5: Overwrite jQuery's init

After having hacked away at jQuery's 1.2.x source code to figure out a way to get to the selector, I found an elegant piece of code by Brandon Aaron somewhere online that I borrowed and enhanced for my purposes.

var init = $.prototype.init; 
  
    $.prototype.init = function(selector, context) 
     {
      var r = init.apply(this, arguments);
   
      if (selector && selector.selector)
        r.context = selector.context, r.selector = selector.selector;
    
      if ( typeof selector == 'string' )
       {
        r.context = context || document, r.selector = selector;
        global.selector = r.selector;
       }
  
      global.selected = r;   
  
      return r;
     };

    $.prototype.init.prototype = $.prototype;

The gist of the code is that it overwrites jQuery's init() function that is responsible for intercepting the selector used, and find the selected element object. If the above doesn't make sense to you, just copy and paste and trust me. The above will populate the global data structure.

Step 6: Namespace

This is another meaty part of my way to author plug-ins: simulating a namespace.

$.fn.pluginName = {
                       config : function(args) 
                        {
                         setConfig($.extend({
                                            'default' : 'value'
                                            }, args));
         
                         return (getConfig());
                        },
                       methodA : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        },
                       methodB : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        }
                      };

Unlike the "normal" method of writing plug-ins, here we declare our plug-in as a hash. This is great since it will let us call our plug-ins with a cleaner syntax.

$('input').pluginName.methodA();
 $('input').pluginName.methodB();

We effectively tell everyone that our methods belong to pluginName - even if such methods exist for another pluginName. I would leave the config method as-is, to be the method to use to send options to your plug-in. This will provide a uniform convention for all jQuery plug-in authors using my way, and automatically know not to chain on it (since it's purposely designed not to chain).

Step 7: Methods

The last step is to define the public methods. This is easily done by simply adding another item to the plug-in hash.

$.fn.pluginName = {
                       config : function(args) 
                        {
                         setConfig($.extend({
                                            'default' : 'value'
                                            }, args));
         
                         return (getConfig());
                        },
                       methodA : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        },
                       methodB : function()
                        {
                         var config = getConfig();
  
                         return (global.selected);
                        }
                      };

Here we add two methods: methodA and methodB. You can add as many methods this way as you want. You can even simply do references as I like to do to keep it clean.

(function($) 
   {
    [code]

    $.fn.pluginName = {
                       config : function(args) 
                        {
                         setConfig($.extend({
                                            'default' : 'value'
                                            }, args));
         
                         return (getConfig());
                        },
                       methodA : someMethodReferenceA,
                       methodB : someMethodReferenceB
                      };

    function someMethodReferenceA()
     {
      [code]
     }

    function someMethodReferenceB()
     {
      [code]
     }

    [code]

   })(jQuery);

The two things to remember when writing your methods is to first retrieve all the configs available to you via getConfig(), and to return the jQuery object for chainability as shown above. We can now see where the global.selected is needed now since returning $(this) at this point would not return the jQuery object.

Aliases

A little bonus to using the above method is that it is very easy to create aliased method names. One would usually want that for developers who are more keen to using certain terminology over the one you may prefer. An example would be where one may want to have a removeItem method (most likely a UNIX or Mac person), whereas the rest of the world may want a deleteItem method (most likely a Windows user).

(function($) 
   {
    [code]

    $.fn.pluginName = {
                       config : function(args) 
                        {
                         setConfig($.extend({
                                            'default' : 'value'
                                            }, args));
         
                         return (getConfig());
                        },
                       removeItem : someMethodReferenceA
                      };

    [code]

    $.fn.pluginName['deleteItem'] = $.fn.pluginName.removeItem;
    $.fn.pluginName['eraseItem'] = $.fn.pluginName.removeItem;

   })(jQuery);

Clean.

That's all there is to it. Once you get used to this way, you will never go back.

GraphicsMagick on FreeBSD

2010-02-02T06:15:00.000-08:00

Recently I've been wanting to install the latest GraphicsMagick 1.3.8 on a FreeBSD 8.0 server, with little success doing so manually - somewhat.

Update: This solution still works with GraphicsMagick 1.3.12.

I want GraphicsMagick to be enabled for the JPEG format but using the --with-jpeg has no effect even though the JPEG libraries are installed. The error that I get is this:

/usr/bin/gm convert: No decode delegate for this image format

This essentially means that the JPEG "decoder", or library, was not found. Urgh. Well, I did see that it didn't compile properly during the configure process, but I thought it might just be a wrongful statement. No such luck.

What are we left to do? Ports.

So the next thing we can do is install GraphicsMagick from FreeBSD's ports collection. This is located in /usr/ports/graphics/GraphicsMagick13. There are other GraphicsMagick folders but we want this version.

cd /usr/ports/graphics/GraphicsMagick13
 make install

Compilation issues

This ports is extremely picky about what libraries are on the server. As you run make you will undoubtedly run into compilation errors. Some of the errors will state that you don't have libtool installed, others will state you already have autoconf installed and fail (this one didn't make sense to me).

The solution is pretty simple and logical though: Remedy all issues.

Missing libtool

This means if it says libtool is not found, go to the ports (now I say ports because all ports are usually compiled with the ports sources in mind so you will have greater luck with it), and install it. Then try again.

It may be necessary to take this step to succeed at building GraphicsMagick from ports. If this is the case you need to simply do the following steps:

cd /usr/ports/devel/libtool22
 make install

If you do not have libtool22 in your ports simply look for the latest libtool version (the 22 in the above example represents the version number).

Autoconf exists

The other error I encountered was that autoconf already exists on the system so it failed to continue. Where is the logic in that? So we fight lack of logic with lack of logic: uninstall autoconf and let GraphicsMagick do its thing.

We all know uninstalling binaries on UNIX is not easily accomplished if you haven't installed it through a system that lets you uninstall. If you are like me and you have installed autoconf manually (via tarball), to uninstall it as far as GraphicsMagick is concerned all you need to do is remove the binary.

rm /usr/local/sbin/autoconf

The path may differ from system to system depending on how you installed it. Adjust the path accordingly.

Once all compilation issues have been remedied, try to make the ports of GraphicsMagick again until you succeed.

Magic

This is where the true magic happens to get the latest GraphicsMagick to install.

Now that FreeBSD took care of installing all the libraries, patches, and all the other files needed to get GraphicsMagick to compile, we can go back to GraphicsMagick's website, download the latest tarball, and install it. It will work since all the prerequisite files are properly installed on the server thanks to the ports.

Voila.

Conditional DOCTYPE

2010-01-30T12:44:00.000-08:00

I recently needed to switch the DOCTYPE of a page according to what browser was used. If IE6 is used I want the page to render in quirks mode, conversely if the page is any other browser such as Firefox I want the page to render in HTML strict DOCTYPE.

Problem

The problem is that there is no such thing as a conditional DOCTYPE. You cannot fool it with JavaScript (and even if you could, you would not want to).

Solution

The solution is quite simple, clean, and elegant.

In IE6 anything that comes before the DOCTYPE declaration will automatically cause IE6 to jump into quirks mode. This means even if you specify a HTML strict DOCTYPE on the page, as long as there is something before it, it will be discarded.

Are you with me so far?

This is good news. This means that all we need to do is start the page with a comment that will be ignored by all browsers, with the extra benefit of disabling the DOCTYPE in IE6.

<!-- DOCTYPE disabler for IE6 -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

We have effectively created a conditional DOCTYPE, and it can be read as "if we use IE6 put it in quirks mode, if any other browser is used such as Firefox then use the strict DOCTYPE."

Moving on.

Compile Locale::gettext on FreeBSD with Perl 5.10

2010-01-26T11:11:00.000-08:00

On FreeBSD when you try to compile the Locale::gettext using Perl 5.10.1 you may get an error message that says:

gettext function not found. Please install libintl at Makefile.PL line 18.

So my solution is pretty simple:

CC='cc -L/usr/local/lib -I/usr/local/include' perl Makefile.PL

Tada!

My logic is we piggy back off of the environment variable that is already built-in into the Makefile.pl and have it go for the compiler, but also inject the various paths (since apparently it's having trouble finding the libintl library on its own).

With this method you will be able to compile successfully.

Before

prompt> perl Makefile.PL
checking for gettext... no
checking for gettext in -lintl... no
gettext function not found. Please install libintl at Makefile.PL line 18.

After

prompt> CC='cc -L/usr/local/lib -I/usr/local/include' perl Makefile.PL
checking for gettext... no
checking for gettext in -lintl... yes
checking for dgettext in -lintl... yes
checking for ngettext in -lintl... yes
checking for bind_textdomain_codeset in -lintl... yes
Writing Makefile for Locale::gettext

prompt> make
cp gettext.pm blib/lib/Locale/gettext.pm
/usr/bin/perl /usr/local/lib/perl5/5.10.1/ExtUtils/xsubpp -typemap /usr/local/lib/perl5/5.10.1/ExtUtils/typemap gec
Please specify prototyping behavior for gettext.xs (see perlxs manual)
cc -c -DHAS_FPSETMASK -DHAS_FLOATINGPOINT_H -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -O c
Running Mkbootstrap for Locale::gettext ()
chmod 644 gettext.bs
rm -f blib/arch/auto/Locale/gettext/gettext.so
LD_RUN_PATH="/usr/local/lib" cc -shared -L/usr/local/lib -fstack-protector gettext.o -o blib/arch/auto/Locale/get
chmod 755 blib/arch/auto/Locale/gettext/gettext.so
cp gettext.bs blib/arch/auto/Locale/gettext/gettext.bs
chmod 644 blib/arch/auto/Locale/gettext/gettext.bs
Manifying blib/man3/Locale::gettext.3

prompt> make install
Files found in blib/arch: installing files in blib/lib into architecture dependent library tree
Installing /usr/local/lib/perl5/site_perl/5.10.1/i386-freebsd/auto/Locale/gettext/gettext.so
Installing /usr/local/lib/perl5/site_perl/5.10.1/i386-freebsd/auto/Locale/gettext/gettext.bs
Installing /usr/local/lib/perl5/site_perl/5.10.1/i386-freebsd/Locale/gettext.pm
Installing /usr/local/man/man3/Locale::gettext.3
Appending installation info to /usr/local/lib/perl5/5.10.1/i386-freebsd/perllocal.pod

Hope this helps.

Dangers of document.write()

2009-10-29T06:16:00.000-07:00

Newcomers to JavaScript quickly learn that it is possible to write dynamic content onto the screen with document.write(). It gets the job done, it is easy to understand, and even easier to implement. This article will cover of why document.write() should be used sparingly if at all.

Pros

Before we cover the serious disadvantages, let's be fair and address the benefits.

Easy to understand
Quick to implement
Immediate rendering

The one time you may want to use this is when dynamically linking files into your page such as additional JavaScript libraries because of the immediate rendering. There you have them. If you are a serious developer, the next section will be more interesting.

Cons

I can count on one hand how many times I've used used document.write(), and I definitely have never used it to display content on the screen (this is like using tables for layout). The disadvantages are best seen when trying to extend existing code. Nonetheless here they are:

Rigid implementation
Renders in-place
Cannot be manipulated

Alright so the list by itself doesn't help my case much; let's explore each point in greater detail.

Rigid Implementation

The document.write() is mostly used to write content to the screen as soon as that content is needed. This means it happens anywhere: in a JavaScript file or inside a script tag within an HTML file - with the script tag being placed anywhere within such an HTML file. The latter is a definite no-no, but alas it happens.

It is a bad idea to have document.write() statements inside script blocks that are intertwined with HTML inside a web page for several reasons:

Changing code requires modifying an HTML file (which is not in line with MVC)
We cannot re-use what is written to the screen since it is not modular. This means that if we want to do the same thing in some other file, we have to copy and paste the same code into that HTML file *shivers*
Since it renders in real-time it may render before other content is generated by another JavaScript that the logic responsible for the document.write() is in turn reliant on.

The above points are quite a mouthful, it is not surprising then that inexperienced developers do not know any better.

Renders In-Place

Well designed code in general will take any dynamically generated content, store it in memory, keep manipulating it as it passes through the code before it finally gets spit out to the screen. I've seen many times that the document.write() does all of this in one swoop: it concatenates logic.

So to reiterate the last point in the preceding section: Rendering content in-place may render faster than other content that may be relied upon, but it may not be available to the other code that in turn requires the content to be rendered for processing. A chicken and egg thing.

To solve this dilemma we need to get rid of the document.write() and implement it the right way.

We should have all content stored in memory. This in turn allows us to shuffle the content around, parse it, tweak it, and manipulate it any way we want, back and forth, as many times as we need. At this point nothing is on the screen, which gives us this flexibility. Once we are happy, and all code has had an opportunity to work with it, only (and only) then do we spit it out - in MVC parlance: to our view.

To display the content we could resort to document.write() but unless one knows exactly what once is doing this should not be the preferred way. Instead one should inject it into a DOM element by id or the like. Frameworks usually provide an easy way to accomplish this. In jQuery one would simply do a $('#id').html(content), and that's it.

Impossible Manipulation

As covered in the previous section one of the major drawbacks of document.write() is that once it's written it's done and over with. We cannot go back to manipulate it without tapping into the DOM - adding to the mess.

Conclusion

This is one of those functions in the world of web development that are deceivingly simple but should only be used by experienced developers - if at all.

Button line-height in FireFox

2009-10-19T10:22:00.000-07:00

In a recent project I had to create a stylized button in a form. This involved a sprite background with some superimposed text to achieve the desired look.

The text on the button had to be center-aligned vertically. This is usually accomplished by tweaking the line-height CSS property. Unfortunately, FireFox doesn't extend line-height onto the button element.

button {
   line-height : 20px
  }

The above CSS declaration will not process as intended in FireFox (as of this writing 3.5.3).

Luckily there is a quick work-around that is cross-browser compatible. It involves adding an element inside the button whose location coordinates we can then manipulate.

<style>
    button {
     line-height : 20px
    }
    button span {
     position: relative;
     top: -2px;
    }
  </style>

  <button>
    <span>
      Button Text
    </span>
  </button>

Above we use a span element, but anything can be used.

Browser Compatibility

I've tested this to work with IE6+ and FireFox 3+.

Cross-Browser Testing

2009-10-08T08:58:00.000-07:00

As a front-end developer the biggest challenge faced is ensuring cross-browser compatibility. Presently the browsers that are expected to be supported are:

Internet Explorer 6
Internet Explorer 7
Internet Explorer 8
FireFox 3
Safari

Other browsers with a smaller market share such as Chrome and Opera are nice-to-haves but are usually not required. The options available to web developers are numerous to ensure cross-browser compatibility. The most obvious is to actually install all browsers, or have several computers with the various browsers, but if you're like me and you want to use one computer to test all, here are some useful tools.

Useful Tools

Spoon is a nice browser plugin that allows a sandboxed version of various browsers. There are some complications running this in a corporate environment where firewalls, proxies, and the like are interfering. Worth a try.
Supports: IE6, IE7, IE8, FF2, FF3, FF3.5, Safari 3, Safari 4, iPhone, Chrome, Opera 9, Opera 10.
MultipleIEs is a nice installer that uses eVolt's standalone packages of older Internet Explorers. I use this only for the IE6 option. Works like a charm even in a corporate environment.
Supports: IE 3, IE 4.01, IE 5.01, IE 5.5, IE 6
IE7 Standalone is a standalone Internet Explorer 7 that is good to have.
Supports: IE 7
eVolt has a nice repository of just about any browser you can think of. Good resource.
Supports: All
BrowserShots is a website that will give you a screenshot of your specified webpage to show you how it will look on that webpage. Good to get an idea, but not ideal for active cross-browser development.

There are many other solutions out there but I try to keep this list limited to solutions that work, are unobtrusive, and easy to install and use.

Javascript's with() function

2009-10-03T08:59:00.000-07:00

There is a feature in JavaScript that is not widely documented yet very helpful: the with() function.

The function is effectively a shorthand that eliminates repetitive objects. An example will best illustrate the benefit.

with(window.open('', 'title',
 'toolbar=0,scrollbars=0,location=0,statusbar=0,' +
 'menubar=0,resizable=0,width=280,height=40').document)
    { 
     open();
     write(email);
     close();
    }

Without using with() this same code would look like this:

var winId = window.open('', 'title', 
 'toolbar=0,scrollbars=0,location=0,statusbar=0,' +
 'menubar=0,resizable=0,width=280,height=40');
   winId.document.open();
   winId.document.write(email);
   winId.document.close();

We can clearly see that by using with() we can eliminate the repetitive "winId.document" and we don't have to do any explicit variable memory allocation.

Using this lets us reduce the bloat of our JavaScript code by eliminating repetitive code, making it more maintainable.

Usage

The key is that the with() statement can operate on any object. In JavaScript everything is an object, so it makes it easy to implement just about with anything. Let's take the next example where I use the with() statement on a hash data structure.

var data = {
             hello : 'Guten Tag',
             name : 'Milan',
             cool : 'geil',
             scores : {
                       high : 2000,
                       low : 1000
                      },
             run : function() { alert('Done') }
            };

 with (data)
  {
   alert(hello + ' ' + name + ', this is really ' + 
         cool + ' and your scores are : \n' + 
         (function() { 
            with(scores) 
             { 
              return "  high score : " + high +
                        "\n  low score : " + low 
             } 
          })());
   run();
  };

This shows that we can easily use this on code blocks where we refer anything that is repetitive, including data structures. Furthermore, we can also have nested with() functions as shown above.

It should be noted that using with() is discouraged however its use introduces ambiguous behavior if you do not know what you are doing and has a higher overhead due to this attempt of finding what to tie an object with. Handle with care, but be aware this is something you can use if you know what you're doing.

Scope

The curly brackets do not define scope. Any variables declared within will assume the scope of where the with() is called.

Hash Arguments & Return Pattern

2009-09-30T13:11:00.000-07:00

If best practices are followed when programming functions and methods, global variables are used sparingly if at all. This then begs the question of what is the best way to pass data in and out from these functions and methods?

In this article I will cover a pattern I've developed that is intuitive, flexible, and consistent. The suggested pattern is used in my FlyTabs jQuery plugin that I released back in 2008 but have used a similar pattern in Perl long before then.

The Hash Arguments & Return Pattern is conveniently abbreviated to HARP.

Input Parameters

Passing arguments into a function or method can be done in many different ways. This pattern relies on the flexible hash data structure as the input data transport, or in other words a collection of keys and associated values.

registerUser({
                firstName : 'Milan',
                lastName : 'Adamovsky'
               });

The benefit of using a hash is that we can change the number, order, or data type of parameters at any given time without having to mess with the function or method source codes.

Most programmers prefer to explicitly list the individual parameters as shown below.

registerUser(firstName, lastName);

The benefit to this traditional convention is that we ensure that only the expected input is passed. Another benefit is that performance wise it will be better - though invisible to the human eye. The drawback to this approach becomes visible when it comes time to augment the code.

Explicitly listing every expected parameter means that when there is a change in the parameter list we need to search through the entire code and find every location where the function or method is called and ensure that we adjust it with the changes. A hash eliminates this since the hash itself changes, but the function or method call remains the same regardless of a hash's contents.

hash approach	list approach
No specific order Flexible Easy to maintain Slightly slower	Specific order Rigid Hard to maintain Slightly faster

Understanding the fundamental differences of the two approaches will let you decide which is best for your circumstances.

In an enterprise development environment one would usually want to opt for the hash solution due to the larger development team, long term goals, and higher frequency of code upgrades. Conversely, a list approach should only be used in functions and methods where every ounce of performance is sought after, and where one knows the function's or method's interface will not change often if at all. In other words, the latter should really only be used by a senior developer who understands all the implications of doing so.

Up to this point I've been using functions and methods interchangeably. It should be noted that in OOP one could use properties as data transports, but since a method can take parameters too we will continue using these interchangeably. Keep this little caveat in mind though when using this pattern.

A function or method would then be coded to accept only one parameter: a hash.

function registerUser (args)
   {
    var firstName = args.firstName,
        lastName = args.lastName;

    ...
   }

We can see that the beauty of passing a hash as a sole argument is that we can now abstract the interface of the function or method and tap into the hash for whatever data we need.

Return Values

As with the input values I like to keep the output values just as simple: a hash.

That's right! The interface to each function and method only returns one object and that is a hash for the same good reasons the arguments use a hash. The one exception on the return hash is that it follows a convention which I refer to as tiered output and it is illustrated below.

function registerUser (args)
   {
    var code = 0,
        message = '',
        data = {}

    ...

    return ({
             code : code,
             message : message,
             data : data
            });
   }

It is a tiered output in the sense that we have an interface with keys that will always be present. Furthermore a code will always be a numeric value (usually '0' for a failure, and '1' for a success). A message will always be a short string (usually only populated in the event of a failure code, indicating the actual error). Finally, the data is a hash that can contain anything that would traditionally be returned by the function or method.

A code can return any numbers that can further be checked against. The only two that should be reserved are the aforementioned ones.

Transposing Apache's error code onto this approach would look something like this:

function pageNotFound (args)
   {
    ...

    return ({
             code : 404,
             message : 'Page Not Found',
             data : {}
            });
   }

The above example is meant for clarity.

Calling a function or method becomes pretty simple and predictable. While the return hash can be named anything, my personal habit is to name it retVal (short for "return value").

var retVal = pageNotFound(...);

  if (!(retVal.code))
   {
    alert(retVal.message)
   }

Let's tie everything together into one complete example illustrating the full use of HARP working with the aforementioned examples.

<script>
  function registerUser (args)
   {
    var firstName = args.firstName;
    var lastName = args.lastName;

    var code = 0,
        message = '',
        data = {};

    if (firstName == '')
     {
      message = 'First name is empty!';
     }
    else if (lastName == '')
     {
      message = 'Last name is empty!';
     }
    else
     {
      code = 1;
      data.completeName = firstName + ' ' + lastName;
     }

    return ({
             code : code,
             message : message,
             data : data
            });
   }

  var retVal = registerUser({
                            firstName : 'Milan',
                            lastName : 'Adamovsky'
                           });

  alert(retVal.code ? retVal.data.completeName 
                    : 'Error: ' + retVal.message);      
 </script>

Copy and paste this and see how it works. It's easy, amazing, and flexible!

Exception Handling

You may be wondering if this pattern is in competition with traditional exception handling and the answer is no.

Exception handling's purpose is to handle exceptions. This means that in the event of an exception, the handling of such is handled appropriately. HARP on the other hand focuses on the input and output of a function or method.

This means that a method can return a success or failure, but it doesn't necessarily have to be an exception. In this case an exception handler would not be thrown.

JavaScript Frameworks

2009-09-23T19:03:00.000-07:00

There are many JavaScript frameworks out there that each come with their own pros and cons. There is jQuery, ExtJS, YUI, MooTools, GWT, and Prototype just to name a few. With so many choices and each providing eye-popping features, it is not surprising that companies small and large simply tack on these frameworks to their existing library.

This seemingly innocent practice slowly snowballs into a larger problem than it solves - and eventually slows development to a crawling pace rather than do what a framework's intent is: speed up development.

How is this possible?

Whenever a framework is adopted by a company it usually does so on the recommendation of their developers who make it a personal choice rather than a sound decision for the business. Understandably enough the developer will naturally choose a technology he or she is most comfortable with.

This type of freedom should only exist once: When no framework has yet been adopted. Once a framework has been chosen, no more frameworks, period.

Here are some points that should be considered:

Performance
Every framework comes at a performance hit since it has a lot of overhead code to run the framework. As can be imagined loading all these frameworks unnecessarily increases the overhead and inversely decrease the performance of the website - eating away resources that could be used more effectively by other features of the website.
Compatibility
Luckily today's frameworks have a level of decency and foresight in playing nice with other frameworks in the event of their presence. Nonetheless this does not necessarily hold true for every framework out there. This could lead to namespace collisions of all types.

The other problem becomes knowing what framework to code on what portion of the website. A clever developer may advise to only load jQuery on one page, and YUI on another. This means that depending on what page a feature is to be added to, the developer needs to adapt to the framework running on that page. In turn, code becomes fragmented and cannot be easily re-used - losing most if not all modularity.
Productivity
Developers tend to specialize in one or two frameworks. It is not impossible for a developer to learn a new framework, but doing so is like learning a new language: it takes time, trial and error, and experience to get it right. This is wasted effort that could be used more efficiently.
Production Cost
One of the most important yet least observed points of adopting a multitude of frameworks is the fact that the code base now becomes segmented into an equal amount of skills needed to maintain and improve that same code base. This means either a developer must be familiar with all adopted frameworks, or the team has to grow to enough developers that will have the needed skills combined. Evidently, it will be costly either way one goes.

It becomes obvious that the solution becomes to just have one and only one framework. After all, learning one framework takes a lot less effort than learning several.

The above applies for any framework. The moral of the story is to choose any one, and only one, framework and stick with it. It is worth spending time figuring out how to make things work under the selected framework, rather than adopting a whole new framework that will achieve the task, but also duplicate already existing features.

CSS Localization

2009-09-23T13:40:00.000-07:00

It is quite simple to achieve conditional content showing by way of pure CSS for localization purposes. This may be ideal in some instances and not so much in others. We will explore both, but first let's see how we can accomplish this.

<style>
   p {
    display: none;
   }
   body:lang(en) p:lang(en) {
    display : inline; 
   }
   body:lang(cz) p:lang(cz) {
    display : inline; 
   }
 </style>

 <body lang="cz">
   <div>
     <p lang="en">Hello</p>
     <p lang="cz">Ahoj</p>
     <p lang="ru">Privet</p>
   </div>
 </body>

That's all there is to it!

The concept is quite simple: Hide all relevant elements, and selectively display only those of interest - with no scripting.

Now that we understand the concept let's improve upon it a little. The above example would hide all paragraph elements unless it is attributed a particular language. To overcome this little nuisance we simply create a class for all language items that will be shown conditionally.

It is pretty simple to do this and involves only a slight adjustment to the above code.

<style>
   p.select {
    display: none;
   }
   body:lang(en) p.select:lang(en) {
    display : inline; 
   }
   body:lang(cz) p.select:lang(cz) {
    display : inline; 
   }
 </style>

 <body lang="cz">
   <div>
     <p class="select" lang="en">Hello</p>
     <p class="select" lang="cz">Ahoj</p>
     <p class="select" lang="ru">Privet</p>
     <p>World</p>
   </div>
 </body>

The above will conditionally greet the user according to the language, but the word "World" will always be visible regardless of language.

Keep in mind that the display needs to be set to block or inline however the given tag or element is intended to work.

To select what language's content the page should display, all that needs to be done is adjust the lang attribute in the <body> tag.

The above example's output would be:

Ahoj 
  World

Needless to say the possibilities are endless. This approach is not limited to just the conditional showing of content but it can effectively be used in applying the correct style accordingly.

The disadvantage of this solution is that the server is pushing through all content for all languages. If content localization (e.g. translations) is the sole purpose, consider using some sort of server-side localization solution and return only the content specific to that language.

On the other hand this is great if one wants to give a user quick access to customizing the user experience.

Nothing would stop one from using a hybrid solution that would work with AJAX to conditionally inject the right content accordingly while having the CSS readily available to reformat the layout on-demand (e.g. changing from a left-to-right layout to a right-to-left).