a05 Human Interface

DUE: 2022-04-15T00:00:00-5:00

GitHub Classroom Assignment Invite: https://classroom.github.com/a/PUVGxeMe

Issues: https://github.com/comp426-2022-spring/a05/issues

Packaging an interface

In this assignment, you will build an HTML human interface for your API. You will also document your API endpoints and consider package structure.

We are going to take our rudimentary interface from in-class examples and expand upon it somewhat for this assignment.

Assignment requirements

  1. A web interface with:
    1. a landing page <div>
      1. an explanation of the game and basic instructions
    2. a navigation of some kind using buttons that will highlight the active <div> and hide others
    3. a flip-one-coin <div>
      1. a button that makes an API call to /app/flip/ and then presents the resulting data to the person using the interface
      2. a graphical representation of the resulting coin flip
    4. a flip-many-coins <div>
      1. a button that makes an API call to /app/flip/ and then presents the resulting data to the person using the interface
      2. a graphical representation of the resulting coin flips
      3. summary information
    5. a guess-flip <div>
      1. Two buttons that make an API call to /app/flip/call and then present the resulting data to the person using the interface
      2. a graphical representation of the guess, and the actual result of the coin flip
      3. win or loss
  2. Document the API endpoints listed in README.md based on how they actually behave (for those that exist) and how they should behave (for those yet to be implemented).
    1. This is an exercise in planning and scoping as much as anything else.
    2. Think about the information that YOU would want or need to work with this app and put it in the README.md
  3. Package structure
    1. Modularize parts of your package and put them into different subdirectories. You have been provided with a basic structure to do this.
    2. Put public web files in ./public/
    3. Place your database script file in ./src/services/
    4. Write any log files into `./log/
    5. Store any database files in ./data/
    6. Consider other ways to move code out of index.js and into other parts of the package structure.
    7. Be sure to adjust the paths you are using to create files and call dependencies.

Instructions

Interface

Put your web interface code in ./public/. There is already some boilerplate HTML and CSS there for you to work with.

Your client-side JavaScript will also live in this directory.

You can (and should) use the code we worked on in class during w11 as the basis for your code.

Instead of having a single HTML file, you will split this code into three separate files:

index.html
style.css
main.js

The examples provide almost everything for the the single coin flip and many coin flips interfaces verbatim. Use what is there to develop the guess flip interface and other navigation.

API documentation

Your coinserver, at this point, should have all of the API endpoints listed in README.md available, except for two modified endpoints that relate to the w11 examples and requirements for this assignment.

See below for details about adding those.

For all of the endpoints that currently exist and those that have not yet been implemented, use the examples available in the README.md file to fill out the rest based on actual tests against your API server and speculative planning, respectively. The examples in README.md are from actual tests of a working example Coinserver.

Package structure

You will use index.js as your main entry point for the app. You will have to modify your existing code a bit to make the structural changes work, but you should start by putting everything that you have been building in server.js in previous assignments into index.js and go from there.

Place your database.js file in /src/services/ and change require('database') in your new index.js accordingly so that it can reference it in a subdirectory.

You will also want to consider where you put the database itself and log files. Directories have been provided for this in the starter repo.

Serving HTML with express

You will need this line in your index.js:

// Serve static HTML files
app.use(express.static('./public'));

This will expose everything in the ./public directory to the web using basic HTTP service on the same port as your API endpoints.

This way you do not have to use a separate webserver and worry about proxying or CORS.

Add modified endpoints

Since you will need to send body messages to endpoints using the client-side fetch() API for inputs in the interface for a many-coin flip and flip guess, you need to add two new endpoints to handle it, and invoke some middleware.

To make it so index.js can handle JSON body messages, add this line somewhere near the top:

// Make Express use its own built-in body parser to handle JSON
app.use(express.json());

To add endpoints that accept JSON body messages, use the following as an example to adapt your existing endpoints to use body instead of parameters:

app.post('/app/flip/coins/', (req, res, next) => {
    const flips = coinFlips(req.body.number)
    const count = countFlips(flips)
    res.status(200).json({"raw":flips,"summary":count})
})

app.post('/app/flip/call/', (req, res, next) => {
    const game = flipACoin(req.body.guess)
    res.status(200).json(game)
})

For reference, the following two endpoints use parameters, which is the way that your current API from a03 should be working.

app.get('/app/flips/:number', (req, res, next) => {
    const flips = coinFlips(req.params.number)
    const count = countFlips(flips)
    res.status(200).json({"raw":flips,"summary":count})
});

app.get('/app/flip/call/:guess(heads|tails)/', (req, res, next) => {
    const game = flipACoin(req.params.guess)
    res.status(200).json(game)
})

Note the simliarities and differences.

Use the above examples to adapt your existing code in similar ways.

Things to remember

It doesn’t have to be pretty

It just has to work.

The point of this assignment is to make a web interface function, not to make it polished and shiny.

By all means, if you are bored and interested in exploring that aspect of web development, feel free. But it is not a requirement.

There will also be a ghost assignment that can point you to to resources and tutorials for making this app more polished if you like. Watch for it to be listed on the assignments page. It will be entirely optional and you can receive extra credit for it if you wish to submit it.

Documentation is super important

A human interface isn’t just about clicking buttons and having things dance around on a screen.

A human interface should include information for people interacting with your app about how it works: PARTICULARLY for open source development.

So, don’t think of the documentation as an afterthought. Focus on it as a critical component.

Explore package structure

You are not required to restructure your package beyond what is described above, but you are encouraged to consider how to do this.

There are many different conventions and practices related to structuring packages. These can help communicate where to find certain things to other developers.

These links can help you think about where and how to structure your packages. But do keep in mind that this is, like everything we do, but one example of how to do a thing.

Organizing your Express.js project structure for better productivity - Geshan Manandhar

expressjs-structure - @geshan

You will need to make sure you use the dependency techniques we are familiar with to make the files in different directories talk to one another. This will be useful for the next assignment, which will involve converting all of this into a React app.

Good skill!

You have all the skills needed to do all of this.

You also already have most of the code needed to do this.

You don’t need luck.

And, if you need help, we are always here. Just (create an issue on the main a05 repo page)[https://github.com/comp426-2022-spring/a05/issues].