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!
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”
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
eslintand ?? tools “globally” with
npm install -g eslint
- install the
project dependenciesby running
npm installin a terminal from the project root repository
- install node and npm
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 installas 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 testin 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
- 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
} 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:”
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:
privateXXXproperties. Please do not enclose
falsein 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).
lastNameshould be the same as the names I will find in my official class roster from U of T
- use the
nickNamefield 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:
privatePicturewill hide your picture on the website (default: false)
privateEmailwill hide your email (default: true)
privateGithubwill hide your github id (default: true)
- if you set
privateNameto true, your first and last name will be hidden. Your
nickNamewill still be displayed, so be sure to use a
nickNamevalue 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
superPowersfield 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.
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.
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.
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:
<header>element contains some metadata and some very simple styling instructions in the form of CSS directives
<body>is also simple, and has two main parts:
<nav>element for the blue headline
<div>element with an
cardcontainerto 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
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.