sociomantic labs | Real-time bidding solutions for eCommerce » Code Talk

Native Javascript Ninjutsu: Navigator object browser detection

Dylan — Mon, 08 Nov 2010 11:35:49 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Javascript used to be a dark and ancient art, looked down upon by many web developers as a dishonorable – even malicious – ‘copy and paste’ language. Macromedia’s Shockwave – which later became Macromedia Flash, which even later became Adobe Flash – pushed audio, video, and interactive motion graphics onto the web in a cross-browser compatible format that all but decimated the need and appeal for Javascript. What little Javascript community there was began to seriously dwindle and die out.

And then the frameworks came to rise: Dojo, Yahoo! UI Library, Google Web Toolkit, jQuery, Prototype, MooTools, and many more. With these powerful armies by its side, the Javascript community quickly grew and regained its honor, competing heavily with the fluid animation and complex, real-time interactivity that Flash had delivered for years.

Javascript now seems to be a strong, healthy, and widely accepted language, frequently used and relied upon by web developers across the land. Yet how many of today’s programmers can write pure native Javascript without the aid of a framework? How many can perform AJAX requests without a framework? And most importantly, how many can craft fully cross-browser compatible code without a framework? In order to not become dependent on the frameworks – and thus risk sliding backwards into the dark ages – we must maintain a wide variety of practices: these are the native Javascript disciplines.

Discipline 8: Tenmon (meteorology)

In my daily JS missions I do my very best to make sure my code is fully cross-browser compatible. Even in the worst case scenario I try extremely hard to find clever solutions that allow me to avoid relying on browser detection. Despite this practice and frame of mind I still believe it’s useful for native JS ninjas to understand how to use browser detection techniques.

Let’s first take a look at the navigator object. While it has some useful properties and methods, it’s very important to remember that they can – and often will – return inaccurate and misleading information. This is not only because there is no public standard for this object (and its methods and properties), but also because some of its properties (such as the navigator.userAgent) are extremely easy to spoof. You’ll want to note that I’ll be using Firefox version 3.6.12 (with cookies and Java enabled) on Windows 7 (in English) for the following examples, and thus if you test my code snippets within your work environment you may not (and most likely won’t) see the same results returned.

navigator.appCodeName

The navigator.appCodeName property will return the code name of the browser:

var browser_code_name = navigator.appCodeName;

The above code will return “Mozilla” for my browser settings and environment.

navigator.appName

The navigator.appName property will return the name of browser.

var browser_name = navigator.appName;

The above code will return “Netscape” for my browser settings and environment.

navigator.appVersion

The navigator.appVersion property will return the version information of the browser.

var browser_version = navigator.appVersion;

The above code will return “5.0 (Windows; en-GB)” for my browser settings and environment.

navigator.cookieEnabled

The navigator.cookieEnabled property will return whether or not cookies are enabled in the browser.

var browser_cookie_enabled = navigator.cookieEnabled;

The above code will return “true” for my browser settings and environment.

navigator.platform

The navigator.platform property will return which platform the browser was built to run on.

var browser_platform = navigator.platform;

The above code will return “Win32″ for my browser settings and environment.

navigator.userAgent

The navigator.userAgent property will return the user-agent header that the browser sends to the server.

var browser_user_agent = navigator.userAgent;

The above code will return “Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB; rv:1.9.2.12) Gecko/20101026 Firefox/3.6.12″ for my browser settings and environment.

navigator.javaEnabled()

The navigator.javaEnabled() method will determine whether or not Java is enabled.

var browser_java_enabled = navigator.javaEnabled();

The above code will return “true” for my browser settings and environment.

20 Browsers Worth Testing

Now that we’ve become a bit more familiar with the navigator object let’s take a look at the various browsers available to our users. It’s important to understand that while a majority of users may have upgraded to one of the more modern web browsers (and their most recent release versions), there may still be a significant number of visitors using out-of-date browsers and older versions. Because of this I do my very best to support a wide range of browsers in my CSS, HTML, and JS production. I currently test 20 different browsers for each mission I embark on:

IE9
IE8
IE7
IE6
FF4
FF3.6
FF3.5
FF3
FF2
Chrome 9
Chrome 8
Chrome 7
Chrome 6
Chrome 5
Chrome 4
Safari 5
Safari 4
Safari 3
Opera 10
Opera 9

I only consider a web project fully cross-browser compatible if it works in all of the above browsers and versions.

Browser Detection

Detecting the above 20 browsers using the navigator object can seem daunting at first as many of the navigator properties do not return what one might expect. I did a series of tests in Windows 7 using all the above browsers and determined that the most accurate and simplest way for me to detect the browser was to read the returned value of the navigator.userAgent. Now this may seem obvious to experienced users, but I hope that this will tip will help beginners avoid the mistake of attempting to rely on the likes of navigator.appCodeName, navigator.appName, and navigator.appVersion.

After that I went through each browser and looked for a unique part of the user-agent header that I could use to properly identify each browser and version. Fortunately these unique strings are pretty straight forward and quite human-readable. Below you can see some example JS that will attempt to detect the browser name and version number based on the existence of various strings in the navigator.userAgent property:

var browser = navigator.userAgent;
var browser_name = 'Unknown';
var browser_version = 'Unknown';

if ( browser.indexOf( 'MSIE' ) !== -1 )
{
    browser_name = 'Microsoft Internet Explorer';

    if ( browser.indexOf( 'MSIE 6' ) !== -1 )
    {
        browser_version = '6';
    }
    else if ( browser.indexOf( 'MSIE 7' ) !== -1 )
    {
        browser_version = '7';
    }
    else if ( browser.indexOf( 'MSIE 8' ) !== -1 )
    {
        browser_version = '8';
    }
    else if ( browser.indexOf( 'MSIE 9' ) !== -1 )
    {
        browser_version = '9';
    }
}
else if ( browser.indexOf( 'Firefox' ) !== -1 )
{
    browser_name = 'Mozilla Firefox';

    if ( browser.indexOf( 'Firefox/4' ) !== -1 )
    {
        browser_version = '4';
    }
    else if ( browser.indexOf( 'Firefox/3.6' ) !== -1 )
    {
        browser_version = '3.6';
    }
    else if ( browser.indexOf( 'Firefox/3.5' ) !== -1 )
    {
        browser_version = '3.5';
    }
    else if ( browser.indexOf( 'Firefox/3' ) !== -1 )
    {
        browser_version = '3';
    }
    else if ( browser.indexOf( 'Firefox/2' ) !== -1 )
    {
        browser_version = '2';
    }
}
else if ( browser.indexOf( 'Chrome' ) !== -1 )
{
    browser_name = 'Google Chrome';

    if ( browser.indexOf( 'Chrome/4' ) !== -1 )
    {
        browser_version = '4';
    }
    else if ( browser.indexOf( 'Chrome/5' ) !== -1 )
    {
        browser_version = '5';
    }
    else if ( browser.indexOf( 'Chrome/6' ) !== -1 )
    {
        browser_version = '6';
    }
    else if ( browser.indexOf( 'Chrome/7' ) !== -1 )
    {
        browser_version = '7';
    }
    else if ( browser.indexOf( 'Chrome/8' ) !== -1 )
    {
        browser_version = '8';
    }
    else if ( browser.indexOf( 'Chrome/9' ) !== -1 )
    {
        browser_version = '9';
    }
}
else if ( browser.indexOf( 'Safari' ) !== -1 )
{
    browser_name = 'Apple Safari';

    if ( browser.indexOf( 'Version/3' ) !== -1 )
    {
        browser_version = '3';
    }
    else if ( browser.indexOf( 'Version/4' ) !== -1 )
    {
        browser_version = '4';
    }
    else if ( browser.indexOf( 'Version/5' ) !== -1 )
    {
        browser_version = '5';
    }
}
else if ( browser.indexOf( 'Opera/9' ) !== -1 )
{
    browser_name = 'Opera';
    browser_version = '9';

    if ( browser.indexOf( 'Version/10' ) !== -1 )
    {
        browser_version = '10';
    }
}

Although the above code works like a charm in my test environment, it’s extremely important to remember that the user-agent header is very easy to spoof. Again – in order to not alarm and enrage the experienced coders out there and also to properly guide and inform the beginners – I want to explicitly state that the above method of browser detection is not at all a replacement for building cross-browser compatible code to begin with. I highly suggest you design your CSS, HTML, and JS to work in all browsers without the need to rely on browser detection techniques.

I personally only use JS browser detection in my own ‘sandbox’ (a local test environment for front-end web development) and I do so there because it’s easy to forget which browser (and version number) I’m currently viewing when I need to test each file in all 20 of the above listed browsers. Human error is natural and in such an environment I’m simply using the browser detection to provide me with an easy way to display the current test browser and version number. Remember: I’m acting as the user and thus I know that the user-agent header is accurate and not being spoofed.

Cross-Browser Compatibility Test Environment

I’ll admit that I’m no expert on the many web applications and desktop software solutions that exist out there for doing cross-browser compatibility testing. I actually prefer to do as much of my testing by hand whenever possible. I currently have a test environment that I particularly like and find to be useful, fast, and quite reliable. It consists of a local ‘sandbox’ I’ve developed, which is, in essence, simply an archive of test files. I have setup a local host so that the ‘sandbox’ can be quickly reached with the short URL: ‘http://sandbox’.

In addition to my locally installed web browsers I also run the Spoon Browser Sandbox and make sure that all of the browsers’ homepages are set to my ‘sandbox’ host (with the exception of IE9 Preview which currently does not allow a homepage to be set). This means I can quickly and efficiently check a single test in numerous browsers, one after the other, with only a few clicks and without needing to have said browsers actually installed on my machine. I open a test browser and it immediately jumps to my list of test files, I select one, see the results (success or failure), make note of the browser and version number that my JS detection displays in the top corner, close the browser, and repeat the process.

This is only one solution to building a cross-browser compatibility test environment and I’m very open to hearing the other options people use. Please leave a comment if you have found (or made) a test environment that you think is particularly clever, useful, or otherwise worth mentioning. For those beginners out there I hope this article has helped to steer you in the right direction, informing you of the importance of not relying on JS browser detection, but also providing you the necessary means to attempt browser detection whenever it may be useful or interesting.

Previous Disciplines
Discipline 1: AJAX with XHR
Discipline 2: Dynamic JS with PHP
Discipline 3: Include External JS
Discipline 4: Cookies and Variables
Discipline 5: removeNode vs. removeChild
Discipline 6: DOMinating iframes
Discipline 7: Document object methods & properties
Discipline 8: Window object methods & properties

Resources
W3Schools’ Navigator Object Reference
Spoon Browser Sandbox

Are you smart? Innovative? Driven? If you’re interested in working on challenging projects in one of the world’s most fast-paced industries, why not check out the openings on our Careers page?

D-tails 1: local this

Gavin — Fri, 05 Nov 2010 13:20:39 +0000

This is the first in an on-going series of posts relating nuggets of D wisdom gained through daily praxis.

“this is a local variable”

I recently came across the situation where I needed to pass a pointer to an object to a callback function in a C library. The function was designed so that you can pass ‘additional data’ by means of a void*, which could be used to point to any kind of data in memory which would contain the context for the callback. This is a fairly common pattern in C libraries, designed to make the callbacks flexible and extensible to any use case.

Here’s a simplified example of the situation:

class MyClass
{
	// Method to register a request with the C library, passing a reference
	// to this object as the 'context', which will be passed to the C callback
	// function below when the request is processed.
	void register ( )
	{
		void* pointer_to_this /* = ? */;
		CLibraryFunction(pointer_to_this);
	}

	// Callback
	extern ( C ) static private void callback ( void* context )
	{
		// somehow cast the 'context' argument to an object reference
		// and do something with it
	}
}

So the question is, how to get the address of an object, from inside it, to pass to the C library function? And how to convert it back to a usable object reference inside the callback function?

My initial instinct was:

	void* pointer_to_this = &this;

Sounds fair enough, right? But unfortunately it’s not that simple. After some research I turned up the fairly obscure fact that this is actually a local variable which is implicitly added to the every method’s parameter list. This means that by taking the address of this, all we get is a pointer to somewhere in the stack, which is not at all what was intended!

The solution is to think about what this actually is: a reference to an object. So we can cast the reference directly to a void*, and then cast it directly back – there’s no need to take the address of it or to dereference it at the other end using the * operator.

class MyClass
{
	// Method to register a request with the C library, passing a reference
	// to this object as the 'context', which will be passed to the C callback
	// function below when the request is processed.
	void register ( )
	{
		void* pointer_to_this = cast(void*)this;
		CLibraryFunction(pointer_to_this);
	}

	// Callback
	extern ( C ) static private void callback ( void* context )
	{
		MyClass object = cast(MyClass)context;
		// do something with object
	}
}

More D language “D-tails” to come.

Native Javascript Ninjutsu: Window object methods & properties

Dylan — Thu, 21 Oct 2010 10:39:42 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 8: Sui-ren (water training)

NOTE: This article was written with the JS beginner in mind, so it will likely bore the rest of you!

Last week’s article covered the most useful properties and methods of the document object, so this week I’d like to zoom out a bit and explore the window object. Just like the document object, the window object has a variety of its own properties, objects, and methods, though we’ll only go over the most useful and interesting ones. Here’s a quick list of what we’ll discuss:

Properties/Objects:

window.document
window.frames
window.length
window.location
window.name
window.navigator
window.parent
window.self
window.top

Methods:

alert
confirm
prompt
setInterval
clearInterval
setTimeout
clearTimeout
window.open
window.close
window.focus
window.blur

Let’s take a look at some of the most useful (and cross-browser compatible) properties first:

window.document

We’ve already discussed the document object in the previous article so I won’t go into detail, though it’s important to note that this object is a property of the window object.

window.frames

The window.frames property stores an array of all the frames in the given window. You can access a particular frame by providing it’s index number (remember that the index count of an array begins with 0, not 1):

var first_frame = window.frames[0];
var second_frame = window.frames[1];

Once you’ve referenced a particular frame using the frames property you can access its properties:

var first_frame = window.frames[0];
var second_frame = window.frames[1];
var first_frame_source = first_frame.location;
var second_frame_source = second_frame.location;

You can read more about the frames property in my previous post, DOMinating iframes.

window.length

The window.length property stores the number of frames in the given window. This should return the same result as window.frames.length:

var number_of_frames = window.length;

window.location

The window.location property is actually an object which stores all the data about the given window’s current URL:

var the_current_url = window.location;

The location object also has its own properties for returning various parts of the URL. The location.href property will also return the entire URL:

var the_current_url = window.location.href;

The protocol property will return the protocol being used (such as HTTP, HTTPS, FTP, FTPS, etc):

var the_current_url_protocol = window.location.protocol;

The port property will return the port being used (if one was explicitly provided):

var the_current_url_port = window.location.port;

The host and hostname properties will return the host part of the URL:

var the_current_url_host = window.location.host;
var the_current_url_host = window.location.hostname;

The pathname property will return the full path of the current URL:

var the_current_url_path = window.location.pathname;

The hash property will return the anchor of the current URL (if one is provided):

var the_current_url_hash = window.location.hash;

The search property will return the query parameters of the current URL (if any ar provided):

var the_current_url_query_parameters = window.location.search;

The location object also has some of its own methods, but I hardly ever use them in my native JS missions so I won’t explain them here.

window.name

The window.name property stores the value of the window’s name attribute. You can retrieve and set this value:

var the_old_name = window.name;
window.name = 'the new window name';

window.navigator

The window.navigator object can be quite an extensive subject and I find it deserves its own article, so I’ll be discussing the navigator() object in the next post in this series. Stay tuned for that if you’d like some more detailed info about this property.

window.parent

The window.parent property references the parent of the given window:

var the_parent = window.parent;

This can also be used recursively:

var the_parent = window.parent;
var the_grandparent = window.parent.parent;

window.self

The window.self property allows you to reference the current window:

var the_current_window = window.self;

window.top

The window.top property allows you to reference the topmost window:

var the_topmost_window = window.top;

There are many more properties that belong to the window object, though these are the ones that I find most useful in real-world applications. These are also the ones that I’ve found to be fully cross-browser compatible and W3C compliant in my testing and research. Let’s continue our exploration of the window object by looking at a few of it’s most useful methods:

alert()

The alert() method is one of the most useful and commonly applied functions I can think of: it’s used constantly in early production, testing, and debugging stages of any native JS code. It’s fully cross-browser compatible and incredibly easy to use:

alert( 'This is the alert message' );

The above code will open an alert box in the browser and display your message within it.

confirm()

Very similar to alert(), the confirm() method will open a confirmation box in the browser that will include your message, an ‘OK’ button and a ‘Cancel’ button. It’s also cross-browser compatible and fairly easy to use:

confirm( 'This is the confirmation message' );

The message is optional but it’s wise to include one, otherwise your users won’t know what they are confirming. Now if you want to check for which button the user has pushed you can do the following:

var user_pushed_ok = confirm( 'This is the confirmation message' );
if ( user_pushed_ok == true )
{
    // User pushes 'OK'
}
else
{
    // User pushed 'Cancel'
}

prompt()

The prompt() method is similar to both the alert() and the confirm() methods: it opens a browser alert message. The difference is that prompt() prompts the user to input some text. Again, it’s relatively simple to use:

prompt( 'This is the prompt message' );

Just like confirm() the first parameter is optional. You can also provide a second parameter to specify if there should be default text filled in for the user:

prompt( 'This is the prompt message', 'This is the default text' );

In order to use the text inputted by the user you’ll have to save the returned value of the method to a variable (as we do above with the confirm() method):

var the_user_input = prompt( 'This is the prompt message', 'This is the default text' );

setInterval()

The setInterval() method is used to trigger a piece of code (typically a function call) over and over again until either the window is closed or the clearInterval() method has been called (see below for a description of this method). The method takes three parameters: the code to execute, the interval between executions (in milliseconds), and the script language (optional). For the sake of simplicity in this article we will just focus on the first two parameters:

function theMethodToRepeat()
{
    // Do something
}

setInterval( 'theMethodToRepeat()', 5000 );

The above code will call theMethodToRepeat() function every five seconds. This will happen forever until the window is closed or the clearInterval() method is called.

clearInterval()

The clearInterval() method can be used to stop the looped execution of a setInterval() method. It’s relatively simple to use and requires you to store the return of the setInterval() method into a variable:

function theMethodToRepeat()
{
    // Do something
}

var the_interval = setInterval( 'theMethodToRepeat()', 5000 );

function stopTheInterval()
{
    the_interval = clearInterval( the_interval );
}

Whenever you wanted the loop to be stopped you could simply make a call to the stopTheInterval() function and it will clear the interval loop.

setTimeout()

The setTimeout() method works almost identical to the setInterval() method except that it does not automatically loop over and over again. Instead, it waits the given amount of time and only executes the given code (typically a call to a function) once:

function theMethodToCall()
{
    // Do something
}

setTimeout( 'theMethodToCall()', 5000 );

The above code will execute theMethodToCall() function after waiting five seconds. In order to use this in a loop you must include the setTimeout() method inside of the function it calls:

function theMethodToCall()
{
    // Do something

    setTimeout( 'theMethodToCall()', 5000 );
}

theMethodToCall();

As you can see, theMethodToCall() function is executed over and over again, every five seconds. Just like the setInterval() method, the setTimeout() method can be canceled using the clearTimeout method.

clearTimeout()

var the_timeout;

function theMethodToCall()
{
    // Do something

    the_timeout = setTimeout( 'theMethodToCall()', 5000 );

    if ( someValue == true )
    {
        clearTimeout( the_timeout );
    }
}

theMethodToCall();

The code above checks if someValue equals true, and if it does then the clearTimout() method is called to make sure the loop is broken.

window.open()

To be honest, I hardly ever use this method in my live production work, though I thought it was still worth describing. The window.open() method can be used to open a new browser window. It has four parameters which are all optional: the URL, the window name, the window specs, and a replace flag. If you use the method with no parameters it will simply open a blank window:

window.open();

Specifying a URL and a window name is extremely straightforward:

window.open( 'http://somedomain.com', 'The name of the new window' );

Passing in window specs is a bit more complex. You need to pass them as a comma separated list:

window.open( 'http://somedomain.com', 'The name of the new window', 'width=800, height=600' );

There are many specs that you can define, though the most useful are the ones that are fully cross-browser compatible:

width (window size, in pixels)
height (window size, in pixels)
left (window location, in pixels)
location (window has an address field, true or false / 0 or 1)
menubar (window has a menu bar, true or false / 0 or 1)
resizable (window is resizable, true or false / 0 or 1)
scrollbars (window has scrollbars, true or false / 0 or 1)
status (window has a status bar, true or false / 0 or 1)
titlebar (window has a title bar, true or false / 0 or 1)
toolbar (window has a tool bar, true or false / 0 or 1)

Lastly, the replace parameter specifies whether the new window will add a new entry in the browser history or replace the current entry. This parameter should be set to true or false.

Now if you want to use JS to open a new window and write specific elements to it’s DOM then you’ll have the store the return of the window.open() method to a variable:

var the_new_window = window.open();
the_new_window.document.write( 'This is a paragraph tag in the new window!' );
the_new_window.focus();

This code is pretty self-explanatory and the only part we haven’t gone over is the focus() method which I will describe below. Keep in mind that using the window.open() method is pretty risky because many browser settings will detect this action as a pop-up window and block it from the user.

window.close()

Using the window.close() method to close a window is pretty simple:

var the_new_window = window.open();
the_new_window.document.write( 'This is a paragraph tag in the new window!' );
the_new_window.focus();

function closeTheNewWindow()
{
    the_new_window.close();
}

As you can see in the code above we call the close() method on the appropriate variable (which stores the window reference) and we can close it quickly and easily.

window.focus()

In one example above I used the focus() method and I thought it would be wise to briefly explain that this method can be used to set which window has the current focus (which one is on top). It’s simple to use:

some_window.focus();

window.blur()

And to compliment the focus() method is the blur() method, which does the exact opposite: removes the focus from the referenced window:

some_window.blur();

There are many more methods and properties that belong to the window object, but I find that the above mentioned ones are the most essential for your native JS knowledge. I hope this short tutorial has been helpful for you beginners out there. Stay tuned for next week’s discipline: Navigator object browser detection.

Resources
W3Schools’ HTML DOM Window Object

Native Javascript Ninjutsu: Document object methods & properties

Dylan — Mon, 04 Oct 2010 08:00:50 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 7: Chi-mon (geography)

NOTE: This article is for JS beginners only, and it will likely bore the rest of you!

While working with the HTML DOM I find that it greatly helps to fully understand and know the document object itself. The document object mostly consists of three types of features: properties, methods, and objects of its own (though most of the objects are deprecated now). Here’s a quick list of what I plan to go over in this article:

Properties:

document.cookie
document.domain
document.referrer
document.title
document.URL

Methods:

document.createElement
document.getElementById
document.getElementsByName
document.getElementsByTagName

Let’s take a look at some of the most useful (and cross-browser compatible) properties first:

document.cookie

I’ve already gone over this property at length in my cookies and variables article so I won’t go into much detail in this tutorial, but here’s a basic example:

document.cookie = 'cookie_name=cookie_value';
document.cookie = 'another_cookie_name=another_cookie_value';
document.write( document.cookie );

The above code will output “cookie_name=cookie_value; another_cookie_name=another_cookie_value”. As you can see the document.cookie property can be used to store a string of cookie names and values.

document.domain

The domain property returns the domain that loaded the current page. This property is read-only and cannot be set using JS.

document.write( document.domain );

On this page the above code would output “blog.sociomantic.com”.

document.referrer

The referrer property returns the URL of the page that loaded the current page. This property is read-only and cannot be set using JS.

document.write( document.referrer );

On this page the above code could output “http://blog.sociomantic.com/” if you navigated to this article via our main blog page.

document.title

The title property returns the URL of the current page. You can also set this property using JS to change the document title:

document.title = 'New Document Title';

document.URL

The URL property returns the URL of the current page. This property is read-only and cannot be set using JS.

document.write( document.URL );

On this page the above code will output “http://blog.sociomantic.com/2010/09/native-javascript-ninjutsu-document-object-methods-properties/”.

There are many more properties that belong to the document object, though these are the ones that I find most useful in real-world applications. These are also the ones that I’ve found to be fully cross-browser compatible and W3C compliant in my testing and research. Let’s continue our exploration of the document object by looking at a few of it’s most useful methods:

document.createElement()

The createElement() method creates an HTML element that can be added to the DOM. It’s pretty simple to use, you pass it the tag name of the element which you would like to create:

var the_element = document.createElement( 'p' );

The above code creates a p (paragraph) element, but does not yet add it to the page. Here’s an example of how to add the new element to the DOM:

As you can see we store the new element in a variable, store another element in a variable, and use the location of the second element to help us place the first element into the page.

document.getElementById()

I’ve already demonstrated how to use the getElementById() above and I think that it’s very self-explanatory, but for those true beginners out there here’s the idea: you pass it an id value as the parameter and it returns the element (if found):

var the_element = document.getElementById( 'some_id' );

Now let’s move onto two similar methods: getElementsByName and getElementsByTagName.

document.getElementsByName()

The getElementsByName() method is pretty self-explanatory: you pass it a name value as the parameter and it returns an array of all the elements that have the same value stored in their name attribute:

var all_elements_with_some_name = document.getElementsByName( 'some_name' );

This is mostly used to count (or reference) the elements used in HTML forms, particularly in the case of element groups that are required to share the same name (such as radio buttons or checkboxes).

document.getElementsByTagName()

The getElementsByTagName method is also pretty self-explanatory: you pass it a tag name as the parameter and it returns an array of all the elements that are of that tag type:

var all_paragraphs = document.getElementsByTagName( 'p' );

There are many more methods and properties that belong to the document object, but I find that the above mentioned ones are the most essential for your native JS knowledge. I hope this short tutorial has been helpful for you beginners out there. Stay tuned for next week’s discipline: window & location.

Resources
W3Schools’ HTML DOM Document Object
Javascript Kit’s Document Object
Javascript Kit’s Document Object Methods

Native Javascript Ninjutsu: DOMinating iframes

Dylan — Fri, 24 Sep 2010 14:44:23 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 6: Bajutsu (horsemanship)

I typically don’t front flip at the opportunity to use iframes in my native JS Ninjutsu practices, though I frequently find myself in the midst of a mission where I have no choice but to work with an iframe. While I may not need to approve of them, I certainly must make sure I know how to properly work with them in such cases. First and foremost, one must understand exactly what an iframe is, and I think it’s best to quote Wikipedia’s iframe article:

“An inline frame places another HTML document in a frame. Unlike an object element, an inline frame can be the [target] frame for links defined by other elements and it can be selected by the user agent as the focus for printing, viewing its source etc. The content of the element is used as alternative text to be displayed if the browser does not support iframes. First introduced by [MSIE] in 1997, standardised in HTML 4.0 Transitional, allowed in HTML 5.”

Now that we understand what an iframe is, let’s learn how to add one to the HTML DOM:

document.write( '

' );

That is the quickest and simplest way to get an iframe written to the DOM, though of course, if you want to be able to manipulate it further with JS it would make sense to give it an id:

document.write( '

' );

Alternatively you can give the iframe a name value and access it using the window.frames array (which I will demonstrate later in the article). The advantage to this approach is that it seems to be more backward compatible with older (legacy) web browsers:

document.write( '

' );

Despite it’s one-line appeal, the document.write method has a major downside: the JS itself must be located in the exact place in the DOM that you want the iframe to be inserted. For this reason I typically use the document.createElement and parentNode.insertBefore approach:

var the_iframe = document.createElement( 'iframe' );
the_iframe.id = 'the_iframe_id';

var another_element = document.getElementById( 'another_element_id' );
another_element.parentNode.insertBefore( the_iframe, another_elment.nextSibling );

The above code will create the iframe, give it an id value, locate another specific element on the page (which you want to insert the iframe after), and then add the new iframe to the DOM at the given location.

Adding the iframe won’t do much though, as we need to give it a src value before any content will appear inside of it:

var the_iframe = document.createElement( 'iframe' );
the_iframe.id = the_'iframe_id';
the_iframe.src = 'http://domain.com/directory/filename.html';

var another_element = document.getElementById( 'another_element_id' );
another_element.parentNode.insertBefore( the_iframe, another_elment.nextSibling );

Changing the content of the iframe is as easy as changing the value of the src attribute:

document.getElementById( 'the_iframe_id' ).src = 'http://new-domain.com/new-directory/new-filename.html';

As I mentioned above, you may use the legacy approach that relies on the iframe having a name value:

window.frames[ 'the_iframe_name' ].location = 'http://new-domain.com/new-directory/new-filename.html';

Although it’s nice to understand legacy and alternative approaches, this one in particular does not seem to be all that useful. In my cross-browser tests the document.getElementById().src method works in all eighteen (18) web browsers that I routinely check (IE9, IE8, IE7, IE6, FF4, FF3.6, FF3.5, FF3, FF2, GC7, GC6, GC5, GC4, Safari 5, Safari 4, Safari 3, Opera 10, and Opera 9). In my opinion this would mean that it’s a cross-browser compatible solution that is safe to use for all purposes.

Now that we’ve gone over some of the basics about using iframes it makes sense to discuss the relationship between the iframe and its parent page. When both your pages come from the same domain you can do a lot of simple communication between the iframe and the parent page. There are three different ways you can reference the iframe‘s content:

using the document.getElementById( 'the_iframe_id' ).contentDocument method,
using the document.getElementById( 'the_iframe_id' ).contentWindow.document method,
or using the window.frames[ 'the_iframe_name' ].document method.

I’ve done some extensive cross-browser testing and it seems that out of my usual eighteen (18) web browsers (listed above) the only two that don’t support the contentDocument method are IE6 and IE7. For this reason I would to one of the following:

Stick to using only contentWindow

var the_iframe = document.getElementById( 'the_iframe_id' );
var some_element = the_iframe.contentWindow.document.getElementById( 'some_element_id' );

or check to see if contentDocument is available before using it)

var the_iframe = document.getElementById( 'the_iframe_id' );

if ( the_iframe.contentDocument )
{
    var some_element = the_iframe.contentDocument.getElementById( 'some_element_id' );
}
else if ( the_iframe.contentWindow )
{
    var some_element = the_iframe.contentWindow.document.getElementById( 'some_element_id' );
}

There is one more alternative method to both of the above, and that is to rely on the name attribute of the iframe and access its elements using the window.frames array:

var the_iframe = window.frames[ 'the_iframe_name' ];
var some_element = the_iframe.document.getElementById( 'some_element_id' );

This last method is (again) more suitable for legacy web browsers, though it does appear to work in all the modern web browsers that I typically test for cross-browser compatibility. Let’s put this all together in the following example which shows you how to communicate down (from the parent page to the iframe):

And here is the source code of the_iframe_content.html:


This element should not be visible

This element should be visible

As you can see above I use the onload attribute/event to make sure the iframe has fully loaded it’s source before allowing the removeSomeElement() function to be executed. If I didn’t do this it’s very likely that the_iframe variable would end up being set as null or undefined and then the following code wouldn’t be able to properly locate the target element.

This whole process is referred to as ‘referencing down’ (or ‘communicating down’) because you are going from the parent page down into its child iframe. Similarly, ‘referencing up’ is when you reference the iframe‘s parent (and its DOM elements) by using the parent.document method:

var some_parent_element = parent.document.getElementById( 'some_parent_element_id' );

Here’s how to add this method into our previous example:


This element should not be visible

This element should be visible

And here is the source code of the_iframe_content.html:


This element should not be visible

This element should be visible

If everything works right each targeted element should be removed from its respective parent page’s DOM. The cool part of this feature is that you can easily use the same methods to deal with nested iframes. You can reference an iframe element two levels down by doing the following:

var the_first_iframe = document.getElementById( 'the_first_iframe_id' );
var the_second_iframe = the_iframe.contentWindow.document.getElementById( 'the_second_iframe_id' );
var some_element = the_second_iframe.contentWindow.document.getElementById( 'some_element_id' );

Similarly, to reference an element in the top level parent of an iframe you can do the following:

var the_top_parent_element = parent.parent.document.getElementById( 'the_top_parent_element_id' );

In theory you should be able to repeat this infinitely, though I’m sure there are iframe limits imposed by web browsers as a basic safety measure (I have not needed to test this before but maybe I will as it sounds interesting enough).

So far so good, but as soon as you begin playing with cross-domain src values in your iframe you’ll notice that communication between the parent and the iframe becomes extremely restricted. If the parent page and the iframe src are from two separate domains then it will be impossible to directly access the DOM elements of one from the JS of the other. However there is a technique (more suitably referred to as a ‘hack’) that uses fragment identifiers to pass information cross-domain between an iframe and it’s parent. A fragment identifier is the part of the URL that follows the hash / anchor symbol (#). If you change (or add) this value it will not reload or refresh the page, but it does modify the window.location.hash value. The trick is to constantly measure the window.location.hash every second (or so) to see if the value has changed. This technique is called ‘polling’. Here’s a working example of the fragment (hash) identifier and polling techniques used to reference down in a cross-domain environment:

And here is the source code of the_iframe_content.html (which should be located on a separate domain):

Most of the above code should be pretty self-explanatory, but I’ll go into a bit of detail for those readers who are less familiar with native JS. First we apply an onload event to the body of our parent page and set this event to trigger the setupTheForm() function. This function stores the iframe element, the form element, the input element, and the iframe src value into their own variables. Notice that the_src variable includes the original iframe content URL with a hash symbol added to the end. This is necessary to make sure the fragment identifier is parsed correctly and also doesn’t refresh or reload the content within the iframe. Next we add a custom function to the onsubmit event of the form which stores the value of the input element, combines it with the_src variable, and uses the result to update the iframe src attribute. The function will also return false in order to prevent the default HTML form submit event from being triggered (in case there is one).

The iframe content also has an onload event that triggers the startPolling() function. This function grabs the fragment identifier by using the window.location.hash method. We also apply the substr() method to remove the first character of the hash string (which will always be the hash symbol). In this example we’re assuming that the user will always provide a value that is equal to one of the HTML colors (such as white, black, blue, green, yellow, orange, red, purple, etc) and we use this value to set the document.body.style.backgroundColor. Lastly, the function references the global poll variable, storing setTimeout() to it, which waits for the given time in milliseconds (the second parameter) before calling the provided function (the first parameter). Since this setTimeout always calls it’s parent function it will repeat the function infinitely, thus providing us with a working polling mechanism.

Now that you’ve seen how to reference down in a cross-domain environment, let’s complete the test by incorporating the code needed to reference up as well:

And here is the source code of the_iframe_content.html (which should be located on a separate domain):

For this example you’ll notice that the parent page content and the iframe content are almost identical. The main difference is that the iframe will not need to store values for the_iframe and the_src variables, and that when the form onsubmit event is triggered the JS will store the_value into the parent page’s fragment identifier by using the parent.window.location.hash method. While the first example (referencing down) was fully cross-browser compatible (at least concerning the eighteen web browsers I’ve mentioned earlier in the article), the second example appears to only work in Firefox. This has to do with the various browser limitations imposed on setting the parent.window.location.hash value. It appears that this line of code can be replaced with parent.location though you’ll have to add the whole URL with the hash value and this means the parent page could possibly be refreshed/reloaded (I did not do extensive testing to verify whether the parent page is actually reloaded or not in every browser). Also, it’s important to remember that you’ll be restricted by any size restraints which apply to the URL itself. For this reason the fragment identifier method is obviously limited to passing smaller bits of information between the parent page and its children.

This article is far from covering all the aspects of the iframe and how it works – especially in cross-domain environments – but I hope it has been a helpful tutorial, providing you with a way to use native JS to work with iframes. Stay tuned for next week’s discipline: Document object methods & properties.

Previous Disciplines
Discipline 1: AJAX with XHR
Discipline 2: Dynamic JS with PHP
Discipline 3: Include External JS
Discipline 4: Cookies and Variables
Discipline 5: removeNode vs. removeChild

Resources
Dynamic Web Coding’s iframe scripting tutorial
Software As She’s Developed’s Cross Domain iframe article
Tagneto’s Cross Domain Frame Communication with Fragment Identifiers
AJAXPatterns’ Cross-Domain Comms via IFrame Demo

Implementing an asynchronous, epoll based network client with Tango on Linux

David — Tue, 21 Sep 2010 16:29:23 +0000

Implementing an asynchronous, epoll based network client with Tango on Linux

NOTE: The code snippets in this article use the D brush extension we built for the SyntaxHighlighter Evolved WP plugin. Info & download here.

To implement a network client application which can handle multiple socket connections simultaneously, there are basically two approaches:

using threads and handling each connection with an own thread,
having multiple connection session contexts and handling all connections with a single thread.

Approach 1 is pretty straight forward. Consider a simple case where the client application sends request data to the server and then receives response data from the server. The following code starts five client threads. Each thread connects to server localhost, port 4711, writes request_data (whatever it is) and reads response_data (whatever that is).

module ThreadedClient;

import tango.net.device.Socket;
import tango.core.Thread;

void main ( )
{
    Thread[5] threads;                  // 5 threads

    foreach (ref thread; threads)       // create thread instances
    {
        thread = new Thread(&doRequest);
    }

    foreach (thread; threads)           // start threads
    {
        thread.start();
    }

    foreach (thread; threads)           // wait for all threads to
    {                                   // finish
        thread.join();
    }
}

void doRequest ( )
{
    scope socket = new Socket;          // create socket
                                        // connection

    socket.connect("localhost", 4711);  // connect to server

    void[] request_data;                // request data buffer
    socket.write(request_data);         // send request

    void[] response_data;               // response data buffer
    response_data.length = 10;          // response will have a
                                        // length of 10 bytes

    socket.read(response_data);         // receive response
}

Note: For sake of simplicity, we assume that socket.write() sends all provided data and socket.read() completely populates the provided buffer. Since one cannot rely on that, it is advisable to wrap socket.write()/socket.read() in a loop or use Tango’s BufferedInput/BufferedOutput.

The threading approach works fine with a few (up to about 20) connections but scales badly because each thread has a significant resource usage overhead. A way that provides much better performance for a big number of simultaneously handled connections is to handle all connections in the main thread, using Linux’ epoll interface in combination with non-blocking socket I/O.

Tango’s EpollSelector is built on top of epoll and provides a pretty good D interface for it. These are the steps to use the EpollSelector with multiple sockets:

Create an EpollSelector instance and several Socket instances.
Set the Sockets to non-blocking I/O and connect to the server.
Register each of the Socket instances in the EpollSelector instance for an event. The event is usually Write (“socket became ready for writing”) or Read (“data arrived at socket so it became ready to read”).
Let the EpollSelector instance wait for an event to happen on some of the sockets.
Query which event actally happened on which socket by retrieving and iterating over the so-called Selection Keys from the EpollSelector.
Write to or read from the socket(s) which became ready to write/read and watch the return value of write()/read() to see how much of the data passed to write() have actually been written or, respectively, how much of the data buffer passed to read() has actually been populated.
If comparison of the read/write buffer length to the read()/write() return value indicates that there is more data to send or receive, continue with step 4.
Unregister the socket from the EpollSelector.
If you want to perform another read or write, continue with step 3.
Finished!

The following example demonstrates how to use an EpollSelector to wait for our five sockets to become ready to write, following step 1 to 5.

module ThreadedClient;

import tango.net.device.Socket;
import tango.io.selector.EpollSelector;
import tango.io.selector.model.ISelector : Event;

import tango.time.Time: TimeSpan;

void main ( )
{
    /*
     * Step 1: Create an EpollSelector and the Socket instances
     */
    scope selector = new EpollSelector;

    Socket[5] sockets;

    foreach (ref socket; sockets)
    {
        socket = new Socket;
    }

    /*
     * Step 2: Set the sockets to non-blocking I/O and connect to
     * the server
     */
    foreach (socket; sockets)
    {
        socket.socket.blocking = false;
        socket.connect("localhost", 4711);
    }

    /*
     * Step 3: Register each of the Socket instances in the
     * EpollSelector instance for an event. Here we register all
     * sockets for the event "socket became ready to for writing".
     */
    foreach (socket; sockets)
    {
        selector.register(socket, Event.Write);
    }

    /*
     * Step 4: Let the EpollSelector instance wait for an event to
     * happen on some of the sockets. We have to provide a
     * TimeSpan timeout parameter; TimeSpan.max disables timing
     * out.
     */
    selector.select(TimeSpan.max);

   /* Step 5: Query which event actally happened on which socket
    * by retrieving and iterating over the Selection Keys from the
    * EpollSelector instance.
    * Note that EpollSelector.selectedSet may be null.
    */

    auto selection_set = selector.selectedSet;

    if (selection_set) foreach (selection_key; selection_set)
    {
        // - selection_key.conduit is one of our sockets which
        //      just became ready for writing;
        // - selection_key.events contains the events that
        //      happened on the socket. We expect Event.Write but
        //      it may also be an error event like Event.Error,
        //      Event.InvalidHandle or Event.Hangup.
        //      Event.Hangup would notify us that the server
        //      closed the socket connection.

        /*
         * TODO -- Step 6: Write to or read from the socket(s)
         * would go here...
         */
    }
}

Now that we know how to wait for and be notified about each socket’s I/O readiness, we can start writing our request data into each socket. Here the mechanism of non-blocking I/O gets important.

Consider the following example of the Selection Key iteration body:

    foreach (selection_key; selector)
    {
        /*
         * Step 6: Write to or read from the socket(s). (In the
         * real world we would check selection_key.events for an
         * error event before doing anything.)
         */

        Socket socket = cast (Socket) selection_key.conduit;

        socket.write("Hello World!");
    }

There is always the possibility that the socket cannot instantly send all provided data. Usually socket.write() could then block and wait until the remaining data can be sent. Or imagine we would read from the socket, not all data we expect could have arrived which is very likely when we want to receive significantly more than just a Hello World! string.

To handle all connections as quickly as possible, we set the socket to non-blocking. That means that socket.write()/read() consume or produce just as many data as possible right now and return the number of bytes actually consumed or produced. Then we iterate over the Selection Keys, call socket.write() passing all output data to be written to this socket and memorize the return value which tells us how much of the data the socket actually consumed.

When the Selection Key iteration loop is finished, all of our sockets are busy sending the data they consumed. Then we call select() again to wait until a socket gets ready for writing and run the Selection Key iteration loop again to send the pending data.

That all is nice and good but the following difficulty arises from it. For each socket, we need:

a separate output buffer because in general the socket connections get different output data,
a counter that memorizes how much of the output data have actually been written into this socket.

That’s easy so far, we say, so for five sockets we just create five void[] buffer and five int counter variables. But when we are inside the Selection Key iteration loop, how do we know which buffer and counter belongs to the socket of the current Selection Key?

Fortunately, epoll, and so the EpollSelector, provide a pretty clever solution for this problem, the so-called Selection Key attachment. EpollSelector.register() accepts an optional third parameter of type Object — an arbitrary class instance –, which is attached to the registered conduit. Inside the Selection Key iteration loop the SelectionKey.attachment property contains the object attached to SelectionKey.conduit.

So we have to create a class that contains the context of each socket connection, in our example the output buffer and byte counter. Putting it all together, the code example expands to:

module ThreadedClient;

import tango.net.device.Socket;
import tango.io.selector.EpollSelector;
import tango.io.selector.model.ISelector : Event;

import tango.time.Time: TimeSpan;

import tango.text.convert.Format;

/*
 * Socket item class, bundles a socket instance with its event to
 * be registered for and its context.
 */
class SocketItem
{
    /*
     * Socket context class, used for the socket attachment
     */
    static class Context
    {
        size_t counter = 0;
        void[] data;
    }

    /*
     * Socket instance
     */
    Socket  socket;

    /*
     * Event to register the bundled socket for
     */
    Event   event;

    /*
     * Context attachment for the bundled socket
     */
    Context context;

    /*
     * Constructor
     */
    this ( )
    {
        this.socket  = new Socket;
        this.context = new Context;
    }
}

/*
 * main method
 */

void main ( )
{
    /*
     * Step 1: Create an EpollSelector and the Socket instances
     */
    scope selector = new EpollSelector;

    SocketItem[5] sockitems;

    foreach (ref sockitem; sockitems)
    {
        sockitem = new SocketItem;
    }

    /*
     * Step 2: Set the sockets to non-blocking I/O and connect to
     * the server. Here we also define the event and output data.
     */
    foreach (i, sockitem; sockitems)
    {
        sockitem.socket.socket.blocking = false;
        sockitem.socket.connect("localhost", 4711);

        sockitem.event = sockitem.event.Write;

        sockitem.context.data = Format("Hello World from Socket "
                                       "{}!", i + 1).dup;
    }

    /*
     * Step 3: Register each of the Socket instances in the
     * EpollSelector instance for an event. Here we register the
     * socket with the bundled event and context attachment of
     * each sockitems element.
     */
    foreach (sockitem; sockitems)
    {
        selector.register(sockitem.socket, sockitem.event,
                          sockitem.context);
    }

    do
    {
        /*
         * Step 4: Let the EpollSelector instance wait for an
         * event to happen on some of the sockets. We have to
         * provide a TimeSpan timeout parameter; TimeSpan.max
         * disables timing out.
         */
        selector.select(TimeSpan.max);

       /* Step 5: Query which event actally happened on which
        * socket by retrieving and iterating over the Selection
        * Keys from the EpollSelector instance.
        * Note that EpollSelector.selectedSet may be null.
        */

        auto selection_set = selector.selectedSet;

        if (selection_set) foreach (selection_key; selection_set)
        {
            // - selection_key.conduit is one of our sockets which
            //      just became ready for writing;
            // - selection_key.events contains the events that
            //      happened on the socket. We expect Event.Write
            //      but it may also be an error event like
            //      Event.Error, Event.InvalidHandle or
            //      Event.Hangup.
            //      Event.Hangup would notify us that the server
            //      closed the socket connection.

            /*
             * Step 6: Write to or read from the socket(s). (In
             * the real world we would check selection_key.events
             * for an error event before doing anything.)
             */

            Socket socket = cast (Socket) selection_key.conduit;

            // Retrieve the socket connection context.

            SocketItem.Context context =
                cast(SocketItem.Context) selection_key.attachment;

            // Attempt to write all pending data and increase the
            // counter by the number of bytes actually written.
            // (In the real world we would first check if the
            // return value of write() is socket.Eof.)

            context.counter +=
                socket.write(context.data[context.counter .. $]);
        }
    }
    /*
     * TODO -- Steps 7 and 8: Unregister sockets whose counter
     * reached context.data.length from the selector and let this
     * loop stop when all sockets are unregistered.
     */
    while (true)
}

A loop which waits for events to happen and then handles these events, as the while loop in the example does, is often called an Event Loop.

Finally we have to unregister the sockets which are finished writing and terminate the event loop when no more socket is registered. Since EpollSelector.count() returns the number of registered conduits, we can just use this value as the loop condition.

     /*
     * Step 7 (moved to front): Let the event loop stop when all
     * sockets are unregistered.
     */
    while (selector.count)
    {
        /*
         * Step 4: Let the EpollSelector instance wait for an
         * event
         */
        selector.select(TimeSpan.max);

       /* Step 5: Query which event actally happened on which
        * socket.
        */

        auto selection_set = selector.selectedSet;

        if (selection_set) foreach (selection_key; selector)
        {
            /*
             * Step 6: Write to or read from the socket(s).
             */

            Socket socket = cast (Socket) selection_key.conduit;

            // Retrieve the socket connection context.

            SocketItem.Context context =
                cast(SocketItem.Context) selection_key.attachment;

            // Attempt to write all pending data and increase the
            // counter by the number of bytes actually written.

            context.counter +=
                socket.write(context.data[context.counter .. $]);

            /*
             * Step 8: If there is no more data to write for
             * socket, unregister it.
             */
            if (context.counter >= context.data.length)
            {
                selector.unregister(socket);
            }
        }
    }

That’s it! Now we are able to do one write operation on multiple, possibly a huge number of sockets simultaneously without the need of threads. Well, one might object, first the threaded code is much shorter and second with all that code we now can do one write; what about a subsequent read to receive the reply from the server?

Of course, that’s right. But consider the following: The epoll mechanism can easily handle hundreds of sockets without a significant resource usage overhead. When using threads, for each thread 1 MB of memory is allocated by default on Linux so you easily end up with a hundred MB of memory usage plus the memory that your code allocates. In addition, even if threads are easier to set up, they must be synchronized when using shared resources.

To make each socket read the response data from the server right after sending the request using the EpollSelector, as it is done in the thread-based example, the socket context class must be extended and a socket that finished writing must be re-registered for Event.Read. How this can be done will be the subject of the next post.

Native Javascript Ninjutsu: removeNode vs. removeChild

Dylan — Tue, 14 Sep 2010 09:33:30 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 5: Intonjutsu (escaping and concealment)

Recently there have been a few occasions in which I needed to remove element nodes from the DOM. In some cases the HTML layout needed to be restructured and in other cases I’ve been asked to make sure that various script tags were removed after their contents had been executed. Learning how to remove element nodes from the DOM can be very useful for a variety of reasons.

The most straightforward way to remove an HTML element is by using its id attribute to select it and then applying the removeNode() method to remove it from the DOM:

document.getElementById( 'the_element_id' ).removeNode( true );

Apparently you must pass the true parameter to the removeNode() method in order for it to work properly. In theory, this will work, but be aware that if the element you are trying to select does not exist then the JS will throw an error and cease execution immediately. This means that any following JS code will not be processed. In order to avoid this you’ll want to check if the element actually exists before attempting to remove it:

var the_element = document.getElementById( 'the_element_id' );

if ( the_element !== null )
{
    the_element.removeNode( true );
}

There is one major problem with this approach; it’s not cross-browser compatible at all. In my tests the removeNode() method only worked in IE and Opera, failing in FF, Google Chrome, and Safari. Due to this unfortunate lack of support we’re forced to rely on the removeChild() method:

var the_element = document.getElementById( 'the_element_id' );

if ( the_element !== null )
{
    the_element.parentNode.removeChild( the_element );
}

The above JS code begins by attempting to select the element by the given id value, storing the results to the_element variable. The code then checks this variable to see if the element actually exists or not. This is important to do because if you try to remove an element that does not exist your code will fail and any following JS will not be executed (as I’ve already explained above). If the element does exist then we must first select it’s parent node by using the parentNode() method, after which we can then remove the element itself by applying the removeChild() method and passing it the_element as a parameter. I know this may seem a bit convoluted, but this is the simplest – and most straightforward – way to remove an HTML element using purely native and fully cross-browser compatible JS.

I mentioned in the beginning of this tutorial that I’m sometimes asked to make sure all included JS code is removed from the HTML DOM as soon as it’s finished being executed. I accomplish this by storing the id attribute values of the script elements into a JS array and then passing this array to a for loop which removes them one by one:

var script_ids = [ 'first_script_id', 'second_script_id', 'third_script_id' ];

script_ids.reverse();

for ( var index in script_ids )
{
    var the_script = document.getElementById( script_ids[index] );

    if ( the_script !== null )
    {
        the_script.parentNode.removeChild( the_script );
    }
}

You’ll notice that I use the reverse() method on the script_ids array so that it starts from the last script. I do this because I want to remove them in the reverse order they were added. To further explain, I normally store the removal code in a globally accessible function which is defined in the first script I include. For this reason, the first script needs to be the last one I remove or the removal function well no longer be accessible (and thus the scripts won’t all be removed properly). Here’s a fuller, working example of this process:

It should be pretty clear what I’m doing in the above example. It’s important to note that you should wait until the DOM is fully loaded before you actually call the remove_all_scripts() method or you may run into serious trouble attempting to remove a node that only half exists! This is the reason why I’m relying on the onload attribute of the body element. You might also pay close attention to the fact that I’m using the push() method to add each script’s id to the script_ids array. I’m making sure this happens only once the respective script has actually been added to the page (if you imagine that some of these scripts might be dynamically added then this should begin to make a lot more sense). Alternatively you could specify the list of script ids that you presume to load, but to me it seems much cleaner and more elegant to do it like this.

I hope this tutorial has been helpful in providing you with a way to use native JS to remove HTML elements from the DOM. Stay tuned for next week’s discipline: DOMinating iframes.

Previous Disciplines
Discipline 1: AJAX with XHR
Discipline 2: Dynamic JS with PHP
Discipline 3: Include External JS
Discipline 4: Cookies and Variables

Native Javascript Ninjutsu: Cookies and Variables

Dylan — Mon, 06 Sep 2010 16:43:40 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 4: Chōhō (espionage)

Setting cookies with JS is a technique that I must frequently use in my front-end development missions. The quickest way to set a cookie is by giving it a name and a value:

document.cookie = 'test_cookie=test_value';

The code above is pretty self-explanatory, we set the document.cookie object to equal a name and a value. This is the minimum amount of information one needs to define when setting a cookie, though a cookie actually contains all the following details:

Name
Content/Value
Domain/Host
Expires
Path
Secure

When adding multiple parameters to the cookie we need to separate them with semicolons:

document.cookie = 'test_cookie=test_value; expires=Mon, 06 Sep 2010 11:38:29 GMT; path=/';

By default the cookie is set to expire at the end of the session, but in my work I typically want cookies to expire within one hour. I achieve this time restraint by doing the following:

var the_date = new Date();
var unix_time = the_date.getTime();
var expiration = unix_time + ( 3600 * 1000 );

the_date.setTime( expiration );

document.cookie = 'test_cookie=test_value; expires=' + the_date.toGMTString();

First I get the current date and time using the Date() object and set it to the_date variable. I then retrieve the Unix time version of the current date and time by using the getTime() method and save this to the unix_time variable. This stores the time in milliseconds so I can simply add one hour by doing some quick math (60 seconds * 60 minutes * 1000 to get milliseconds + the current Unix time = one hour from now). I then reset the_date variable’s time to that of the desired expiration. When we finally write the cookie itself we must make sure to use the GMT string to set the expiration in the proper format.

The domain parameter sets the domain or host on which the cookie is valid. If this isn’t explicitly set it’s default value will be the full domain of the page that executes the cookie-setting JS. If you would like to allow the cookie to be accessed on multiple subdomains then you must set the base domain using two periods:

document.cookie = 'test_cookie=test_value; domain=.testdomain.com';

It’s important to remember that for security reasons you cannot set a cookie to have a cross-domain value. For example, if your cookie is set using JS on www.testdomain.com then you cannot set the domain parameter to www.othertestdomain.com.

The path parameter is quite similar, as it’s also used to restrict where (on the server) the cookie is made available. By default the path is set to the root of the current domain (/), but it’s wise to explicitly set this yourself as some older browsers have been known to have problems if it isn’t set (such as Netscape).

document.cookie = 'test_cookie=test_value; path=/';

If you want to limit the cookie usage to a particular directory on your server you can explicitly set the path parameter:

document.cookie = 'test_cookie=test_value; path=/test_directory';

Lastly, the secure parameter allows you to specify whether or not the cookie needs to be accessed over secure (encrypted) connections:

document.cookie = 'test_cookie=test_value; secure=true';

Now let’s put it all together and set a cookie that has a name and a value, is accessible on all subdomains and directories of the current host but only over secure connections, and expires within one hour:

var the_date = new Date();
var unix_time = the_date.getTime();
var expiration = unix_time + ( 3600 * 1000 );

the_date.setTime( expiration );

document.cookie = 'test_cookie=test_value; domain=.testdomain.com; path=/; secure=true; expires=' + the_date.toGMTString();

That about covers how to set cookies, but obviously setting a cookie doesn’t help much if we don’t know how to read it’s value. Retrieving cookie data is a bit more complex when using purely native JS. You can use the document.cookie to return all the cookie values:

var cookies = document.cookie;
document.write( cookies );

Do that and you’ll notice that what you get is a string of cookie names and values separated by semicolons:

test_cookie=test_value;another_test_cookie=another_test_value;

This isn’t too helpful until we’ve parsed the information we want out of the string. What I typically do is use the match() method with a regular expression to store the cookie value into an array:

var cookie_array = document.cookie.match( '(^|;) ?cookie_name=([^;]*)(;|$)' );

if ( cookie_array )
{
    var cookie_value = cookie_array[2]
}

I won’t explain the regular expression I’ve used in great detail – as the topic of regular expressions could easily make up a whole series of blog articles by itself — but I will summarize by saying that it finds the value and stores it into the second element of an array. Once we set this array we must check if it actually exists before attempting to extract the cookie value. Note that this regular expression will only return the value of the first cookie whose name matches the cookie_name string, therefore if you have two cookies set with the same name you will not be able to retrieve both values using this method. This is a rare case and for that reason I’m not worried about the use of this technique.

To update a cookie you can simply rewrite it using the methods I’ve shown above, although it’s important to note that if you change the domain parameter of a cookie you will actually end up with two cookies. This is because the original is not automatically removed. The best way to remove cookies is to set their expires parameter to a past date, and all their other parameters to null (or an empty string). Even once you’ve done this the cookie may still appear to be available. Most web browsers need a restart to refresh (and delete) their cookie data completely.

Cookies are not the only way to store and retrieve user data, and often I’m sent out on a JS mission which involves extracting data from the page itself. It’s very common that third party scripts will save their variables outside of the global namespace and this makes these variables impossible to access directly. For example take the following HTML page:

Lets pretend that the above HTML page belongs to our client. Imagine that the script tag and its contents were added to the client’s webpage by a third party developer and that we’re not able to doctor or edit them whatsoever. Further imagine that all we’re allowed to do is include our own script after theirs. Because the_variable is defined within the scope of the set_variable() function we’re completely unable to access its value directly. We can however use some DOM parsing tricks to retrieve the value:

First we store all the script tags from the DOM into an object called scripts. Then we run a for loop on this object, checking if each node is an element (nodeType === 1). If the node is an element then we proceed by storing its innerHTML to a string called script_code and then use the match() method to run a fairly straight forward regular expression on the string. If the results aren’t null then we store the found value to our final variable. Be aware that it may be necessary to slightly modify the regular expression pattern used to match different situations (such as different variable names, single quotes versus double quotes around the value, spaces before and after the equals sign, et cetera).

I hope this article has been helpful in providing you with a way to use native JS to deal with cookies and non-global variables in your scripts. Stay tuned for next week’s discipline: removeNode vs. removeChild.

Previous Disciplines
Discipline 1: AJAX with XHR
Discipline 2: Dynamic JS with PHP
Discipline 3: Include External JS

Resources
The Unofficial Cookie FAQ
W3Schools’ Javascript Cookies Tutorial

Native Javascript Ninjutsu: Include External JS

Dylan — Tue, 31 Aug 2010 08:30:29 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 3: Shinobi-iri (stealth and entering methods)

Using native JS to include external scripts is pretty fun and easy to do. Here’s a simple example below:

As you can see, the HTML file has a script tag in it that contains an anonymous function. The anonymous function is wrapped in parentheses and followed by (); so that it will execute itself immediately. The reason we do this is so that the variables used are explicitly scoped within this function only. This prevents possible overlap from any other JS variables that may exist in the HTML. While this may seem to be a bit paranoid for smaller projects, I’m often asked to complete JS missions which involve including external scripts into third party, client-owned pages, and thus I have no control over – and sometimes no idea about – what may already exist in the page.

The anonymous function starts by creating a script element and saving it to a variable (s, in this case). The element is given a handful of attributes: an id, a type, an async value, and a src. These should all be pretty straightforward and self-explanatory, though the aync attribute is a bit interesting. The attribute sets the script to load asynchronously, and it works the same as the disabled and checked attributes, in that it’s value doesn’t matter, but only it’s presence holds meaning. If the async attribute exists it will automatically be considered to hold the value of true. Considering this, you don’t need to actually set the async attribute to any value, but instead you can simple define the attribute and it will work as expected. Keep in mind that the async attribute is a new HTML5 attribute and so it isn’t supported in all browsers yet.

After we set all the proper attributes for the element we then find the current script and insert our new script directly before it. Alternatively, if we’d like to insert our new script directly after the current script we can do the following:

If for some reason you can’t – or don’t want to – give the first script an id attribute then you can include the second script like so:

This will return an array of all the script tags in the DOM. It will then save the first element in this array to the variable x. Sometimes this will be the current script tag, but other times (depending entirely on the HTML structure of the page) this could be earlier script tags. The point of this method is to make sure the new JS is included to the page in an area that makes the most sense for the page owner. This can be very important when working with third party, client-owned websites.

Cross-browser compatibility is a big deal and even though it seems like everyone is browsing with JS enabled these days, I believe it’s still important that we make things work for those who aren’t. In most circumstances where I’m forced to use native JS to include scripts in websites it’s very likely that these scripts will be used to trigger server-side code. The end client may not always allow me to include server side code directly in their website itself, so a helpful workaround is to load the server side code into an img tag and wrap this in a noscript tag:

What this will do is execute the server side code instead of actually loading an image. Although this doesn’t allow you to execute JS, it does help to provide a work around and an alternative means of firing third party code when you need your solution to be as cross-browser compatible as possible.

There’s a third way to include JS that I would like to share with you and it involves the use of the HTML iframe tag. The initial JS would look like this:

The code in iframe-script.html would look like this:

There are times when it may make more sense to use an iframe, though I do not often find them that useful, and the above code has some problematic points. For starters, if the initial webpage you are working with has its scripts all in the head tag then you will be attempting to insert the iframe there, which is not a good idea. Furthermore, it is very difficult to pass JS variables and make calls to functions between the parent page and the child iframe within it. In fact, if these pages are either from different domains or even use different protocols (HTTP versus HTTPS) then it will be impossible to communicate between them using JS. To add to the problems the iframe tag is also not supported in all browsers. For these reasons I avoid the use of iframe tags whenever possible.

I hope this article has been helpful in providing you with a way to use native JS to include external scripts into your pages. Stay tuned for next week’s discipline: Cookies and Variables.

Previous Disciplines
Discipline 1: AJAX with XHR
Discipline 2: Dynamic JS with PHP

Native Javascript Ninjutsu: Dynamic JS with PHP

Dylan — Mon, 23 Aug 2010 17:10:39 +0000

Sensei Says (dark ages, to dojos, to disciplines)

Discipline 2: Hensōjutsu (disguise and impersonation)

I mostly use static scripts when working with JS, though recently I’ve completed quite a few missions that involved the use of dynamic scripts. Dynamic scripting allows your JS to be changed based on the server side or client side situation (or both); different scenarios call for different measures, different variables, and sometimes even completely different code altogether.

Let’s begin with variables. Passing variables from PHP to internal JS is very simple:

I’ve shown two examples above, the latter of which passes a string value to JS. It’s important to note that you must include quotes around the PHP block. This insures that the outputted value is properly wrapped in quotes, otherwise it could very well break your JS.

It’s also important to note that the above code relies on PHP to create and pass the values to the JS variables, and therefore the file itself must be parsed as a PHP file by the server. This is most easily done by making sure the file has a .php extension (suffix). There will certainly be some cases in which you don’t have the option of changing the main webpage you are working with to a PHP file. In that case there is an alternative solution, but it only works with external JS:

The above HTML code includes an external PHP script that contains the following code:

This echoes the dynamic JS that should be included into the HTML page. The PHP values are passed directly in the echo string. This works because we’re using double quotes around the echo string and I think it’s one of the most convenient ways to store PHP values in JS variables. If you need to use double quotes within the JS code itself then you must either escape those quotes with a back slash or echo a list of strings/values allowing you to switch to single quotes:

The latter approach can be quite hard to read, and for this reason I typically stick with escaping double quotes whenever I’m required to use them. When you need to echo multiple lines of JS you can do so by simply putting lines break in the echo string:

Although this has a purely aesthetic effect on the code, I find it to be invaluable in keeping my JS readable, especially considering that the code itself is stored inside of a PHP string (and thus I lose the benefit of syntax highlighting that would normally be applied within my code editor).

Very often my front end missions involve passing values from the client side to the server side. When including an external script you can add query parameters to the source URL and have these values passed by PHP to the echoed JS:

The above HTML code includes an external PHP script that contains the following code:

The PHP code retrieves the value from the header GET method array and echoes it with the JS back to the HTML page.

Earlier this summer I finished my first Facebook Application, in which my work required me to pass an entire PHP array to be stored as a JS array. The technique I used may be helpful in illustrating that you can achieve quite a lot with a bit of creativity and understanding of both languages:

The above code prepares a new array in JS and then runs a PHP foreach loop. Each time the loop is executed the line of JS inside of it is added to the page, complete with the properly echoed PHP values. Once the server side processing is complete, the client side will execute all the prepared lines of JS and you should have an array that is identical to your PHP original; the same keys, and their same values.

By now you should be able to imagine the variety of ways that dynamic JS can be useful. You can use these same techniques to add more dynamic functionality to your front end projects. Now go out there, practice your native, dynamic JS in the field, and stay tuned for next week’s discipline: Including External JS.

Previous Disciplines
Discipline 1: AJAX with XHR