A short assignment introducing yourself to me, and getting you set up for the rest of the class.
Clone or download
Latest commit 0197257 Jan 10, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Reflection initial commit Jan 10, 2019
images initial commit Jan 10, 2019
students initial commit Jan 10, 2019
test initial commit Jan 10, 2019
utils initial commit Jan 10, 2019
.eslintrc.json initial commit Jan 10, 2019
.gitignore initial commit Jan 10, 2019
.npmrc initial commit Jan 10, 2019
.nvmrc initial commit Jan 10, 2019
.travis.yml initial commit Jan 10, 2019
README.org initial commit Jan 10, 2019
index.html nonsense ocmmit Jan 10, 2019
package.json initial commit Jan 10, 2019

README.org

This is an assignment for Digital History, a digital humanities course taught in the History Department at the University of Toronto. If you’re a teacher, feel free to fork and repurpose for your own courses. If you’re a student, keep reading!

Class profile Assignment: Goal

In this assignment, you will:

  • create a small file with some information about yourself
  • add (“commit”) that file and a separate image file to a git repository
  • optionally (if you are considering attempting an “A” in the class) write short responses to some questions in a text file and commit that file as well
  • send (“push”) your changes to the github code-sharing website

The information you send will generate a “trading card” about you that will be displayed on a publicly-visible website. Take this opportunity to think about the ethics of data collection, and implications for historical work that operates in communities like this one.

This is also your opportunity to set up a development environment on your laptop. While we have done our level best to simplify the process, this can still be a somewhat daunting task, so do not leave your setup to the last minute. Expect the unexpected!

Expectations

This assignment is graded pass/fail. You will only get credit if your repository passes all relevant tests. To pass the assignment, you must:

  • successfully install git and bash on your computer
  • install and use Visual Studio Code, or another text editor at your discretion
    • Add the Hacking History extension to Visual Studio; this will download a number of other tools as well
  • install Lintbot (but see below for other options)
  • Accept the assignment invitation that was circulated on Quercus (you may already have done this!). This will create a repository for you, which you must then clone locally on your laptop
  • enable automated testing by installing all npm packages
  • add to the repository a text file containing structured information about you
  • add to the repository a profile picture of yourself
  • commit both these changes
  • students attempting an A only: answer reflection questions
  • push all your changes to Github and check that “all checks have passed”

Other Options

Our tool “Lintbot” is intended to remove one troublesome step in the setup process. However, there’s a tradeoff: lintbot is easy to use, but it is less powerful and flexible than the advanced tools you might use instead. So if you wish you may also:

  • download and install node.js and npm as described on the Tools page
  • install the “Hacking History Advanced” extension to VSCode
  • install the eslint and ?? tools “globally” with npm install -g eslint
  • install the project dependencies by running npm install in a terminal from the project root repository
  • install node and npm

Details

Setup

Setting up your work environment could take some time. It’s best to do this well in advance of the assignment deadline.

  • download the Visual Studio Code (VSCode) editor and install the course extensions package as described on the Tools page
  • configure git with your git and github information as described here and here
  • allow Github to create a copy of this repository for you by following the link on the website. Clone locally via the “Clone or Download” method described here, and do your work within VSCode.
  • Download and install Lintbot as described on the Tools page. Alternatively, you may choose to install the entire “node stack”:
    • download and install node.js and npm as described on the Tools page
    • install the node dependencies for your project with npm install as described on this page. On Windows you may run into some issues. See the Node website before coming to me for help, but I will assist where I can.
    • run tests by executing npm test in your working directory
    • you should now see a new directory TestResults, inside of which you will find a file testresults.html. Open this file in a modern browser (Chrome or Firefox) to see your test results (most of the tests should fail at this point, so don’t worry!).

Make your Changes and Commit Them

Add a picture of yourself to the repository

  • the picture should be named yourgithubid.jpg (substitute your real !) and should be placed in the images directory
  • commit this new file to the repository. You can use the command line, the git tools inside Atom, or the GitKraken interface, as you prefer.

Create and update your JSON file

In the directory students, you should see a file named “template.json”. Copy the contents of this file to a new file, which should be named yourgithubid.json (substitute your actual Github user id for “yourgithubid”!). This file is written in the JSON (“JavaScript Object Notation”) framework, which we will learn more about later in the course. Your file will contain exactly one “JSON object”, delimited by the { and } at the beginning and end of the file. Each line of the file is called a “property” and takes the form of a “key/value pair:”

"key": "value",

Think of the “key” as the name of this small element, and the value as its content. You should not change the keys, but you must change almost all of the values.

This file needs to meet the stringent criteria of the JSON specification, so be very careful editing it:

  • the resultant file must be valid JSON, which means that key names must be enclosed in double quotes, and values must either be enclosed in double quotes as well, or use the special Javascript values “true” or “false” in the case of the privateXXX properties. Please do not enclose true and false in quotes, or they will not work as expected. Avoid using ~”~ and ~’~ except as enclosing markers around your keys and values, as they can easily lead to syntax errors.
  • the fields “firstName”, “lastName”, “email”, “github”, and “photo” must all be filled out (no exceptions).
  • firstName and lastName should be the same as the names I will find in my official class roster from U of T
  • use the nickName field if either of these is true for you:
    • you prefer to be called by a name that is not the name I’ll find in my roster
    • you do not wish to share your full name publicly on the class roster website.
  • the “privateXXX” fields control what information will be displayed on the public website. Any such field set to “true” will mark some information as private, as follows:
    • privatePicture will hide your picture on the website (default: false)
    • privateEmail will hide your email (default: true)
    • privateGithub will hide your github id (default: true)
    • if you set privateName to true, your first and last name will be hidden. Your nickName will still be displayed, so be sure to use a nickName value that you are willing to make public.

    This is a low-traffic website which will only be available during this semester, but if you do not want to share information with your classmates, or have serious concerns about information becoming public, you should be sure to fill these fields out

  • the superPowers field is not mandatory, but it will help me to remember who you are, so… please do fill it out! Use it to tell the class something interesting and/or memorable about yourself. Note that this field cannot be made private.

When you are done, commit your changes as above.

COMMENT

fix” singleton:

Answer Reflection Questions (“A” Bundle only)

This section is only required for students who are attempting to achieve an “A” grade. If that is not your goal, you do not need to worry about this part, or about tailing tests from this section.

In the folder “Reflection”, you will find a file named reflection-template.md. Copy the file contents to a new file named yourgithubid.md (again, use your real Github id instead of githubid!). This file contains two subheadings, each of which is a question. Answer each of these questions in a response of approximately 100-150 words. Your responses should be thoughtful and perceptive, and written at a level that would normally result in a grade of B or higher.

Run tests

At any point in the process, you can re-run your tests by dropping your repository’s root directory into Lintbot (or by executing npm test from a terminal in the working directory). Visit the file TestResults/results.html in a browser to see your updated results. To have the tests run continuously whenever you modify a file, run npm run watch instead (you will still have to refresh the web page to see the new results!).

Building the Website

You may want to see what your profile will look like on the website when it goes live. You can get a preview this with the following command:

npm run collectjson

Now open the file index.html in your browser. You should see your card along with the dummy cards already provided.

Handing in

As mentioned above: when you are finished – when your code passes all the tests – submit your code by pushing your changes to origin in VSCode FIXLINK (or with git push origin master in the terminal). At that point, the “continuous integration server” will re-run the tests and confirm that your code is valid; if the tests pass, a script will trigger and upload your work to the website.

Tests will also run upon submission of your pull request, and a notification will appear on the Pull Request page indicating whether or not they have passed . Please note that the build process may be very slow or even fail during periods of heavy load, e.g., immediately before deadlines. For this reason it is better to familiarize yourself with the testing process and run them locally, yourself, before handing in your work. ’

For the curious: How this works

This is a very simple example of using structured data to create a visual interface that, as it were, represents that data to the visitor. In this case, the “representation” takes the form of a playing card.

Each of you creates a small json file with uniform structure. Because the structure is predictable, I can build other structures on top of the data you provide. In this case, I use some primitive techniques for harvesting that data; and then I have some further code (also very simple) for looping across the data structure, creating an HTML structure for each person in the class. That HTML is then “injected” into the web page, where you can see the cards.

For privacy reasons, you don’t have access to each other’s information. However, if you want to, you can still see how this process works.

index.html: The main web page

You haven’t learned about HTML yet, but the structure of this page is quite simple:

  • the <header> element contains some metadata and some very simple styling instructions in the form of CSS directives
  • the <body> is also simple, and has two main parts:
    • a <nav> element for the blue headline
    • a <div> element with an id attribute of cardcontainer to hold the cards

If you look closely at the code, you’ll see that the card container div is empty! So where do the cards actually come from? That’s where the <script> tags comes in. First, we load the list of all student information (see below) by executing the trivial script in utils/allstudents.js. Then, in the final script tag I “loop over” that list – for each student, this script creates a bunch of HTMl and adds it to the cardcontainer div.

utils/collectjson.js: Gather student data

This script reads all the json files and uses them to write a new file, allstudents.js. It might be a little hard to follow, but I’ve added extensive comments which might help you a little bit.

utils/allstudents.js: student data storage

This is where the full list of students is stored.

Testing this out yourself

To run this yourself, you will need to install node.js and NPM. Follow those instructions, then run npm run collectjson from a terminal having first navigated to the root directory of the repository. You should see a set of cards that also includes your own information.