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');
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');
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');} );
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.
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');
});
More information is available about Element Selections if you read the API Documentation.