D3.js Tips and Tricks: d3.js Elements

The following post is a portion of the D3 Tips and Tricks book which is free to download. To use this post in context, consider it with the others in the blog or just download the the book as a pdf / epub or mobi .

----------------------------------------------------------

d3.js Elements

We will begin by describing what we mean when we talk about an ‘element’.

There is considerable scope for confusion when talking about elements on a web page. Are we talking about HTML elements, SVG elements or something different?

In fact we are going to be describing a subset of SVG elements. Specifically those that are described in the d3.js API reference (since that’s why we’re here right?). These are a collection of common shapes and objects which include circles, ellipses, rectangles, lines, polylines, polygons, text and paths.

“Text?” I hear you say. “Doesn't sound like a shape.” I suppose it depends on how you think of it. We can use text in different ways in d3, but for this particular exercise we can regard text as an SVG element.

Circle

A circle is a simple SVG shape that is described by three required attributes.

cx: The position of the centre of the circle in the x direction (left / right) measured from the left side of the screen.
cy: The position of the centre of the circle in the y direction (up / down) measured from the top of the screen.
r: The radius of the circle from the cx, cy position to the perimeter of the circle.

The following is an example of the code section required to draw a circle in conjunction with the HTML file outlined at the start of this chapter;

holder.append("circle")        // attach a circle
    .attr("cx", 200)           // position the x-center
    .attr("cy", 100)           // position the y-center
    .attr("r", 50);            // set the radius

This will produce a circle as follows;

Circle

The centre of the circle is at x = 200 and y = 100 and the radius is 50 pixels.

Ellipse

An ellipse is described by four required attributes;

cx: The position of the centre of the ellipse in the x direction (left / right) measured from the left side of the screen.
cy: The position of the centre of the ellipse in the y direction (up / down) measured from the top of the screen.
rx: The radius of the ellipse in the x dimension from the cx, cy position to the perimeter of the ellipse.
ry: The radius of the ellipse in the y dimension from the cx, cy position to the perimeter of the ellipse.

The following is an example of the code section required to draw an ellipse in conjunction with the HTML file outlined at the start of this chapter;

holder.append("ellipse")       // attach an ellipse
    .attr("cx", 200)           // position the x-centre
    .attr("cy", 100)           // position the y-centre
    .attr("rx", 100)           // set the x radius
    .attr("ry", 50);           // set the y radius

This will produce an ellipse as follows;

Ellipse

The centre of the ellipse is at x = 200 and y = 100 and the radius is 50 pixels vertically and 100 pixels horizontally.

Rectangle

A rectangle is described by four required attributes and two optional ones;

x: The position on the x axis of the left hand side of the rectangle (required).
y: The position on the y axis of the top of the rectangle (required).
width: the width (in pixels) of the rectangle (required).
height: the height (in pixels) of the rectangle (required).
rx: The radius curve of the corner of the rectangle in the x dimension (optional).
ry: The radius curve of the corner of the rectangle in the y dimension (optional).

The following is an example of the code section required to draw a rectangle (using only the required attributes) in conjunction with the HTML file outlined at the start of this chapter;

holder.append("rect")       // attach a rectangle
    .attr("x", 100)         // position the left of the rectangle
    .attr("y", 50)          // position the top of the rectangle
    .attr("height", 100)    // set the height
    .attr("width", 200);    // set the width

This will produce a rectangle as follows;

Rectangle

The top left corner of the rectangle is at 100, 50 and the rectangle is 200 pixels wide and 100 pixels high.

The following code section includes the optional attributes for the curved corners;

holder.append("rect")       // attach a rectangle
    .attr("x", 100)         // position the left of the rectangle
    .attr("y", 50)          // position the top of the rectangle
    .attr("height", 100)    // set the height
    .attr("width", 200)     // set the width
    .attr("rx", 10)         // set the x corner curve radius
    .attr("ry", 10);        // set the y corner curve radius

This will produce a rectangle (with curved corners) as follows;

Rectangle with curved corners

The corners are curved with radii in the x and y direction of 10 pixels.

Line

A line is a simple line between two points and is described by four required attributes.

x1: The x position of the first end of the line as measured from the left of the screen.
y1: The y position of the first end of the line as measured from the top of the screen.
x2: The x position of the second end of the line as measured from the left of the screen.
y2: The y position of the second end of the line as measured from the top of the screen.

The following is an example of the code section required to draw a line in conjunction with the HTML file outlined at the start of this chapter. A notable addition to this code is the style declaration. In this case the line has no colour and this can be added with the stroke style which applies a colour to a line;

holder.append("line")          // attach a line
    .style("stroke", "black")  // colour the line
    .attr("x1", 100)     // x position of the first end of the line
    .attr("y1", 50)      // y position of the first end of the line
    .attr("x2", 300)     // x position of the second end of the line
    .attr("y2", 150);    // y position of the second end of the line

This will produce a line as follows;

Line

The line extends from the point 100,50 to 300,150.

Polyline

A polyline is a sequence of connected lines described with a single attribute. The d3.js wiki rightly makes the point that “it is typically more convenient and flexible to use the d3.svg.line path generator in conjunction with a path element”. So while drawing a polyline using this method may be possible, bear in mind that depending on your application, there may be a better way.

points: The points attribute is a list of x,y coordinates that are the locations of the connecting points of the polyline.

The following is an example of the code section required to draw a polyline in conjunction with the HTML file outlined at the start of this chapter. A notable addition to this code are the style declarations. In this case the line of the polyline has no colour and this can be added with the stroke style which applies the colour black to a line. Likewise the area that is bounded by the polyline will be automatically filled with black unless we explicitly tell the object not to. This is achieved in this example by addition of the fill style to none.

holder.append("polyline")      // attach a polyline
    .style("stroke", "black")  // colour the line
    .style("fill", "none")     // remove any fill colour
    .attr("points", "100,50, 200,150, 300,50");  // x,y points

This will produce a polyline as follows;

Polyline

The polyline extends from the point 100,50 to 200,150 to 300,50.

Polygon

A polygon is a sequence of connected lines which form a closed shape described with a single attribute. Thed3.js wiki rightly makes the point that “it is typically more convenient and flexible to use the d3.svg.line path generator in conjunction with a path element”. So while drawing a polygon using this method may be possible, bear in mind that depending on your application, there may be a better way.

points: The points attribute is a list of x,y coordinates that are the locations of the connecting points of the polygon. The last point is in turn connected to the first point.

The following is an example of the code section required to draw a polygon in conjunction with the HTML file outlined at the start of this chapter. A notable addition to this code are the style declarations. In this case the line of the polygon has no colour and this can be added with the stroke style which applies the colour black to a line. Likewise the area that is bounded by the polygon will be automatically filled with black unless we explicitly tell the object not to. This is achieved in this example by addition of the fill style to none.

holder.append("polygon")       // attach a polygon
    .style("stroke", "black")  // colour the line
    .style("fill", "none")     // remove any fill colour
    .attr("points", "100,50, 200,150, 300,50");  // x,y points 

This will produce a polygon as follows;

Polyline

The polygon extends from the point 100,50 to 200,150 to 300,50 and then back to 100,50.

Path

A path is an outline of an SVG shape which is described with a ‘mini-language’ inside a single attribute.

d: This attribute is a list of instructions that allow a shape to be drawn in a complex way using a ‘mini-language’ of commands. These commands are written in a shorthand of single letters such as M-moveto,Z-closepath, L-lineto, C-curveto. These commands can be absolute (normally designated by capital letters) or relative (lower case).

The following is an example of the code section required to draw a triangle in conjunction with the HTML file outlined at the start of this chapter. A notable addition to this code are the style declarations. In this case the line of the path has no colour and this can be added with the stroke style which applies the colour black to a line. Likewise the area that is bounded by the path will be automatically filled with black unless we explicitly tell the object not to. This is achieved in this example by addition of the fill style to none.

holder.append("path")          // attach a path
    .style("stroke", "black")  // colour the line
    .style("fill", "none")     // remove any fill colour
    .attr("d", "M 100,50, L 200,150, L 300,50 Z");  // path commands 

This will produce a path as follows;

Path

The path mini-language first moves (M) to 100,50 then draws a line (L) to 200,150 then draws another line (L) to 300,50 then closes the path (Z).

Text

A text element is an SVG object which is shaped as text. It is described by two required attributes and three optional ones.

x: This attribute designates the anchor point location for the text in the x dimension (required).
y: This attribute designates the anchor point location for the text in the y dimension (required).
dx: This attribute designates the offset of the text from the anchor point in the x dimension (optional). There are several different sets of units that can be used to designated the offset of the text from an anchor point. These include em which is a scalable unit (used in these examples), px (pixels), pt (points (kind of like pixels)) and 5 (percent (scalable and kind of like em))
dy: This attribute designates the offset of the text from the anchor point in the y dimension (optional).
text-anchor: This attribute controls the horizontal text alignment (optional). It has three values; start (left aligned), middle (centre aligned) and end (right aligned).

The following is an example of the code section required to draw the text “Hello World” in conjunction with the HTML file outlined at the start of this chapter. A notable addition to this code is the style declaration which applies a black fill to the text. Additionally there is the declaration .text which defines the text that will be displayed.

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text 
    .text("Hello World");     // define the text to display 

This will produce text as follows;

Text

It can be seen from the image that the anchor point for the text is at 200,100 and that the text is positioned with this anchor point at the bottom, left of the text.

The following examples will demonstrate the various options for positioning and aligning text so that you can arrange it correctly.

ANCHOR AT THE BOTTOM, MIDDLE OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("text-anchor", "middle") // set anchor y justification 
    .text("Hello World");          // define the text to display

This will produce text as follows;

Text: Anchored Bottom-middle

ANCHOR AT THE BOTTOM, RIGHT OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("text-anchor", "end")  // set anchor y justification 
    .text("Hello World");        // define the text to display

This will produce text as follows;

Text: Anchored Bottom-Right

ANCHOR AT THE MIDDLE, LEFT OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".35em")           // set offset y position
    .attr("text-anchor", "start")  // set anchor y justification 
    .text("Hello World");          // define the text to display

This will produce text as follows;

Text: Anchored Middle-Left

ANCHOR IN THE MIDDLE, CENTRE OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".35em")           // set offset y position
    .attr("text-anchor", "middle") // set anchor y justification 
    .text("Hello World");          // define the text to display

This will produce text as follows;

Text: Anchored Middle-Centre

ANCHOR IN THE MIDDLE, RIGHT OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".35em")         // set offset y position
    .attr("text-anchor", "end")  // set anchor y justification 
    .text("Hello World");        // define the text to display

This will produce text as follows;

Text: Anchored Middle-Right

ANCHOR AT THE TOP, LEFT OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".71em")           // set offset y position
    .attr("text-anchor", "start")  // set anchor y justification 
    .text("Hello World");          // define the text to display

This will produce text as follows;

Text: Anchored Top-Left

ANCHOR AT THE TOP, MIDDLE OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".71em")            // set offset y position
    .attr("text-anchor", "middle")  // set anchor y justification 
    .text("Hello World");           // define the text to display

This will produce text as follows;

Text: Anchored Top-Middle

ANCHOR AT THE TOP, RIGHT OF THE TEXT:

holder.append("text")         // append text
    .style("fill", "black")   // fill the text with the colour black
    .attr("x", 200)           // set x position of left side of text
    .attr("y", 100)           // set y position of bottom of text
    .attr("dy", ".71em")          // set offset y position
    .attr("text-anchor", "end")   // set anchor y justification 
    .text("Hello World");         // define the text to display

This will produce text as follows;

Text: Anchored Top-Right

The description above (and heaps of other stuff) is in the D3 Tips and Tricks book that can be downloaded for free (or donate if you really want to :-)).