Command Palette

Search for a command to run...

Hectal
PHASE 0Beginner ~20 min· topic 4 of 7

Topic 0.4

Where You Write Code

In one line

You write code in two places in this course: the live editor on these pages (nothing to install), and from now on also one file on your own computer, lumen-dashboard/index.html, opened by double-clicking it. In Phase 4 the project moves to a small local server.

0/7 · 0%

Think of it like this

Learning to cook. First you cook in a teaching kitchen where everything is laid out and the teacher can see your pan. Then you cook the same dish at home, in your own kitchen. The editor on this page is the teaching kitchen; your index.html is your kitchen at home.

Words you'll meet

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

live editor
The code box on these pages with Run, a preview and a Console. It runs your code in a safe, separate frame.
preview
The page your code produces, shown next to the code.
Console
A panel that shows what your code prints with console.log, and every error, in red.
VS Code
Visual Studio Code: a free code editor from Microsoft for Windows, macOS and Linux.
developer tools
The browser's built-in tools for inspecting a page: the Elements tree, the Console, the Network list and more. Opened with F12 or Cmd + Option + I.
file extension
The end of a file name after the dot, such as .html. It tells the computer which program opens the file.
default size
The size an element gets when you don't give one. For an inline <svg> it is 300 × 150 pixels.

Step by step

01Run something and read the Console

Press Run on the first example. The first three lines print normally: a string, a sum, an array. The fourth line has a typo on purpose (ride instead of rides), and the Console shows Uncaught ReferenceError: ride is not defined in red.

The last line never prints: an uncaught error stops the rest of the script. When a chart stops halfway, look for the first red line in the Console; everything after it never ran.

02Make your folder and your first file

Create a folder named lumen-dashboard somewhere easy to find (your Documents folder is fine). Open it in VS Code with File → Open Folder…, create index.html, and paste the code below into it. Save with Ctrl + S (Windows/Linux) or Cmd + S (macOS).

lumen-dashboard/index.htmlwhole filehtml
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Lumen Bikes dashboard</title>
</head>
<body>
  <h1>Lumen Bikes</h1>
  <svg width="300" height="60" role="img" aria-label="My first bar">
    <rect x="0" y="10" width="200" height="40" fill="#2a9d8f"></rect>
  </svg>
  <script>
    console.log("It works! The page has", document.querySelectorAll("rect").length, "bar.");
  </script>
</body>
</html>

03Open it and check the console

Double-click index.html in your file manager. Your browser opens it, and the address bar starts with file://. You should see the heading Lumen Bikes and one green bar.

Open the developer tools (F12, or Cmd + Option + I on macOS) and click Console. You should see It works! The page has 1 bar. If you see the code as plain text instead of a page, the file is really called index.html.txt: show file extensions and rename it.

04Edit, save, reload

Change the bar's width="200" to width="120", save, and reload the browser tab (F5, or Cmd + R). The bar shrinks. This loop (edit, save, reload, check the console) is how you will work until Phase 4, where Vite reloads the page for you as soon as you save.

05Meet the default size

The second example has an <svg> with no size and two circles: one at x = 40, one at x = 330. Only the first is visible. The Console shows why: the SVG is 300 × 150, so a circle at x = 330 is outside it. The circle still exists in the page (there are 2 circles), it is only cut off. Topic 1.1 explains the SVG viewport.

Try it yourself

  1. 1

    Fix the typo

    In the first example, change console.log(ride); to console.log(rides); and press Run. All five lines print, including This line never runs…, which now does run.

  2. 2

    Give the SVG a size

    In the second example, add width="400" height="100" to the <svg> tag. The Console now prints Width: 400 Height: 100 and the orange circle appears.

  3. 3

    Find the line number on your computer

    Paste the first example's code into a <script> tag at the end of your index.html, save and reload. In the browser's own Console, the red error now ends with the file name and line number (for example index.html:20). Click it: the browser jumps to the exact line.

Code & diagrams

The Console: prints and errors New tab

An error on purpose. Fix the typo (ride → rides) and Run again: now every line prints.

Console

(nothing was printed)

Expected console output

Hello from the editor!
5 is five
[ 2979, 3992, 3759 ]
Uncaught ReferenceError: ride is not defined
An SVG with no size New tab

An edge case with no error message: a shape outside the SVG's box is simply not drawn.

Preview

Press Run to see the page.

Console

Nothing logged yet.

Expected console output

Width: 300 Height: 150
Circles in the page: 2

Break it on purpose

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

Break #1

Use await outside a module

In the second example, replace the JavaScript with: const response = await fetch("/data/lumen/daily.csv"); followed by console.log(response.ok);

terminal
$ Console
── what you'll see ──
Uncaught SyntaxError: await is only valid in async functions and the top level bodies of modules

Myth vs fact

Myth

You need to install a lot of software before you can start.

Fact

For Phases 0–3 you need a browser and a text editor. Node.js and Vite arrive in Phase 4, when loading data files makes a local server necessary.

Myth

If the page shows nothing, there's no error.

Fact

Errors are not shown on the page: they go to the Console. A blank chart almost always has a red line there explaining why. Open it first.

Myth

The live editor is a simplified fake browser.

Fact

Examples run as real pages in a real browser frame, with the real D3 7.9.0. The differences are about safety: the frame can't reach the internet (except the course data) and can't touch your files.

Pro corner

Extra depth for experienced readers. New to this? Skip it for now and come back later.

  • ▸

    In Chromium, a page opened from file:// can't fetch a sibling file: the console says Fetch API cannot load file:///…/data.csv. URL scheme "file" is not supported. and the promise rejects with TypeError: Failed to fetch. A module that imports a local file is blocked by CORS (from origin 'null' has been blocked by CORS policy). That, not convenience, is why Phase 4 moves to a dev server. Classic scripts and inline modules that import nothing still work from file://.

  • ▸

    The live editor's frame is a sandboxed iframe with srcdoc: scripts run, but the frame has no same-origin access to Hectal's page. It is also a secure context, so APIs that need HTTPS exist in it. Relative URLs resolve against the Hectal page, which is why course data uses absolute paths like /data/lumen/daily.csv.

  • ▸

    An uncaught exception aborts only the current script (or the current task), not the page: other <script> tags and later event handlers still run. In dashboards, one failing chart's error must not stop the others, which Topic 16.4 handles with per-chart error boundaries.

Remember this

  1. 1

    The problem this solves: beginners often lose their first hour to setup: installs, settings, errors they can't read. This course removes that. For the first four phases you need only a browser and a text editor, and every example also runs right here with one click.

  2. 2

    The editor on this page. Every live example has the code (HTML, CSS and JavaScript tabs), a Run button, a preview (the page your code makes) and a Console (what your code prints, and every error in red). Reset brings the original code back, so you can't break anything for good. The preview runs in a real Chromium-style browser frame with the real D3 library. It has no internet access except the course's own data files (/data/lumen/…).

  3. 3

    Your own computer, stop 1: one file (from now until Phase 3). Install VS Code (a free code editor; any plain-text editor works) and use any modern browser. Make a folder called lumen-dashboard, create a file index.html inside it, paste code, save, and double-click the file: it opens in your browser. On Windows, use File Explorer's "New folder"; on macOS, Finder's "New Folder"; on Linux, your file manager or mkdir lumen-dashboard in a terminal. In VS Code: File → Open Folder…, then the new-file icon next to the folder name.

  4. 4

    The browser's own console. On your computer, errors don't appear on the page. Press F12 (Windows and Linux) or Cmd + Option + I (macOS) to open the developer tools, then click Console. (In Safari, first turn on Settings → Advanced → Show features for web developers; Firefox opens its Console with Ctrl + Shift + K, or Cmd + Option + K on macOS.) It shows the same messages as the editor's Console, plus the file name and line number of each error. Get used to opening it: most "my chart is blank" problems are explained there in one red line.

  5. 5

    Your own computer, stop 2: a project (Phase 4 onwards). A double-clicked file can't load data files with fetch: the browser blocks it for safety (Topic 4.1 shows the exact error). In Phase 4 you install Node.js (a program that runs JavaScript outside the browser) and start a development server with Vite: a small program on your own computer that serves your files like a real website and reloads the page when you save. Until then, data that a chart needs is written into the file itself.

  6. 6

    The two most common first mistakes. On Windows, file extensions are hidden by default, so a file you named index.html in some editors becomes index.html.txt and opens as text: turn on View → Show → File name extensions in File Explorer (Windows 11; on Windows 10 it is a tick box under View) and rename it. And an <svg> with no width and height is not "empty": it takes a default size of 300 × 150 pixels, so shapes placed further right or lower are cut off without any error (second example).

Explain it without notes

01

Where will you write code in Phases 0–3, and where from Phase 4? Why the change?

02

Your chart on your computer is blank. What is the first thing you do, and how?

03

Why did the last line of the first example never print?

Practice

01

On your computer, create lumen-dashboard/index.html from step 2's code, open it, and add a second bar below the first (y = 60). Give the SVG enough height to show it. What height did you use?

02

In the second example, keep the SVG without a size and move the orange circle so that it is visible but touches the right edge exactly.

Trade-offs

  • ↔

    Double-clicking a file needs no tools at all, but it can't load data files. A dev server (Phase 4) needs Node.js and one command, but behaves like a real website.

Done when you can

  • I can run, change and reset an example in the live editor.

  • I have a lumen-dashboard folder with an index.html that opens in my browser.

  • I can open the browser's Console on my computer and find the line of an error.

  • I know why an SVG with no size cuts shapes off.