Getting set up with D3 is pretty straightforward—a simple matter of downloading the latest version, creating an empty page in which to write your code, and, finally, setting up a local web server.
Then place the latest version of D3 into that folder. Go to https://d3js.org, click the link to download the latest version of D3 as a ZIP file, and then decompress the ZIP file. As of this writing, the current version of D3 is 4.5.0. Move the file d3.js into your new project folder.
In that folder, you’ll also see d3.min.js, a “minified” version from which whitespace has been removed for smaller file sizes and faster load times. The functionality is the same, but typically you’d use the standard version while working on a project (for friendlier debugging), and then switch to the minified version once you’ve launched the project publicly (for optimized load times). The choice is up to you, but in this book, I use the standard version.
Now create a simple HTML page within your project folder named index.html. Remember, HTML documents are just plain-text files, so you can use the text editor of your choice. Free editors like TextEdit and Notepad are fine, but your life will be easier if you use an editor designed specifically for working with code, like Atom, Brackets, or Sublime Text (among many others).
If your editor gives you the option to set the file encoding, choose Unicode (UTF-8).
Your folder structure should now look something like this:
project-folder/ d3.js d3.min.js (optional) index.html
Paste the following into your new HTML file:
<title>D3 Page Template
// Your beautiful D3 code will go here
Or, rather than go through all that manual labor, you could just download the sample code files (see Chapter 1 for instructions), and take a look at 01_empty_page_template.html, which contains almost exactly the same code. (The
src path to D3 is different in my version.)
Here are a few things to note about this template:
meta tag identifies the encoding for this file as
which is needed to ensure that the browser can parse D3’s functions and
script tag sets the reference to d3.js. You should
edit this file path as needed if you’re using the minified version of D3
or decided to locate d3.js somewhere other than the project-folder directory.
script tag, in the
body, is where you will soon key
in all your beautiful code. And it will be beautiful.
Done! Your D3 template files and folders are all set up. You might want to make a copy of this template for each new project down the line.
For this reason, it is more reliable to load your page via a web server. Although you could use a remote web server, it is much faster to store and host everything locally (meaning, on the same computer, the one right in front of you). It is a strange idea, to use your local computer to host and serve files to itself, but you can think about it as the different programs talking to each other: the browser program requests files from the server program, which responds by serving them back.
The good news is that it’s quite easy to get a local server up and running. Here are a couple of ways to do that.
If you’re using macOS X or Linux, then you already have Python installed. As long as you’re comfortable entering commands in the terminal, running a small Python server is definitely the quickest option. (If you’re on Windows, you’ll need to install Python first.)
To use Python, you’ll need to open a terminal window on your system. On a Mac, open the Terminal application. You can find it in the Utilities folder, or by typing
Terminal into Spotlight (the magnifying glass menu item in the upper-right corner of your screen). Linux users are born knowing how to open a terminal window, so I won’t waste your time explaining it here.
To run a Python web server:
Open a new terminal window.
Via the command line, navigate to the directory that you want served. For example, if your project folder is in your Desktop folder on your Mac, you could type:
python -m SimpleHTTPServer 8888 &.
(This will work with Python version 2.x, but in Python versions 3.x and newer,
SimpleHTTPServer has been removed. For Python 3.x, just replace
http.server in the command.)
This will activate the server on port
8888. Switch back to your web browser and visit the following URL: http://localhost:8888/. Yes, instead of www.something.com, you just use localhost, which tells the browser to request a page from this machine.
You should see the blank “D3 Page Template” page. Given that the
body of the page is empty, it won’t look like much. Select View Source, and you should see the contents of our HTML template page.
This option takes longer, but is best if you like dragging and dropping to install things, and want to avoid scary things like the terminal.
All of the AMPs in this section stand for Apache (the web server software), MySQL (popular database software), and PHP (a popular web scripting language). We are really interested only in Apache, the web server, but it usually comes bundled with the other two, as they all work well together.
If you use Linux, then all of this is probably already installed on your machine, but you could still download XAMPP for Linux.
Installation for each of these packages varies somewhat, so follow the documentation carefully. (I’ve found MAMP to be the easiest to install.)
Each package will designate one folder as the web server directory, so only the files within that folder will be served. You should find out what that folder is, and move your D3 project-folder into it.
Once the local server is up and running, you can view any pages within the server directory by opening a browser (on the same computer, of course) and pointing it to localhost, as in the following: http://localhost/. Depending on your AMP configuration, you might need to append a port number to the URL, as in the following: http://localhost:8888/.
If the server’s port number is
8888 and your project folder is called
project-folder, then you could view your D3 template page by going to http://localhost:8888/project-folder/.