Soft Open 003

Learning Software engineering in the open

Hello!

Welcome to Eating Complexity! A newsletter from Jack Hagley.

In the Soft Open series I’m teaching myself about Software Engineering, a subject I’m not an expert in at all. My goal is to develop software to make data visualisation a more interactive, intuitive and fun experience.

The pitch for it is simple:

Scratch for data-viz

Here is the github

Learning things

I’m up to the part where I know enough Javascript to be dangerous, and I have found out about React.

React

I have been encouraged to use React as a framework.
The reasoning to do it

• It’s a well-known framework, so there is lots of resources

• Learning it is useful for doing other things

• Two of the libraries I want to use: Rete and pdfme are based in React

Why I think also it’s a bad idea:

• It’s not getting Graphs on a Page

  ¹

• Owls All the Way Down aka Yak Shaving

What is React?

I got most of what comes below from here
React is a framework for building things. The building blocks of React are components.

What are Components?

• A component wraps up markup, CSS and Javascript together.

• Components are reusable and can be nested inside one another

• an entire page can be a component

• a button can be a component

• components can be 'sprinkled' with markup

• Components come in two types: Functions and Classes

How do they Work?

Components are written in JSX, which is a bit like Javascript. JSX is a syntax extension for React. JSX is essentially Javascript functions that return HTML.
Components are therefore declared using tags:

<PageLayout>
</PageLayout>

It means you can write HTML+CSS inside Js, rather than matching up things in different places. So if you’re making something it means you make it all in one place instead of writing it in three places. So it’s neater.

The Rules of JSX

1. Thou shalt returneth a single root element

• To return multiple elements, wrap them inside another single element (such as a div)

• You can even use an empty tag <> </> - This is called a Fragment.

  • <> </> == <Fragment> </Fragment>.

  • If you explicitly use Fragment you can pass key

  • There are other things to learn about state but it’s outside of scope for now 

2. Thou shalt closeth thine tags

   • <img> must be followed with <img />

   • wrapping tags such as <li> must be followed with </li>

3. Thou shalt use camelCase

   • JSX turns into JS

   • attributes become keys

   • camelCase is used to make sure that you respect limitations on class names:

     • some words are reserved eg class

     • words cannot contain - (dash)

     • strokeWidth instead of stroke-width

     • className not class shalt returneth a single root element

Make sure you can export the component

Prefix the component:

export default …

This is a standard Javascript function. It means this component can be imported (using import) from another module. Modules are simply a way of splitting up large Javascript files so you only bring in libraries (or parts of libraries) that you need.

Define the function

We have to remember that components must begin with a Capital Letter or they won’t work!

export default function MyComponent()
{
…
}

Nesting and definition

Components can render other components, but definitions happen at the top level.
Don’t nest the definitions of components. Or bad things will happen

Add markup / return

HTML

export default function MyComponent()
{
return <img src="https://i.imgur.com/MK3eW3As.jpg" alt="Katherine Johnson" />;
}

If you want to make it neater, use parentheses to split a return value over multiple lines

export default function MyComponent()
{
  return (
    <img
      src="https://i.imgur.com/MK3eW3As.jpg"
      alt="Katherine Johnson"
    />
  );
}

CSS

Inline

Add styling by adding in the styles section inside the component. Notice the properties with two-word names (such as background-color) have to be written camelCase.

export default function StyledComponent() {
  const styles = {
    container: {
      backgroundColor: 'lightblue',
      padding: '20px',
      borderRadius: '8px',
      boxShadow: '0 2px 4px rgba(0, 0, 0, 0.2)',
    },
    heading: {
      fontSize: '24px',
      color: 'darkblue',
    },
    paragraph: {
      fontSize: '16px',
      color: 'gray',
    },
  };

  return (
    <div style={styles.container}>
      <h1 style={styles.heading}>Styled Component with Inline CSS</h1>
      <p style={styles.paragraph}>
        This component has inline styles applied using the "style" prop.
      </p>
    </div>
  );
}

External

Using the file structure:

src/
|-- components/
|   |-- StyledComponent.js
|-- styles.css
|-- App.js

styles.css:

.container {
  //container styling
}

.heading {
  //heading styling
}

.paragraph {
  //paragraph styling
}

StyledComponent.js:

import React from 'react';
import './styles.css'; // Import the external stylesheet

function StyledComponent() {
  return (
    <div className="container">
      <h1 className="heading">Styled Component with External CSS</h1>
      <p className="paragraph">
        This component uses styles from an external "styles.css" file.
      </p>
    </div>
  );
}

export default StyledComponent;

App.js:

import React from 'react';
import StyledComponent from './components/StyledComponent';

function App() {
  return (
    <div>
      <StyledComponent />
    </div>
  );
}

export default App;

That’s probably enough to be dangerous – at least for now. I have some other things but all of these are subjects I could write about forever and never finish.

Doing things

I found a tutorial: https://react.dev/learn/tutorial-tic-tac-toe.

They recommend to use CodeSandbox to complete this task, but I wanted to work on it locally. It’s good practice to work on your local IDE whenever possible, and I haven’t really used it for React so far, so I wanted to see how to make it work.

I made a folder on the desktop using mkdir and cded into it.
Using create-react-app I quickly made all of the relevant files and folders.
I went through all of the files and folders taking out all of the testing stuff, and replacing the code with the code from the tutorial.
I open index.html, but hang on, nothing is happening… Of course I forgot to start the server. Using npm start gives me an error. This is because in the tutorial the package.json does not define this.
It’s simple to fix by adding some code from chatGPT into package.json:

{
"scripts": {
"start": "react-scripts start",
"test": "echo \"Error: no test specified\" && exit 1"
},
///the original code
}

Now I can boot the server using npm start and view it at http://localhost:3000/

Inside App.js we can find just one component:

export default function Square() {
return <button className="square">X</button>;
}

… and we are ready to start making the game.

---

Until next time! Thanks for reading this far!

If you enjoyed this post, please share the substack on social media somewhere. It really makes a difference.

1. Strike the Earth!