Thursday, October 28, 2010

Don't confuse jQuery and Velocity Variable Names

Update. 6/02/2011 1:12:38 PM. Putting Javascript in a separate file is the best way to make sure jQuery and Velocity variables are not confused.

In Velocity, variables are denoted by the dollar sign ($), so when using normal notation, a velocity variable will appear as $someVar. This is tricky if you are writing jQuery code in the same file, because by convention you use the dollar sign to denote jQuery variables as well. For example, see below.

## Refers to a Velocity variable.
$emailAddress = "noreply@example.com"

// Refers to the jQuery object (that wraps a dom object).
var $email = $("#email");
// Refers to a dom object itself
var email_field = $("#email").get(0);

Most often, this is not an issue. The server (and thus Velocity) evaluates a script first and then passes the HTML (including jQuery code) to the browser. In the first stage, Velocity will pick up and evaluate all Velocity variable names i.e. things beginning with a dolllar sign, such as $email. If it finds no value (empty string or null) for that variable, it echos out the name as is, leaving the token $email intact for Javascript to evaluate.

If you do find names are clashing, you can fix this using any of these ways, listed in order of my personal preference.

  1. Put the Javascript into an external .js file. This way the Velocity engine will never even look at the file, and you get the benefit of separation of concerns (HTML being separate from Javascript) and caching (browsers caches Javascript file so it doesn't have to downloaded again every time the page is accessed).
  2. Use different names! The example above will not create an issue because the names are all different: $emailAddress vs $email vs email_field.
  3. Use different characters to denote a jQuery object, e.g. _email = $("#email") as per this excellent article on Authentic Society (The Learning Website): JavaScript Dollar Sign ($) - What is it for?
  4. Use silent notation for Velocity variables, or least those Velocity variables you know or think will be confused with jQuery variables. E.g. $!email. When using silent notation, Velocity will output nothing in place of the variable name if it finds no value (empty string or null) for that variable - leaving nothing to confuse Javascript.
  5. Use formal notation for Velocity variables, or least those Velocity variables you know or think will be confused with jQuery variables. E.g. ${email}. Just as in Bash scripting, the curly braces help the Velocity script engine to discriminate Velocity variables from other text. When using formal notation, Velocity will output tha name as is, leaving the token (e.g. ${email}) intact - which will not confuse Javascript because you will be using $email for the jQuery variable.

It is important to note that in jQuery code, the dollar sign is not just used to denote jQuery variables, but it is also used as an alias for the jQuery class itself, and that in these instances you can use the token jQuery instead. For example, var $email = $("#email") and var $email = jQuery("#email") are the same.