Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
104 commits
Select commit Hold shift + click to select a range
cc7865c
doc renderer supports sections
Jutanium Dec 14, 2020
0c7d6c6
delete docs config from repo
Jutanium Dec 14, 2020
2fb0831
broken parseInner function
Jutanium Dec 16, 2020
6e2b993
working parseInner function
Jutanium Dec 16, 2020
b9ad051
no docsconfig file warning
Jutanium Dec 19, 2020
8514589
Merge branch 'docs-integration'
Jutanium Dec 20, 2020
e555af0
added vis back
Dec 20, 2020
5337492
Merge pull request #69 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 20, 2020
398b054
added uk covid data
Dec 21, 2020
d55374d
Merge pull request #70 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 21, 2020
06c15e2
fix type function error
Jutanium Dec 21, 2020
3d6682d
footnote & inline slot support
Jutanium Dec 21, 2020
c8b9645
Merge branch 'master' of https://github.com/GeorgiaTechDHLab/DataByDe…
Jutanium Dec 21, 2020
f080a1e
basic inline slot inner text support
Jutanium Dec 21, 2020
b0d1482
deal with objects before first section
Jutanium Dec 21, 2020
9b3f19f
peabody is docs
Jutanium Dec 21, 2020
66935a9
complete covid data, bug fix, add router link to playfair chapter
Dec 22, 2020
6ebf1a2
Merge pull request #71 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 22, 2020
8dbefe7
don't render empty paragraphs
Jutanium Dec 22, 2020
26cbe0b
proper subsection tracking
Jutanium Dec 22, 2020
057c8a9
Merge pull request #72 from GeorgiaTechDHLab/peabody-docs
Jutanium Dec 22, 2020
109626e
don't show title header for the introduction section
Jutanium Dec 22, 2020
582f6d5
fix and clealeanup playfair Vue options (was previously a copy of Pea…
Jutanium Dec 22, 2020
8ed5932
add prod script
Jutanium Dec 22, 2020
4b29c57
templates done
Jutanium Dec 22, 2020
f0f8394
add more datasets
Dec 22, 2020
e6d10f1
added vis
Dec 23, 2020
493bc45
Merge pull request #73 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 23, 2020
8a66d73
add script and mode-specific .env file to run remote server
Jutanium Dec 23, 2020
19ef063
Merge branch 'master' of https://github.com/GeorgiaTechDHLab/DataByDe…
Jutanium Dec 23, 2020
8855127
add coxcomb, add dataSelection for covid, women, income
Dec 23, 2020
d9e476e
Merge pull request #74 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 23, 2020
61cd893
adjust coxcomb
Dec 24, 2020
1ecd773
Merge pull request #75 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 24, 2020
7ff77c4
second version
Dec 24, 2020
1520e2e
Merge pull request #76 from GeorgiaTechDHLab/playfair-covid-vis
jianingfu Dec 24, 2020
9de820c
footnotes load from doc
Jutanium Dec 25, 2020
68443bc
blockquote component
Jutanium Dec 25, 2020
51ed39f
captionedimage component
Jutanium Dec 25, 2020
bbfaf3e
captionedimage component
Jutanium Dec 25, 2020
e3a6d3f
Merge branch 'master' of https://github.com/GeorgiaTechDHLab/DataByDe…
Jutanium Dec 25, 2020
80be1e7
captioned image width fix
Jutanium Dec 25, 2020
3ec4ee5
Merge pull request #77 from GeorgiaTechDHLab/dxd-text
laurenfklein Dec 26, 2020
dbb1406
playfair navline integration. extract common functionality into navli…
Jutanium Dec 28, 2020
3c50fb6
remove notebooktypes console log
Jutanium Dec 28, 2020
c429d2f
fix homepage timeline hover layers
Dec 28, 2020
414f4ba
Merge pull request #78 from GeorgiaTechDHLab/timeline-fix
jianingfu Dec 28, 2020
6b01127
Update README.md
Jutanium Dec 29, 2020
52578a8
Merge branch 'master' into dxd-text
laurenfklein Dec 31, 2020
ad35025
Merge pull request #79 from GeorgiaTechDHLab/dxd-text
laurenfklein Dec 31, 2020
6d366d5
Updated Playfair vis with final (?) images and captions; removed unus…
laurenfklein Dec 31, 2020
dcad854
Changed some label text and tweaked the label layout
laurenfklein Dec 31, 2020
862ac90
Merge pull request #80 from GeorgiaTechDHLab/dxd-text
laurenfklein Dec 31, 2020
5b18dcd
fix img filename discrepancy
Jutanium Dec 31, 2020
901303e
DocRenderer in its own repo; CaptionedImage registers on the timeline…
Jutanium Dec 31, 2020
e70f9c0
Merge pull request #81 from GeorgiaTechDHLab/modularize-docs-integration
Jutanium Dec 31, 2020
8552936
playfair vis fix
Dec 31, 2020
99ca581
Merge pull request #82 from GeorgiaTechDHLab/playfair_fix
jianingfu Dec 31, 2020
5c177ce
A few more text/image/caption additions to the Peabody and Playfair c…
laurenfklein Jan 1, 2021
63933de
Merge branch 'master' into dxd-text
laurenfklein Jan 1, 2021
f9b9e4a
Merge pull request #83 from GeorgiaTechDHLab/dxd-text
laurenfklein Jan 1, 2021
26d84cc
Replaced thumbnails in timeilne; updated chapter titles throughout
laurenfklein Jan 3, 2021
1205057
Merge pull request #84 from GeorgiaTechDHLab/dxd-text
laurenfklein Jan 3, 2021
5688ea0
Updated peabody chapter router link
laurenfklein Jan 3, 2021
7d9b33f
picline fix
Jan 3, 2021
e461f24
Merge pull request #85 from GeorgiaTechDHLab/homepage-fix
jianingfu Jan 3, 2021
631ac87
fix reduntant "lines of exports"
Jutanium Jan 3, 2021
2272209
begin removing unused files
Jutanium Jan 3, 2021
757d828
fix priestly -> priestley
Jutanium Jan 3, 2021
41ce85e
minor fix
Jan 3, 2021
d949bab
Merge pull request #86 from GeorgiaTechDHLab/playfair-fix
jianingfu Jan 3, 2021
db37fb2
Tweak caption of covid/income/women vis
laurenfklein Jan 4, 2021
8904f0a
add hover over
Jan 4, 2021
270e45b
Merge branch 'master' into playfair-fix
jianingfu Jan 4, 2021
7b7c40a
Merge pull request #87 from GeorgiaTechDHLab/playfair-fix
jianingfu Jan 4, 2021
4c4d685
Added/tweaked vis captions
laurenfklein Jan 4, 2021
bec226f
Merge branch 'master' of https://github.com/GeorgiaTechDHLab/DataByDe…
laurenfklein Jan 4, 2021
65306c8
fix stacked bar
Jan 4, 2021
9874e23
Merge branch 'master' into playfair-fix
jianingfu Jan 4, 2021
a1b4108
Merge pull request #88 from GeorgiaTechDHLab/playfair-fix
jianingfu Jan 4, 2021
27e3339
make header less obtrusive
Jutanium Jan 5, 2021
31360e8
adjust home page margin
Jutanium Jan 5, 2021
4fe1644
align header with chapter when resizing
Jutanium Jan 5, 2021
c002ea6
fix offset accuracy; add pause feature
Jutanium Jan 6, 2021
f4abace
fix offset accuracy; add pause feature
Jutanium Jan 6, 2021
3559f85
Merge branch 'playfair-todos' of github.com:GeorgiaTechDHLab/DataByDe…
Jutanium Jan 6, 2021
83c7e48
playfair scrollytell
Jutanium Jan 6, 2021
1c2a6b9
Merge pull request #90 from GeorgiaTechDHLab/playfair-todos
Jutanium Jan 6, 2021
83dffdc
fix d3 size
Jan 6, 2021
4b71663
Merge pull request #91 from GeorgiaTechDHLab/playfair-fix
jianingfu Jan 6, 2021
10437d4
grid todos
Jutanium Jan 7, 2021
179b8c0
Merge branch 'master' of github.com:GeorgiaTechDHLab/DataByDesign
Jutanium Jan 7, 2021
d0f4e86
Added floorchart images
laurenfklein Jan 7, 2021
1e66548
Merge branch 'master' of https://github.com/GeorgiaTechDHLab/DataByDe…
laurenfklein Jan 7, 2021
3e2e8f8
finally much better collect
Jutanium Jan 7, 2021
86bc6f2
added dot domain
Jan 7, 2021
3e121c0
Merge pull request #92 from GeorgiaTechDHLab/playfair-fix
jianingfu Jan 7, 2021
0ae4adf
(hopefull) fix glitchy second scrollytell
Jutanium Jan 8, 2021
5c6fed0
finish todos
Jutanium Jan 8, 2021
bd52fc7
Updated Playfair process vis text
laurenfklein Jan 8, 2021
b7e9b28
Added missing caption
laurenfklein Jan 8, 2021
da0fafe
Tweaked image sizes
laurenfklein Jan 8, 2021
b6b0de9
adjust easing on playfair mapscroller
Jutanium Jan 8, 2021
5b8f4d6
Bump bcrypt from 3.0.6 to 5.0.0
dependabot[bot] Jan 8, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
*.xml
*.env
dist/
server-express/docsconfig.json
.DS_Store
.idea
.project
Expand Down
362 changes: 8 additions & 354 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,3 @@
<!----- Conversion time: 3.291 seconds.


Using this Markdown file:

1. Cut and paste this output into your source file.
2. See the notes and action items below regarding this conversion run.
3. Check the rendered output (headings, lists, code blocks, tables) for proper
formatting and use a linkchecker before you publish this page.

Conversion notes:

* Docs to Markdown version 1.0β15
* Tue Feb 19 2019 12:25:33 GMT-0800 (PST)
* Source doc: https://docs.google.com/open?id=1Hq0_eUvE-bin62PqbVLxGUtzeWVRp8vMPPH0o-XVov4
----->



# Data by Design (DxD)


Expand All @@ -26,341 +7,14 @@ Data by Design is an interactive book by Dr. Lauren Klein. It is built for the m

Data by Design has a few features which place it on the cutting edge. In no particular order, these are listed below:



* The Notebook: users can take notes on content in the chapter to save and come back to later, but the notebook allows dragging and dropping of content from the chapter into itself. This includes interactive content, meaning that readers have a sandbox to experiment with each visualization in.
* The Meta-visualizations: the book, seeks to embrace its own interest in datavisualization fully, by visualizing its own content overall, and in each chapter.
* The Scrolly-telling: The book seeks to fully embrace the "[hypermedia](http://www.newmediareader.com/book_samples/nmr-21-nelson.pdf)" potential of the web. Many well established sites have already implemented scrolly telling in their media, most notably the New York Times.

Most importantly, to the developers working on this project, Data by Design is an opportunity to learn. From this point forward, anyone who reads this document will be working on a pre-existing codebase. More than likely, you, the developer, have come to this document because you are trying to familiarize yourself with this project before you dive in head first. Whether this is your first rodeo or not, remember: be patient, be forgiving, and never hesitate to ask for help.


## Installation/Setup

This section is more concrete than the previous sections. It will walk you through common actions you may have to take in developing for Data By Design.


### Installation

In order to use this project, there are a few things you have to do. Most of these steps should be OS-independent, but I will link to tutorials whenever certain steps get more complicated. These steps are listed below.


#### Installing Node

The first step is to install Node.js onto your computer. There are a few different ways to go about installing Node, and this is one step that depends on your operating system. You can research these alone if you want (although beware that choosing [nvm](https://github.com/creationix/nvm) may lead to issues on linux if you need to install packages globally using sudo). I recommend following the directions on the [Node.js website](https://nodejs.org/en/download/) for your specific OS. You should install the LTS (currently 8.11.3).

Check your installation by running the command below. It should spit out v8.11.3 or higher.


```
$ node -v
```



#### Installing MySQL

MySQL is the database which backs our website. Installation depends on your operating system. On Ubuntu 16.04, you should install using this command:


```
$ sudo apt-get install mysql-server
```


You should create a root password (keep it safe and close by). Then login to your MySQL server and create two databases, one called dxd_development another called dxd_production. Below, you can see this process in a bash shell for Ubuntu. In a production environment, you may only need the dxd_production database, but that is totally up to you.


```
$ mysql -u root -p # you'll enter your password below this command
# once inside mysql
> CREATE DATABASE dxd_development;
> CREATE DATABASE dxd_production;
```


It is highly recommended that you create **at least one separate MySQL user** and give it access to these databases. In production, make sure that the password is **strong** and does not contain any of these symbols: (#, ", \, /). They may cause issues when you go to store the password in an environment variable. Here is this process on Ubuntu.


```
# still in MySQL
> GRANT ALL PRIVILEGES ON dxd_production.* to 'dxdAdmin'@'localhost' identified by '<your strong password>';
> GRANT ALL PRIVILEGES ON dxd_development.* to 'dxdAdmin'@'localhost';
```


Make sure to change that password placeholder! You can skip the second command if you want to create a different user for dxd_development. To create that user, just change the database name, username, and password in the first command and run it. Again, make sure to keep track of the usernames and passwords for these accounts.

Now that MySQL is installed, we can move on to cloning the repository.


#### Cloning the repository

Our code is hosted on GitHub at [https://github.com/GeorgiaTechDHLab/DataByDesign](https://github.com/GeorgiaTechDHLab/DataByDesign), There are two branches you need to care about. The first is 'master' (duh), but that one comes by default. The second is 'dev' (this branch has the cutting edge changes, and allows us to stage changes before pushing them to our server). We will need to clone the repository, then checkout and track the dev branch. To do this with ssh (though you could use https too), do the following:


```
$ git clone [email protected]:GeorgiaTechDHLab/DataByDesign.git
$ git checkout --track origin/dev
```


Now you have access to the codebase, and we just need to stitch everything together!


#### Installing Node Modules

Before we get started tying all of these steps together, we need to install the node modules required by the project. These stay out of the repository, so you need to install them with npm (the Node.js package manager).


```
$ npm install
```


If you want to be able to leverage the production environment commands, you'll also want to do this:


```
$ npm install -g forever
```


If you want to be able to leverage the [loopback cli tool](https://loopback.io/doc/en/lb3/Installation.html#install-loopback-cli-tool) (generate models, roles, access controls, etc), then do this:


```
$ npm install -g loopback-cli
```


Now we need to make loopback aware of our database configurations, and generate secrets for our signed cookies.


#### Setting Environment Variables

In Loopback, we have a few different environment variables which need to be set in order for us to be able to use the database and signed cookies. Rather than have you set these environment variables on your machine, you will set them in a .env file. The required variables are below. You can copy and paste this into your own .env file and fill in the information yourself (hopefully you didn't forget any usernames or passwords from the last steps).


```
# env configuration example file (at /.env in the directory)
# Secret for cookies (64 character random string, no #, ", or '
DXD_SECRET=<COOKIE_SECRET>

# Production DB
DXD_PRODUCTION_USERNAME=<PRODUCTION_USERNAME>
DXD_PRODUCTION_DATABASE=dxd_production
DXD_PRODUCTION_PASSWORD=<PRODUCTION_PASSWORD>

# Development/Test DB
DXD_USERNAME=<DEVELOPMENT_USERNAME>
DXD_DATABASE=dxd_development
DXD_PASSWORD=<DEVELOPMENT_PASSWORD>
```


You should save this file in the root of the project, **not** in the a subdirectory (like server). You can change any of these values to make the project work based on your setup. If NODE_ENV is set to production, the production db credentials will be used, otherwise the development ones will be. If a mode is left blank or invalid, the server **will not launch** properly. Double check these once you finish. Make sure you don't have conflicting env variables set already, as they will not be overridden!

Once you do that, You should be good to go! Go ahead to the next section to learn how to run the app.


### Running the code

There are a number of ways you can run the app or different pieces of it. All of these can be found under the 'scripts' section in the package.json file. Scripts can be run using this format:


<table>
<tr>
<td>If you're actively developing, you should probably use:
</td>
<td><code>$ npm run start:dev</code>
</td>
</tr>
</table>



<table>
<tr>
<td>If you're deploying to production for the 1st time, use:
</td>
<td><code>$ sudo npm run start</code>
</td>
</tr>
</table>



<table>
<tr>
<td>If you are updating production code, use:
</td>
<td><code>$ sudo npm run restart</code>
</td>
</tr>
</table>



#### Starting for Development
If you are working on the site, you should probably be using these commands. Each command will enable hot reloading for the server and/or the vue app, meaning that as you update the code, it will auto update in the browser!


<table>
<tr>
<td><code>$ npm run api:dev</code>
</td>
<td>Starts only the server in development mode using nodemon for hot reloads (port 3000).
<p>
The frontend may not work, but all the api endpoints will.
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ npm run app:dev</code>
</td>
<td>Starts vue app with hot reloads on port 8080 using the vue-cli. Any api calls will fail unless you manually run api:dev as well.
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ npm run start:dev</code>
</td>
<td>Starts the app and api in parallel, each in development mode, both with hot reloading. Use this in development.
</td>
</tr>
</table>



#### Starting for Production

It is highly recommended that you run these commands using sudo when working on the server. If you are deploying locally to test a deployment, you can leave it off. It has been included in the commands below since it is best practice.


<table>
<tr>
<td><code>$ sudo npm run api</code>
</td>
<td>Starts the api using forever, (meaning that you will have to manually stop it later, since it will be in the background). The frontend will not be built, so it may not work, and won't be updated from the last build.
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ sudo npm run start</code>
</td>
<td>Builds the vue app and then runs the server in production mode
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ sudo npm run start:reset</code>
</td>
<td>Builds the vue app and then runs the server in production mode, but clears the database first
</td>
</tr>
</table>



#### Restarting or Stopping the App

These commands are used in production when you need to restart the server or stop it altogether.


<table>
<tr>
<td><code>$ npm run restart</code>
</td>
<td>Restarts an already running production server (stops the previous, then starts the current). Use this to update production
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ npm run stop</code>
</td>
<td>Stop a production server running with forever
</td>
</tr>
</table>



#### Building the Vue Front-end

If, for some reason, you want to build the front end directly you can use this command.

**Note:** this is done by default when you use <code>$ <em>npm run start </em></code>, so it most likely won't be necessary.


<table>
<tr>
<td><code>$ npm run build</code>
</td>
<td>Builds the Vue app front-end.
</td>
</tr>
</table>



#### Testing/Linting Commands

The following commands are used for testing and linting the code for the server and app.


<table>
<tr>
<td><code>$ npm run lint</code>
</td>
<td>Runs eslint on the front and back-end code
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ npm run test:unit</code>
</td>
<td>Runs the Vue unit tests
</td>
</tr>
</table>



<table>
<tr>
<td><code>$ npm run posttest</code>
</td>
<td>Lints and runs a security check on the server
</td>
</tr>
</table>

* The Meta-visualizations: the book seeks to embrace its own interest in data visualization fully by visualizing its own content overall and in each chapter.
* The Scrollytelling: The book seeks to fully embrace the "[hypermedia](http://www.newmediareader.com/book_samples/nmr-21-nelson.pdf)" potential of the web. Many well established sites have already implemented scrolly telling in their media, most notably the New York Times.

As we develop the site, we'll be updating our developer blog [here](https://dhlab.lmc.gatech.edu/blog/).

<!-- Docs to Markdown version 1.0β15 -->
## Getting up and running
Here's the quickest way to run the site.
* Install [node and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), which manages the project's dependencies
* Clone the project, then open the project directory in a terminal and run `npm install`
* Once the dependencies are installed, run `npm run app:remote` to run the frontend site locally using our hosted backend server.
1 change: 1 addition & 0 deletions client/.env.remote
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
VUE_APP_SERVER=https://server.dataxdesign.io/api/
Loading