A6—D3 event handling

Due F 2022-03-04, 11:59pm EST 16pts

Follow all the instructions below.

Please post any questions about this assignment on Canvas in Discussion: A6—D3 event handling.

Warning: This is an individual assignment.

Table of contents

• Change log
• Aim of the assignment
• Instructions
  • Setup
  • Repo organization
    • Root files
    • Folders
  • Implement custom click event
  • GitHub Pages, hyperlinks, & validation
  • Bonus: Implement custom double-click event
• Submission instructions
• Academic integrity
• Grading rubric
• Tips, tricks, & troubleshooting

Change log

• 2022-03-03: Revised Implement custom click event for clarity. The initial lines of bullets 2 and 3 now talk about dispatching a custom event and registering a callback that is triggered when the custom event is received.

Aim of the assignment

Using events is critical for implementing interactive visualizations using D3. In this assignment you will learn how to handle and create new events with d3-dispatch. (This is particularly important for the upcoming brushing & linking assignments and your projects.) You will not have to create any new chart—you will just demonstrate your understanding of how events work.

Instructions

Please look through all the materials below so you understand the setup instructions; how to run, organize, and submit your code; and our requirements for the assignment.

Setup

1. Accept the GitHub Classroom assignment invitation by clicking this link to get your repository:

   https://classroom.github.com/a/A7mZdz-4

   For reference, this is the template repository your repository is being created from: https://github.com/NEU-DS-4200-S22/A6--D3_Event_Handling.

   Recall our general instructions and policies on GitHub Classroom assignments.

2. Clone your GitHub-Classroom-generated repository to your local machine.

   E.g., in your terminal / command prompt CD to where you want this the folder for this activity to be. Then run: git clone <YOUR_REPO_URL>

   Warning: Under no circumstances should you be editing files via the GitHub website user interface. Do all your edits locally after cloning the repository.

3. CD or open a terminal / command prompt window into the cloned folder.

4. Start a simple python webserver. E.g., python -m http.server, python3 -m http.server, or py -m http.server. If you are using python 2 you will need to use python -m SimpleHTTPServer instead, but please switch to python 3 as Python 2 was sunset on 2020-01-01.

5. Wait for the output: Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/).

6. Now open your web browser (Firefox or Chrome) and navigate to the URL: http://localhost:8000.

Repo organization

Here is an overview of the files and folders we provide for you in your repo.

Root files

• README.md is this explanatory file for the repo.

• index.html contains the main website content.

• style.css contains the CSS.

• LICENCE is the source code license for the template. You can add your name or leave it as is.

Folders

Each folder has an explanatory README.md file.

• favicons contains the favicons for the web page. You don’t need to change anything here.

• .github contains GitHub Actions (docs) which will automatically validate your HTML, CSS, and hyperlinks when you push (see the validation last step below). Do not edit files here except to create new .yml files for any additional actions you choose to add (you are not required to make any).

• js will contain all JavaScript files you write. E.g.,

  • main.js is the js code that you will have to fill in.

• lib will contain any JavaScript library you use to ensure long-term survivability. It currently includes D3.

  Note: Use the included D3 library here rather than linking to d3js.org or some other content delivery network (CDN). Likewise, put your other libraries here rather than loading them from elsewhere.

Implement custom click event

js/main.js creates an svg inside the div with id #vis and draws a square and a circle for you. You will be creating a new custom event type to handle clicking on a pre-existing square in an svg. When the square is clicked, the circle should change color to red.

Implement the following functionality as part of js/main.js.

As you work, make your edits and commit major versions to your git repository.

1. Define a custom event changeColor using d3-dispatch.

2. Using d3-dispatch, dispatch a custom changeColor event when the square is clicked.

   There are pre-existing DOM events for click and mousedown which are part of the standard DOM events. You may listen for a click or mousedown event and use it to then dispatch the changeColor event using d3-dispatch.

3. Register a callback using d3-dispatch that is triggered when a changeColor event is received. When triggered, it should change the circle’s color to red.

   Do not simply have a listener on the square that changes the color directly, e.g., selection.on('click', function(event){ // code that changes the color }); You must use d3-dispatch to send and listen for a custom changeColor event.

   We are aware that the same objective can be obtained by using standard predefined DOM events. However, learning how to use d3-dispatch correctly will be especially useful to you in the upcoming brushing and linking assignment. In that assignment you will create multiple modular yet linked visualizations and you will want your code to be more loosely coupled and easier to manage. The brushing and linking assignment will be impossible to do without first understanding d3-dispatch.

GitHub Pages, hyperlinks, & validation

1. Commit and push your files to GitHub and test whether your website looks the same on GitHub pages. Note: the GitHub Pages site won’t show up until you make your first commit & push to the remote repository, and it may take up to a minute for it to finish deploying. You would normally need to turn on GitHub pages in the settings for your repository, but we have set that up for you so you’re using the gh-pages branch by default.

2. Edit the last line of your README.md file to include a clickable hyperlink to the GitHub page website for your repo., replacing the <insert your clickable hyperlink here> code with your markdown.

3. In index.html update the GitHub repo URL with the URL of your repository. It is in the span with id='forkongithub'.

4. Make any edits necessary to ensure your code passes the W3 validator. You can see the results automatically from the ‘Validate HTML, CSS, and Links’ checks we run when you push to GitHub. I.e., you want to see a green check next to your commit () and not a red X (). You can also see the results in the Actions tab of your repo:

   

Bonus: Implement custom double-click event

To get a 1-point bonus on your grade, additionally implement the following functionality as part of js/main.js.

1. Similar to before, and continuing to use d3-dispatch, implement a custom changeColor2 event.

2. Create an event listener that dispatches a changeColor2 event when the circle is double-clicked.

   A double-click is two clicks in a very short period of time. In order to implement a double-click, you will need to use a timer, like this:

    setTimeout(function, milliseconds);
   

   Reference: Javascript timing events.

   Using the pre-existing dblclick DOM event is not allowed in this submission.

3. Create an event listener using d3-dispatch that is triggered on a changeColor2 event and changes the square’s color to green.

Points will not be deducted for failing this bonus step, but make sure that the code in your GitHub repository works properly for the first step from the time of the deadline onwards.

Submission instructions

1. Commit all your local files and push them to the remote repository on GitHub which was generated by GitHub Classroom. We will grade based on what is visible on the GitHub Page.

2. Submit the URL of your repository to the assignment A6—D3 event handling in GradeScope.

   Warning: Do not put a link to a personal repository. It must be within our class GitHub organization.

Academic integrity

You are welcome to use D3 tutorials or resources as a starting point for your code. However, keep our academic integrity policy in mind.

Warning: You must cite and reference the resources or sample code you use and explain how you use them and where (e.g. “js/main.js line 33”).

Warning: Cite everything, including code from the D3.js Graph Gallery, bl.ocks.org, Observable, or Stack Overflow!

Failure to properly cite and attribute code is a breach of academic honesty. Simply copying existing examples without performing thoughtful edits is a breach of academic honesty. Also, per our syllabus, homework is an individual assessment and should be completed by you alone. You are welcome to ask fellow classmates and students for help and discuss the assignment, but the submission should be your own work.

See the academic integrity policy on the syllabus for more detail on our expectations.

Grading rubric

Click event is correctly implemented if

• changecolor event uses d3-dispatch.
• Clicking on the square changes the circle’s color to red.
• You aren’t just appending a new red circle on top.

For the coding style, you should have clear, commented, and validated code. Your web page must load properly and look as expected in the latest Firefox and Chrome browsers. Any code from other sources (modified or copied straight) is clearly acknowledged, including how you use it (note that plagiarism carries severe consequences). Files follow the organizational guidelines from the README.md and original template.

Tips, tricks, & troubleshooting

If you run into trouble, first look at our relevant tutorials which have links to various resources, tips, & tricks:

• GitHub Classroom
• git
• Web Development
• D3