Tutorial 5

We're going to keep making the tutorials smaller, letting them transition to being more like worked examples. Why? Because for most students, it'll be more productive for you to work on your projects.

The challenge for this tutorial is to build some controls, using Vue or React, that will let you set up a Conway's Game of Life game.

Clone the code

First, get the code and put it somewhere you can load it in your browser.

To get the code, open a terminal, cd into the public directory of whichever webserver you are using, and:

git clone https://gitlab.une.edu.au/cosc360in2018/tutorial-conway-life-t5.git

This will clone this code using the git version control system. That will, amongst other things, let you switch between different branches (eg, the solution and the start of the exercise)

Check it's working

Open index.html in the browser, and you should find yourself faced with Conway's Game of Life from Tutorial 4.

Install loaders for Vue or React

The repository contains all the code from the previous tutorial, but not a copy of node_modules which would be too large. Let's make NPM go and get all the modules we've already declared in packages.json:

npm install

And before we go any further, let's put webpack into development mode. In webpack.config.js, at the top of module.exports, set:

  mode: 'development',

If you're using Vue, install the modules for vue:

npm install --save-dev vue vue-class-component vue-property-decorator

You'll also need to alter webpack.config.js to load the version of Vue that includes the template compiler. Change the resolve block to:

  resolve: {
    extensions: ['.ts', '.js', '.vue', '.json'],
    alias: {
      'vue$': 'vue/dist/vue.esm.js'
    }
  },

If you're using React, though, you'll need to install the modules for react:

npm install --save react react-dom @types/react @types/react-dom

and edit tsconfig.json to tell TypeScript to target React as the Virtual DOM for .tsx files

    {
        "compilerOptions": {
            "outDir": "./built/",
            "sourceMap": true,
            "strict": true,
            "noImplicitReturns": true,
            "module": "es2015",
            "moduleResolution": "node",
            "target": "es5",
            "experimentalDecorators": true,
            "jsx": "react"
        },
        "include": [
            "./src/**/*"
        ]
    }

Now the challenge

It might be useful to get ready for development by telling npm to watch our project for changes, and rebuild it automatically:

```sh
npm run build -- --watch
```

The challenge:

Using either React or Vue, create a small block that will let us set up the Game of Life game. We're going to keep the game itself rendered through d3, showing how they exist on the page, but this should have:

• Fields for how many columns and rows you want
• A button that when clicked will create the game (and trigger d3 to rerender it)
• A field for how long (in ms) each tick should be -- default it to 500
• A button that will toggle whether the tick-timer is started or not. This button should only be enabled when the game has been created.

For this exercise, we're not going to put the d3-rendered game inside the element controlled by Vue or React -- we'll just have them co-exist in different elements on the same page.

How to go about this

As is typical, I'd recommend you start just by working out the data structure for what you want to render. Looking at the requirements above, something like this seems appropriate:

export interface GameConfig {
    w:number
    h:number
    started:boolean
    created:boolean
    period:number
}

The next task I would suggest is just creating this object and rendering it to a little UI using your chosen framework. That'll let you fiddle around with the layout.

Then, wire up the functionality. Note that you'll probably need to change life. At the moment, it's a constant in the render file. You will probably want it to be a variable that can be set by calling a function.

Solving this with Vue

A worked solution can be found on the vue-solution branch of this repository. To check out the code, you could run git checkout vue-solution. But let's talk you through it.

Getting Vue in there

First, let's get Vue rendering something, even if just Hello World.

In index.html, create a div that Vue can render to. Let's put this above the svg for the game:

<div id="app"></div>

And inside index.ts, let's import Vue and render something to that div

import Vue from "vue";

let v = new Vue({
    el: "#app",
    template: `
      <div>
        Hello {{ name }}
      </div>
    `,
    data: {
        name: "Vue"
    }
})

Reload, and check we get "Hello Vue" appearing. If so, good -- Vue is working, can compile templates, and we can progress.

Defining a ConfigView

Let's create a new TypeScript file gameConfig.ts to define a component in.

First, let's bring our definition of a game config here:

interface GameConfig {
    w:number 
    h:number 
    started:boolean 
    created:boolean
    period:number 
}

Next, we'll import Vue and Component:

import Vue from "vue"
import Component from 'vue-class-component'

And then let's start defining the component. This is going to take a GameConfig as a prop, and is going to alter its fields

@Component({
    props: {
        config: Object as () => GameConfig
    },
    template: `
      <div>
        This will render a game config
      </div>
    `
})
class ConfigView extends Vue {

    config!: GameConfig

    constructor() {
        super()
        console.log("a new config view was placed")
    }

}

I've included a constructor this time, so we can see in the console that we've tried to add the component.

Now, we're going to need to export the definitions of GameConfig and ConfigView:

export { 
    GameConfig as GameConfig,
    ConfigView as ConfigView
}

In index.ts, let's import our definitions:

import { ConfigView, GameConfig } from "./gameConfig"

Now we should be able to create a config (notice we're using TypeScript's structural typing here):

let config:GameConfig = {
    w: 40,
    h: 20,
    started: false,
    created: false,
    period: 500
}

And we should be able to alter our invocation of Vue to use our new component (don't forget to include it in the components section at the bottom):

let v = new Vue({
    el: "#app",
    template: `
      <div>
        <ConfigView :config="config"></ConfigView>
      </div>
    `,
    data: {
        config: config
    },
    components: {
        ConfigView
    }
})

Making ConfigView alter the config

Next, let's go back to gameConfig.ts and make our ConfigView render something more interesting that actually alters the fields.

The full HTML of the component's template in the solution is quite long, but that's because I've used Bootstrap's components to make it look pretty — the Vue aspects are quite small in there. So rather than talk you through all of my solution HTML, let's just do a short and not-so-pretty version here.

We're going to need input elements for the width and height of the grid.

The config prop we've passed in is read-only. But it's a read-only reference to a mutable object. So we're going to bind some input controls to its fields.

First, in the component's template, we need inputs for the width and height:

template: `
      <div>
        Columns:
        <input type="number" v-model:value="config.w" />

        Rows:
        <input type="number" v-model:value="config.h" />
      </div>
    `,

We've used v-model rather than v-bind to give us a two-way binding between the value of the input field and the value of config.w and config.h. Remember, we can't alter config (the reference) but we can alter its fields.

If you reload the page, you should now have some fields above the grid, and they should appear initialised to 40 and 20.

Next, let's wire up a Create button. Inside the component's template, put:

    <button v-bind:disabled="config.created" v-on:click="create">Create</button>

This bind's the button's "disabled" attribute so that it will become disabled when config.created becomes true. And it sets the button so that when it is clicked it will call create() in the component's class. We'd better go and make the create function. Remember, it needs to be a method on the ConfigView class:

    create() {
        console.log("Create was pressed")
        this.config.created = true
    }

Reload and check that logs to the browser console when you hit the button (and the button should also become disabled).

Altering render

We need to let our component actually configure our Life instance.

First, in render.ts, let's turn life into a variable, and also add a create function that accepts a GameConfig and a function for getting the value of life.

import { GameConfig } from "./gameConfig"

let life:Life = new Life(0,0)

function create(config:GameConfig) {
    console.log(config.w)
    life = new Life(config.w, config.h)
    render()
}

function getLife() {
    return life
}

Next, make sure those are exported

export {
    getLife as getLife,
    create as create,
    render as render
}

Making ConfigView set up the game

Let's go back to gameConfig.ts and import those definitions

import { create, render, getLife } from './render'

We can now alter the definition of our create() method on ConfigView to actually call create in render.ts:

    create() {
        create(this.config) // note this calls create in render.ts that we imported
        render()
        this.config.created = true
    }

Reload, and see if it works.

Setting up the timer

JavaScript timers give you a timer id that is a number. So in our ConfigView class let's add a field that can remember it. This is not a prop, just an ordinary field on the class. And the ? means it might be null.

    intervalId?: number

Let's now create a method on the class that can start and stop an actual timer using this field. Notice that we're using the getLife and render functions from render.ts that we imported.

    toggleTimer() {
        if (this.config.started) {
            clearInterval(this.intervalId)
            this.config.started = false
        } else {
            this.intervalId = setInterval(() => {
                let l = getLife()
                if (l) l.stepGame()
                render()
            }, this.config.period)
            this.config.started = true
        }
    }

And now all we need do is add some HTML to the template that'll reference the remaining fields of our GameConfig and will call this method:

Period:
<input type="number" v-model:value="config.period" />
<button v-bind:disabled="!config.created" v-on:click="toggleTimer">
    {{ config.started ? "Stop" : "Start" }}
</button>

Notice this button is bound so it's disabled until we've created the game. It's onClick is bound to the toggleTimer method, and the text changes from Start to Stop depending on whether the timer is already started.

Solving this tutorial with React

There's a worked solution to this tutorial using React.js on the react-solution branch. But let's talk you through it.

Some config changes

First, there's some config changes we'll make to make things easier. By default, React won't give you nice error messages -- it left them out of the library to save space. So make the HTML load the development scripts from our node_modules directory:

<script src="./node_modules/react/umd/react.development.js"></script>
<script src="./node_modules/react-dom/umd/react-dom.development.js"></script>

And tell webpack not to put React itself into bundle.js (because we're loading its development scripts separately). In webpack.config.js, inside module.exports:

externals: {
  "react": "React",
  "react-dom": "ReactDOM"
}

We're also going to want to use TSX, so let's update compilerOptions in tsconfig.json:

    "jsx": "react"

And let's also rename index.ts to index.tsx, and then update webpack.congfig.js to tell it about the new entry point:

  entry: './src/index.tsx',

Getting React on-screen

Let's get React rendering something, even if just Hello World.

In index.html, create a div that Vue can render to. Let's put this above the svg for the game:

<div id="app"></div>

And inside index.tsx, let's import React and ReactDOM, and something to that div

import * as React from "react";
import * as ReactDOM from "react-dom";

and now for our first bit of TSX:

ReactDOM.render(
    <div>Hello React</div>,
    document.getElementById("app")
);

Set webpack watching the files:

npm run build -- --watch

Reload index.html in the browser, and check we get "Hello Vue" appearing. If so, good -- React is working and we can progress.

Creating a ConfigView component

Let's create a file called `gameConfig.tsx'.

First, let's import react:

import * as React from "react"
import * as ReactDOM from "react-dom"

Then let's define two types -- one for the config's definable properties, and another that has some additional state:

export interface ConfigProps {
    w:number
    h:number
}

export interface ConfigState extends ConfigProps {
    created:boolean
    period:number
    intervalId?: number
}

intervalId is optional -- hence the ?

And then let's define a React component:

export class ConfigView extends React.Component<ConfigProps, ConfigState> {
    render() {
        return <div>This will render some game config</div>
    }

    constructor(props:ConfigProps) {
        super(props)
        this.state = {
            ...props,
            created: false,
            period: 500
        }
    }

}

Notice that in the angle brackets, we've said this component's properties are defined by the ConfigProps interface -- so, it has properties for w andh. And we've said its state is defined by the ConfigState interface.

In the constructor, we've also taken the component's properties, and augmented them with the missing compulsory variables. ...props is the "spread" operator that sets all the name-value pairs from props on the new object we're creating.

Let's go back to index.tsx and use our component.

First, we need to import ConfigView:

import { ConfigView } from "./gameConfig"

and then let's alter our React call to use it:

ReactDOM.render(
    <ConfigView w={40} h={20}></ConfigView>,
    document.querySelector("#app")
);

Notice that we've been able to set the w and h properties as attributes on the component. This sets them in the props object.

Reload and see if the message is in the UI.

Render some controls

It's time to get our ConfigView to render some real controls. Let's alter gameConfig.tsx.

    render() {
        return <div>
          Cols: <input type="number" value={this.state.w} onChange={(e) => this.setW(+e.target.value)} />
          Rows: <input type="number" value={this.state.h} onChange={(e) => this.setH(+e.target.value)} />
          <button onClick={(e) => this.create()}>Create</button>  
        </div>
    }

In this, we've bound the input fields to render the w and h fields from the current state.

We've then needed to bind an onChange handler for each field. This takes a lambda function. The parameter (e) is the event that has happened. And we're getting e.target.value from it to get the number out of the input field. This comes out as a string, even though the input field is for numbers. So in order to convert it to a number, we use +e.target.value. This then needs to get passed to this.setW and this.setH -- methods on our class. So we'd better write those!

Likewise, we've boud the button's click handler to this.create().

Let's write setW and setH, which are methods on the ConfigView class:

    setW(w:number) {
        this.setState((state:ConfigState) => {
            state.w = w
            return state
        })
    }

    setH(h:number) {
        this.setState((state:ConfigState) => {
            state.h = h
            return state
        })
    }

In both cases, we call setState, which is a method from the React API (remember, ConfigView inherits from React.Component). setState gives you the current state, and asks you to return the new state. It will then automatically trigger re-rendering the component.

Now let's write create method, and just get it to log to the console:

    create() {
        console.log("I was clicked")
    }

Reload the page, and check the code so far works

Making it create the Life game

Let's alter render.ts.

First, import the ConfigProps interface

import { ConfigProps } from "./gameConfig"

and now let's make life a variable instead of a constant. We'll initialise it to a zero-sized game so it won't be null but won't be visible on the screen. And we'll define a create method that takes ConfigProps.

let life = new Life(0, 0)

function create(config:ConfigProps) {
    life = new Life(config.w, config.h)
}

We'd best make sure those are exported:

export {
    life as life,
    render as render,
    create as create
}

Now let's go back to gameConfig.tsx and make it set up the game by altering what happens when we click the button

First, let's import the functions from render.ts

import { life, create, render} from "./render"

Then let's alter the create method on ConfigView:

    create() {
        create(this.state) // note this calls the function imported from render.ts
        render()  // note this calls the function imported from render.ts
    }

Reload, and check it works

Setting up the timer

The last part we'll do is setting up the timer. In gameConfig.tsx, let's alter the render() method for our component:

    render() {
        return <div>
          Cols: <input type="number" value={this.state.w} onChange={(e) => this.setW(+e.target.value)} /> 
          Rows: <input type="number" value={this.state.h} onChange={(e) => this.setH(+e.target.value)} />   
          <button onClick={(e) => this.create()}>Create</button>  

          Period: <input type="number" value={this.state.period} onChange={(e) => this.setPeriod(+e.target.value)} />
          <button onClick={(e) => this.toggleTimer()}>{ this.state.intervalId ? "Stop" : "Start" }</button>  
        </div>

We've added an input field, very similar to the ones for w and h but operating on period.

We've also added a button that will call toggleTimer, which we need to define. Its text is set by a ternary expression on whether intervalId in the component's state is defined.

toggleTimer can work as another call to setState. Only this time, the call is also going to either start or cancel a JavaScript timer. We need to use window.setInterval because in Node setInterval has a different return type than in the browser -- calling window.setInterval makes sure TypeScript uses the browser's version.

    toggleTimer() {
        this.setState((state:ConfigState) => {

            if (state.intervalId) {
                clearInterval(state.intervalId)
                state.intervalId = undefined
                return state
            } else {
                state.intervalId = window.setInterval(() => {
                    life.stepGame()
                    render()
                }, this.state.period)
                return state
            }

        })
    }

Reload, and see if it all works!