01-getting-started.Rmd

# Getting Started {#getting_started}

To use the Infographiq approach, you'll need a couple of things:

1.  A code editor. We recommend [Sublime Text](https://www.sublimetext.com/), but there are lots of [great choices](https://www.creativebloq.com/advice/best-code-editors).
2.  A basic understanding of how HTML works. For a refresher, check out this [great tutorial series](https://www.w3schools.com/html/default.asp).
3.  A basic understanding of Javascript, as the core Infographiq functionality works through this language. If you don't know any Javascript, don't panic! Further down on this page, you'll find a cheat sheet to get you up to speed.
4.  Vector graphics software. The images used by Infographic must be in vector form and, therefore, you'll need vector graphics software. We provide instructions in this guide for two vector graphics packages: [Adobe Illustrator](https://www.adobe.com/products/illustrator.html) (requires a paid subscription) and [Inkscape](https://inkscape.org/) (free).
5.  An understanding of how to run Javascript locally from your own computer. Don't fret if you don't know: we get into it on this page.
6.  The example folder for Infographiq, which provides a full working example that you can fiddle around with. We'll be referring to this folder extensively in this guide and you can [download a compressed version here](https://marinebon.org/infographiqJS/infographiq_example.zip). Just unzip the folder when you get it.

## The basics of Javascript {#javascript_basics}

We'll be providing a very fast pass through Javascript here, but for a more detailed tutorial, [check this out](https://www.w3schools.com/js/default.asp).

1.  **Javascript is used in html pages via the `<script>` tag.** Using your handy-dandy code editor, take a look at the infographic.html file that is contained within the Infographic example folder that you just downloaded. There, you'll see that a html page can draw upon Javascript in two ways.

1A. Loading an external Javascript library. Lines 12-14 of the infographic.html file reads as follows:

``` {.html}
<script src="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js" 
  integrity="sha384-aJ21OjlMXNL5UyIl/XNwTMqvzeRMZH2w8c5cRVpzpU8Y5bApTppSuUkhZXN0VxHd" 
  crossorigin="anonymous"></script>
```

These lines loads in a bunch of Javascript code written elsewhere - which is known as a Javascript library. In this case, we're loading in Bootstrap - a well-known Javascript library

1B. Writing Javascript code directly within a page. Lines 39-48 of the infographic.html file read as follows:

``` {.html}
<script>
    link_svg({
        svg: "illustrator_example.svg", 
        csv: "icon_link.csv", 
        svg_id: "svg1", 
        toc_id: "toc1",
        toc_style: "sectioned_list",
        text_toggle: "toggle_off",
        svg_filter: "illustrator_example.svg"});
</script>
```

Here, within the confines of the `<script>` tags, we're directly writing some Javascript code. In this particular case, we're calling a function called `link_svg` (more on this function later).

2.  **You end a Javascript line with a semicolon.** In the Javascript example for 1B above, this may seem like multiple lines of code. But it isn't! Take a careful look at the end of the second-to-last line (the one starting with `svg_filter`). You'll notice that there is a semicolon there. In fact, it is the only place in this code chunk where there is a semicolon. So, that means this whole chunk is actually just one line of code, so far as the Javascript is concerned. Why does this matter to you? It matters because a classic reason why Javascript code fails is because the programmer forgot to put semicolons in the right places (don't let that happen to you).

3.  **Javascript functions.** A function is a simple way of calling upon a chunk of code that has been written elsewhere. In Javascript, the dead giveaway that a function is being called is a set of parentheses after some term (something like this: `some_function()`. So, for example in 1B above, you know `link_svg` is a function because you see `link_svg(` on the third line. You may be a bit confused though, because the closing parentheses only shows up several lines later (on the `svg_filter` line). What's all the stuff in between the parentheses?

All those things are values that are being fed into the function. For an example, check out the third line of 1B:

``` {.javascript}
svg: "illustrator_example.svg",
```

We see here a few things. There is a parameter in the function called `svg` and we are going to give that parameter the value "illustrator_example.svg". Lastly, we are going to finish out with a comma, to let Javascript know that more values are coming.

## Running Javascript on your own machine {#localhost}

Since, Infographiq involves HTML files that contain Javascript, you'll need the ability to run Javascript on your computer. You might think that, if you have a Javascript-containing HTML file saved on your machine, you can just open the file directly in a web browser. Unfortunately, this won't work. To have the Javascript run, you'll need to set up a local testing server on your computer (which is easier than it might sound!). Here are the [instructions for how to do that](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server#running_a_simple_local_http_server).

How do you know if it is working? In the example folder for Infographiq (which, again you can [download a compressed version here](https://marinebon.org/infographiqJS/infographiq_example.zip)), there is a file called infographic.html. If you have the local testing server running properly - and you open the page via the following URL in your browser:

    http://localhost:8000/infographic.html

you should see something that matches what you see at [this link](https://marinebon.org/infographiqJS/infographiq_example/infographic.html).