Understanding DOM Element Selections

An DOM Element Selection is an object that allows you to manipulate one or more DOM elements using a concise, easy-to-use API. Element selections may be obtained by calling the thinkmap.select() method or the thinkmap.selectAll() methods. Let's look at a simple example. Let's say you wanted to append a <div> to the body that contained the phrase "hello world":

// without using Element Selections
var div = document.createElement('div');
div.appendChild( document.createTextNode('hello world') );
document.body.appendChild(div);

// using element selections
thinkmap.select('body').append('div').text('hello world');	

Select and SelectAll

Let's look at the difference between select and selectAll. Calling select() selects the first element that matches the criteria where selectAll() selects all the elements that match the criteria.

So, if we wanted to change the color of every <h3> element on a page, we would do the following:

	thinkmap.selectAll('h3').style('color','#ff0000');

Arguments to select and selectAll

You can pass any valid CSS 3 selector string to select() and selectAll(). Let's look at some examples:

	// remove all <h3> tags from the page
	thinkmap.selectAll('h3').remove();
	
	// select all <p> tags inside of a <div> with the "section" class
	// and add the CSS class "selected" to them
	thinkmap.selectAll('div.section p').addClass('selected');
	
	// select the element with the id "resetButton" and attach an event listener
	thinkmap.select('#resetButton').on('click',function(){ alert('reset');} );

Transitioning Selections

Element selections also make it easy to perform animated transitions. Let's see how that's done:

	// fade all <h3> tags to red, over 5 seconds
	thinkmap.selectAll('h3').transition().style('color','#ff0000').duration(5000);

As you can see, doing animations is as easy as adding the transition() call. The transition method just returns a new Element Selection that is an exact copy of the current selection, but it just performs its operations over time. That time can be set using the duration() method. You also can use the delay() method and the easing() methods to finely tune the animation. Transitioned selections also implement the thinkmap.async.Future interface, so you can be notified when they are complete.

Element Selections and Display Templates

In Thinkmap, the most common place you will encounter Element Selections is when you are creating templates for the Display. Let's take a look:

	var display = new thinkmap.display.Display(document.getElementById('myThinkmap'));
	
	// here we define a template to be used when nodes are added to the screen
	display.template('node').as(function(selection,node) {
	    // Selection here is an Element Selection that contains the SVG <g>
	    // element that represents the node.  We append a circle to the
	    // <g> element, with a "r" (radius) attribute of "4px" 
		selection.append('circle').attr('r','4px');
	});
	

Further Study

More information is available about Element Selections if you read the API Documentation.