epubjs
Version:
Render ePub documents in the browser, across many devices
84 lines (83 loc) • 13.5 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg"><head><title>Chapter 4. Setup</title><link rel="stylesheet" type="text/css" href="core.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"/><link rel="up" href="index.html" title="Interactive Data Visualization for the Web"/><link rel="prev" href="ch03.html" title="Chapter 3. Technology Fundamentals"/><link rel="next" href="ch05.html" title="Chapter 5. Data"/></head><body><section class="chapter" title="Chapter 4. Setup" epub:type="chapter" id="setup-chapter4"><div class="titlepage"><div><div><h2 class="title">Chapter 4. Setup</h2></div></div></div><p>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.<a id="I_indexterm4_id295602" class="indexterm"/></p><div class="sect1" title="Downloading D3"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="_downloading_d3">Downloading D3</h2></div></div></div><p>Start by creating a new folder for your project. Call it whatever you
like, but maybe something like <span class="emphasis"><em>project-folder</em></span>.</p><p>Within that folder, I recommend creating a subfolder called <span class="emphasis"><em>d3</em></span>. Then
download the latest version of D3 into that subfolder. <a class="ulink" href="http://d3js.org/d3.v3.zip" target="_top">Download the latest version of D3 as a ZIP file</a>, and then decompress the ZIP file. As of this writing, the current version of D3 is 3.0.6.</p><p>D3 is also provided in a “minified” version,
<a class="ulink" href="http://d3js.org/d3.v3.min.js" target="_top"><span class="emphasis"><em>d3.v3.min.js</em></span></a>, 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 regular 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.</p><p>A third option is to download the entire D3 repository, which
gives you not just the JavaScript files, but also all of the component
source code. You can <a class="ulink" href="https://github.com/mbostock/d3" target="_top">browse the
repository contents</a> first, or just
<a class="ulink" href="https://github.com/mbostock/d3/zipball/master" target="_top">download the whole thing
as a compressed ZIP file</a>. Of course, once you’ve downloaded everything,
make a copy of the file <span class="emphasis"><em>d3.v3.js</em></span> and move that into
<span class="emphasis"><em>project-folder/d3/</em></span>.</p></div><div class="sect1" title="Referencing D3"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="_referencing_d3">Referencing D3</h2></div></div></div><p>Now create a simple HTML page within your project folder named
<span class="emphasis"><em>index.html</em></span>. 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 might be easier if you use an editor
designed specifically for working with code, like Coda, Espresso, or
Sublime Text (among many, many others).<a id="I_indexterm4_id295710" class="indexterm"/></p><p>If your editor gives you the option to set the file encoding, choose
Unicode (UTF-8).</p><p>Your folder structure should now look something like this:</p><pre class="screen">project-folder/
d3/
d3.v3.js
d3.v3.min.js (optional)
index.html</pre><p>Paste the following into your new HTML file:</p><a id="I_programlisting4_id295736"/><pre class="programlisting"><code class="cp"><!DOCTYPE html></code>
<code class="nt"><html</code> <code class="na">lang=</code><code class="s">"en"</code><code class="nt">></code>
<code class="nt"><head></code>
<code class="nt"><meta</code> <code class="na">charset=</code><code class="s">"utf-8"</code><code class="nt">></code>
<code class="nt"><title></code>D3 Page Template<code class="nt"></title></code>
<code class="nt"><script </code><code class="na">type=</code><code class="s">"text/javascript"</code> <code class="na">src=</code><code class="s">"d3/d3.v3.js"</code><code class="nt">></script></code>
<code class="nt"></head></code>
<code class="nt"><body></code>
<code class="nt"><script </code><code class="na">type=</code><code class="s">"text/javascript"</code><code class="nt">></code>
<code class="c1">// Your beautiful D3 code will go here</code>
<code class="nt"></script></code>
<code class="nt"></body></code>
<code class="nt"></html></code></pre><p>Or, rather than go through all that manual labor, you could just download the sample code files (see <a class="xref" href="ch01.html" title="Chapter 1. Introduction">Chapter 1</a> for instructions), and take a look at <span class="emphasis"><em>01_empty_page_template.html</em></span>, which contains almost exactly the same code. (The <code class="literal">src</code> path to D3 is different in my version.)<a id="I_indexterm4_id295761" class="indexterm"/></p><p>Here are a few things to note about this template:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
The <code class="literal">meta</code> tag identifies the encoding for this file as <code class="literal">utf-8</code>,
which is needed to ensure that the browser can parse D3’s functions and
data properly.
</li><li class="listitem">
The first <code class="literal">script</code> tag sets the reference to <span class="emphasis"><em>d3.v3.js</em></span>. You should
edit this file path as needed if you’re using the minified version of D3
or decided to locate <span class="emphasis"><em>d3.v3.js</em></span> somewhere other than the <span class="emphasis"><em>d3</em></span> directory.
</li><li class="listitem">
The second <code class="literal">script</code> tag, in the <code class="literal">body</code>, is where you will soon key
in all your beautiful code. And it will be beautiful.
</li></ul></div><p>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.<a id="I_indexterm4_id295836" class="indexterm"/></p></div><div class="sect1" title="Setting Up a Web Server"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="_setting_up_a_web_server">Setting Up a Web Server</h2></div></div></div><p>In some cases, you can view local HTML files directly in your web browser. However, some browsers have restrictions that prevent them from loading local files via JavaScript, for security reasons. That means if your D3 code is trying to pull in any external datafiles (like CSVs or JSON), it will fail with no good explanation. This isn’t D3’s fault; it’s a browser feature that prevents loading of scripts and other external files from third-party, untrusted websites.<a id="I_indexterm4_id295864" class="indexterm"/><a id="I_indexterm4_id295872" class="indexterm"/></p><p>For this reason, it is much more reliable to load your page via a web
server. Although you <span class="emphasis"><em>could</em></span> use a remote web server, it is much, 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.</p><p>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.</p><div class="sect2" title="Terminal with Python"><div class="titlepage"><div><div><h3 class="title" id="_terminal_with_python">Terminal with Python</h3></div></div></div><p>If you’re using Mac OS X or Linux, then you already have Python installed. As long as you’re comfortable entering commands in the terminal, then running a miniserver with Python is definitely the quickest option. (If you’re on Windows, you’ll need to install Python first.)</p><p>To use Python, you’ll need to open up a terminal window on your system. On a Mac, open the Terminal application. You can find it in the Utilities folder, or by typing <span class="strong"><strong><code class="literal">Terminal</code></strong></span> 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.</p><p>To run a Python web server:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
Open up a new terminal window.
</li><li class="listitem">
Via the command line, navigate into the directory that you want served. For example, if your project folder is in your Desktop folder on your Mac, you could type: <span class="strong"><strong><code class="literal">cd ~/Desktop/project-folder</code></strong></span>.
</li><li class="listitem">
Enter <span class="strong"><strong><code class="literal">python -m SimpleHTTPServer 8888 &</code></strong></span>.
</li></ol></div><p>(This will work with Python version 2.x, but in Python versions 3.0 and newer, <code class="literal">SimpleHTTPServer</code> has been removed. For Python 3.x, just replace <code class="literal">SimpleHTTPServer</code> with <code class="literal">http.server</code> in the command.)</p><p>This will activate the server on port <code class="literal">8888</code>. Switch back to your web browser and visit the following URL: <a class="ulink" href="http://localhost:8888/" target="_top">http://localhost:8888/</a>. Yes, instead of <span class="emphasis"><em>www.something.com</em></span>, you just use <span class="emphasis"><em>localhost</em></span>, which tells the browser to request a page from <span class="emphasis"><em>this machine</em></span>.</p><p>You should see the blank “D3 Page Template” page. Given that <code class="literal">body</code> 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.</p></div><div class="sect2" title="MAMP, WAMP, and LAMP"><div class="titlepage"><div><div><h3 class="title" id="_mamp_wamp_and_lamp">MAMP, WAMP, and LAMP</h3></div></div></div><p>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.</p><p>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.</p><p>On a Mac, you can download and install <a class="ulink" href="http://mamp.info/en/" target="_top">MAMP</a> or
<a class="ulink" href="http://bit.ly/W8RQa6" target="_top">XAMPP for Mac</a>.</p><p>The Windows equivalents are <a class="ulink" href="http://www.wampserver.com/en/" target="_top">WampServer</a>
and <a class="ulink" href="http://bit.ly/ZEGJq1" target="_top">XAMPP for Windows</a>.</p><p>If you use Linux, then all of this is probably already installed on your
machine, but you could still download <a class="ulink" href="http://bit.ly/126txfk" target="_top">XAMPP for Linux</a>.</p><p>Installation for each of these packages varies somewhat, so follow the
documentation carefully. (I’ve found MAMP to be the easiest to install.)</p><p>Each package will designate one folder as the web server directory, so
only the files <span class="emphasis"><em>within that folder</em></span> will be served. You should find out
what that folder is, and move your D3 <span class="emphasis"><em>project-folder</em></span> into it.</p><p>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 <span class="emphasis"><em>localhost</em></span>, as in the following: <a class="ulink" href="http://localhost/" target="_top">http://localhost/</a>. Depending on your AMP configuration, you might need to append a port number to the URL,
as in the following: <a class="ulink" href="http://localhost:8888/" target="_top">http://localhost:8888/</a>.</p><p>If the server’s port number is <code class="literal">8888</code> and your project folder is called
<span class="emphasis"><em>project-folder</em></span>, then you could view your D3 template page by going to <a class="ulink" href="http://localhost:8888/project-folder/" target="_top">http://localhost:8888/project-folder/</a>.</p></div><div class="sect2" title="Diving In"><div class="titlepage"><div><div><h3 class="title" id="_diving_in">Diving In</h3></div></div></div><p>All set? Great! Let’s start working with data.</p></div></div></section></body></html>