To repeat myself: you do not have to become a coder to do well in this course. However, you /will/ have to be willing to explore technical skills that you might not otherwise develop as a humanities scholar. In this assignment, you will extend your knowledge of JavaScript to allow you to work directly with the content of web pages. The goal of the assignment is to provide you with basic technical knowledge that you will need for later assignments.
Note: if you're reading this in VSCode, the [[https://orgmode.org/][org-mode]] syntax probably won't display properly. Sorry about that! It's likely easiest to read these instructions online instead.
Expectations This assignment is graded pass/fail. You will only get credit if all of your code runs as required. To pass the assignment, you must:
successfully copy this repository on github (you'll get a link) and clone a local copy
complete at least the first three parts of this assignment (plus the fourth part if you hope to get an A in the class), such that both the student-visible tests and the instructor/machine-visible tests all pass.
commit your work to git as you go, so that a query of the git history will show multiple steps. Please note that git commits are timestamped and unique; they are an excellent defense against accusations of cheating, so please use them extensively. Tests will fail unless you make at least 6 commits to the repository.
push all your changes to Github
the last commit pushed to the main branch by the assignment deadline becomes your submission automatically
Checking Out And Handing In the Assignment
Create your personal copy of this repository by following the Github Classroom link you got separately. The new repository will appear at the URL ~https://github.com/dh20219/03-DOM-and-data-YOURID~ (as always, replace with your own github ID!). Clone this new repository locally via the "Clone or Download" process discussed in [[https://github.com/DigitalHistory/assignment-00-git-and-github/][your first assignment]] and also [[https://help.github.com/articles/cloning-a-repository/][described here]], and do your work in VSCode (you can also use the built-in GitHub integration in VSCode).
When your assignment passes all tests and you are satisfied with your work, please be sure that you have also pushed all your commits to the repository. This will ensure that I receive your work.
in the last assignment, you learned to work with JavaScript in a programming environment. You learned how to declare variables, write functions, and iterate across arrays and object properties.
In this assignment we slowly bring that knowledge back into the browser and the Web environment. This assignment is designed to lead you slowly to the point where you are able to manipulate parts of a web page in simple ways. You will make use of almost everything you learned in the last two assignments. Much of the difficulty here will come from integrating knowledge you already have, rather than from learning new topics.
** Part 1 - Introducing the data
Fill in the blank functions in [[./Part1/01-data-to-rows.js]].
We will be working with the same dataset in parts 1 and 3. The work you do here will make it much easier for you to succeed in part 3.
The dataset is an array of object literals, just like the arrays of names you worked with in your last assignment. A single object in the array has the structure:
{
name: 'Person\'s Name',
born: 1111,
died: 2222,
affiliations: ['list', 'of', 'organizations'],
quote: inspirational quote,
description: lengthy description
}
/Note: Textual data here is generally taken from Wikipedia (sometimes lightly modified) and is reproduced under [[https://en.wikipedia.org/wiki/Wikipedia:CCBYSA][a CC BY-SA licence]] unless otherwise noted in the source texts. Links to source material are not provided in this version of the repository, but will be generated by students on successful completion of the exercise./
As before, you will use the object properties to build a string output which your functions will return. However, this time, the returned strings will take the form of /valid HTML/. That will come in handy later.
For fun, you can see the results of your work by checking ~Part1/index.html~ before and after you write your functions.
** Part 2 - DOM Tricks
Fill in the blank functions in ~Part2/02-dom-tricks.js~.
This time, things are a little different. Your code will not run effectively in VSCode. We are transitioning to browser-based JavaScript, and the functions you write will only do work in the browser context.
You will need to understand the DOM first, and then become familiar with a small number of the jQuery functions for maniuplating the DOM. Make sure you have read [[https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction][the MDN intro to Web API's]], and the first part of [[https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Manipulating_documents][the DOM manipulation guide]]. However, we will not be using the built-in JavaScript DOM manipulation tools because they are somewhat clumsy. Instead, we will use convenience functions from the [[https://jquery.com/][jQuery library]]. You might want to look at some of their docs, e.g. [[https://jquery.com/][this example, in which we add a class to an existing HTML element]]. There are [[https://www.w3schools.com/jquery/jquery_ref_html.asp][some good explanations on w3schools]], and if you're feeling brave, [[http://api.jquery.com/css/][full discussions in the official jQuery introduction]]. Unfortunately MDN does not have other docs. You will definitely need to use the ~$().html~, ~$().text~, and ~$().css~ methods. We will go over the use of query selectors in class.
Your work will be loaded into ~Part2/index.html~ via a script tag; your functions will then be executed via a second script. Take a look at index.html to see how all of this works.
See the comments in ~02-dom-tricks.js~ for more details.
** Part3: manipulating a real web page
In ~Part3/index.html~, we have a web page which was generated using the same dataset you used in Part 1. You are going to use jQuery to add some extremely basic "interactivity" to the page (actually, it hardly qualifies). Your script (~03-dom-data.js~) will add a Wikipedia link to every name in the table of leaders. The assignment will lead you through a series of steps, each of which gets you closer to the desired result.
Consider the structure of the table rows:
Your code should change that to this:
Again, your code will not actually run in VSCode; you will need to open ~Part3/index.html~ to see how you are doing. However, the tests should still run, and they will hopefully help at least a little.
Hints: In this exercise we are beginning to actually do a form of digital history. Notice that we are treating /text/ as /data/: transforming names into "pointers" that give us access to further information.
This is made possible because the web page itself is already well-structured. Notice the class attribute on each ~
Now, consider the structure of Wikipedia links:
https://en.wikipedia.org/wiki/Steve Biko
Note they always consist of "https://en.wikipedia.org/wiki/" + A_Name_With_Spaces_Replaced_By_Underscores. But, lucky you, /Wikipedia will rewrite spaces as underscores for you!/ So you just need to be sure you are producing the correct string, which consists of the Wikipedia "prefix" plus the figure's name
* Part 4: Reflection If and only if you are aiming to achieve an A in the course*, you must also complete the Reflection section of the assignment. Answer the questions in ~Reflection/reflection.md~. Follow the directions in the file.
** Tests As in our other assignments, this one comes with a set of bundled tests designed to make your life a little easier. To run them, first execute ~npm install~ from this directory. Then run ~npm test~ or, to watch the directory continuously, ~npm run watch~
** Notes for People with pre-existing web skills
In real life, you would probably avoid programming in the way we do here. Instead of directly inserting strings into the HTML structure of the page, you would operate at the element level, creating, inserting, and manipulating nodes into the DOM. Unfortunately, working that way requires use of the document object, which does not exist be default in Nodejs files. This makes it difficult to employ a transitional problemset in Part 1. If you have thoughts on how to improve the experience here I would love to hear them!