plotly / academy

Plotly Academy

Usage

Setup

1. Clone this repository by entering git clone https://github.com/plotly/academy.git into your terminal
2. When that is finished, enter the directory of the repo with cd academy
3. Install the dependencies of this page with bundle install

Note: See Prerequisites.md if you encounter a problem with the initial setup.

Running locally

1. Enter bundle exec jekyll serve into your terminal
2. Open localhost:4000 in your browser

Typography

We use Typography.js to set up our typography styles. If you need to adjust the typography, follow the steps below:

1. Go to the scripts/ folder and run npm install.
2. Make changes to the generated typography css, make changes to write-typography.js
3. Run npm run write-typography. This will write out a file to the _sass src directory.

NOw you can just start jekyll like normally and the new styles will be there!

Adding a new tutorial

There are two types of tutorials: site internal tutorials, and external tutorials. Site internal tutorials are all tutorials that live in this repository and can be accessed directly at academy.plotly.com/tutorialname, e.g. the React tutorials.

External tutorials are links to tutorials that live on other websites.

Internal tutorials

Add your tutorial to the _config.yml as a collection like this:

collections:
  tutorialname:
    output: true
    permalink: /tutorialname/:path/index.html
    title: "Tutorial Title"
    category: "Frontend"

Add a folder in the root directory called _tutorialname, and put the Markdown files of the tutorial in there. That's it, your tutorial will now be visible on the homescreen!

Note the category field, this field can be one of these two values: "Frontend" or "Data Science"!

External tutorials

To add an external tutorial, again add your tutorial to the _config.yml as a collection but this time with output set to false:

collections:
  tutorialname:
    output: false
    title: "Tutorial Title"
    category: "Data Science"

Also similar to the internal tutorials, you again add a directory called _tutorialname to the root folder and put Markdown files in there, one for each tutorial part.

The difference lies within the Markdown files, instead of containing the parts themselves, they specify links_to in their YAML Front Matter, like this:

---
title: Test 1
description: This is a test external tutorial
links_to: http://plot.ly
---

And you'll see a list of your tutorial parts with links to the external sites on the homepage!

Licensing

Code released under the MIT license.

academy's Issues

[Frontend Tutorial] Chapter 4 File Name Confuision

In chapter 4 of the tutorial when adding redux the file names seem mixed up. In the structure defined from create-react-app there is no app.js but index.js. There is also no folder components

[Frontend Tutorial] Chapter 4 ReactDOM.render missing RootNode

In the code snipped when adding the provider in index.js:

ReactDOM.render( <Provider store={store}> <App /> </Provider> );

it should be

ReactDOM.render( <Provider store={store}> <App /> </Provider>, document.getElementById('root') );

[Introduction] - Browserify part - no require error as it should be

Hey,

In the Browserify section, when I open the index.html file without transpiling the main.js, I have no error like you say:

If you try opening the index.html file in your browser now, you’ll see an error in your console saying something like “require is undefined”.

main.js is loaded but not executed apparently.
You need to add it like this in the index.html:
<script src="./main.js"></script> instead of this <script src="./main.js" />

EDIT: same thing when you add bundle.js :)

[Chapter 3] - Good practice

Hey Max,

IMO, I think it's a good practice to respect component lifecycle order in a class. It's more clear when you read it or want to debug it.
In Plot.js chapter 3, we wrote componentDidUpdate() method before componentDidMount().
Maybe we would inverse them. What do you think?

React with Plotly - Warnings

Hey Max,

I have different warnings and an error in the Plotly.min.js:

Warnings are coming from eslint rules, I guess. Maybe we should not use the name data for the data we get from our xhr request and for the data we are going to use when we do var data = JSON.parse(data.body);. It might be confusing too for users.
For the Plotly undefined warning, we should declared Plotly as a global variable in an eslint config but eslint is not really a part of the tutorial so I am not sure what to do. Leave the warning or add a few lines in the tutorial about declaring Plotly as a global in eslint :)

EDIT: Forget about Plotly error, it was because I didn't specify data like x, y, type... in Plotly.newPlot(). My bad!

Typo and future folder maybe?

We learned how to structure our application, with a common components/ folder.

There is no components/ folder in our app at this point of the tutorial.

We’re not taking of rendering an error message

A little typo error: taLking :)

Let me know if you think I am going to deeply in feedbacks.
For now, your tutorial is very clear and comprehensive!

Switch to Jest

Since create-react-app will use and support Jest with the next release I'm going to switch part 6 to use it!

Installing dependencies locally instead of globally?

Hey,

In your tutorial, you tell people to install browserify and watchify globally with the -g option.
Is it on purpose?

IMO, this is not a good practice to install something globally. People can forget sometimes that a dependency is needed for a project because they have installed it a while ago globally. Just my opinion though!

[Frontend Tutorial] Installing new dependency

To install a new dependency in the tutorial you need to stop and restart the development server. This is not reflected in the tutorial.

[Chapter 3] - Good practice 2?

We set a click event on the plot element like this document.getElementById('plot').on('plotly_click', this.props.onPlotClick);

Not sure but should we remove it in componentWillUnmount()? Not sure how on('click') works.
I usually use addEventListener() in componentDidMount() and removeEventListener() in componentWillUnmout(). Should we do the same here?

Asking for my personal knowledge and good practice :)

[Frontend Tutorial] Links open in same window

Links open in the same window as the tutorial. You have to sign up / copy the key / read the documentation and then hit back a bunch of times to continue where you were.
For the sake of the tutorial flow it might be a good idea to open the links in new windos/tabs

OpenWeatherMap API is a deadlink

Hey,

OpenWeatherMap API in the Fetched Data section is a deadlink :/

EDIT: Link to get an API key is dead too

[Chapter 6] Component Test

Hi,

Thank you for this tutorial. Encountered an issue with the last part of testing.

renders correctly
TypeError: Cannot read property 'on' of null

Not sure if this is caused by the Jest version or something else.

Hero image

This is the image I'm currently using as a hero image, it signifies learning in the sense of the never ending void of the human knowledge.

_{(Source: Unsplash))}

If you have any better ideas or images, let me know!

Tagline

Any ideas for a tagline for Plotly Academy?

First steps - App.js confusing?

At the beginning of First Steps, you completely modify App.js from the one we get with create-react-app but you don't export the class anymore.
It can be confusing for the user that you need to keep export default App at the end of the file :)

Personally, I use export default class App extends Component {} instead of exporting it at the end of the file.

Safari jsbin

Using Safari (9.1), when I open the react.jsbin.com link in a new tab (not our first JSBin link), the html is not rendered and I get an error. I don't understand why this link is not working but the our first JSBin is. It's working find with Chrome. Kind of an edge case but I just wanted you to know :)

Plotly - undefined issue

I'm having issues with plotly being undefined. So, I have created Plot.js and I have added /* global Plotly */ to the top of plot.js and when I call plotly from within my App.js file, it tells me Plotly is undefined. Here's what I have:

`/* global Plotly */
// Plot.js
import React from 'react';

class Plot extends React.Component {
drawPlot = () => {
Plotly.newPlot('plot', [{
x: this.props.xData,
y: this.props.yData,
type: this.props.type
}], {
margin: {
t: 0, r: 0, l: 30
},
xaxis: {
gridcolor: 'transparent'
}
}, {
displayModeBar: false
});
}

componentDidMount() {
this.drawPlot();
}

componentDidUpdate() {
this.drawPlot();
}

render() {
return (

);
}
}

export default Plot;`

Then in my index.html file, I have added the script <script src="https://cdn.plot.ly/plotly-1.8.0.min.js"></script>

Then in my App.js file, I am making the plotly call right after render.

render() { Plotly.newPlot();

I'm not sure where I went wrong, I'd appreciate any insight.

Translating this project

Hi @mxstbr ,

Thank you for making such an awesome tutorial for beginner.

I'm creating this issue to ask you if It would be OK to translate this project to Vietnamese? Should I fork this project and deploy the result to a different domain? Or should I send a PR back to this project

Nav & Footer

Could one of you send me the markup and the styling of your Nav and Footer? It'd be a waste of time and money to reimplement those if they already exist...

Use fetch instead of xhr

Hey guys,

create-react-app already includes a fetch polyfill.

License

How do you want the code and the tutorials licensed, which license do you prefer?