Welcome to JavaScript Programming for Planners & Designers!

Syllabus

• Course: CPLN-6920/MUSA-6110, University of Pennsylvania
• Location: McNeil Building 286-7
• Schedule: 1:45-4:45PM, Wednesdays
• Instructor:
  • Mjumbe Poe, mjumbe@design.upenn.edu
• Office Hours:
  • Coworking in person (check schedule here) Usually in Van Pelt RDDSx Wednesdays, 10:00-1:00, but there are exceptions; check the calendar
  • Virtually, by appointment (book here)
• Need help?
  • Slack

Course Overview

Dashboards, maps, and other interfaces that enable the display, analysis, and in some cases generation of new geospatial data, are often the end product of a data analysis or modeling process. In this course we'll focus on the interface and interaction aspects of creating these products. Ultimately, the goal is for you to become conscientious builders of civic technology, able to craft data-backed interfaces that inform, empower, and engage the public.

You will learn to design and build accessible interfaces to help users access the value promised by geospatial data, modeling, and analysis. As this is a JavaScript course, we'll be doing a lot of programming in JavaScript. Because of the nature of interactive interfaces with JavaScript, we'll also be doing a lot of work with HTML and CSS.

This course is the first part of a track in MUSA in which you will learn to build data products. In the second course (Geospatial Cloud Computing & Visualization) we'll focus on the data pipeline aspects of building these products. The courses are best together, but they can each also stand alone.

Objectives

By the end of this course, you should be able to:

• Apply user-centered design principles and accessibility standards to create intuitive, public-facing data interfaces.
• Demonstrate familiarity and comfort with the JavaScript language, alongside essential HTML and CSS.
• Understand the structure of client-side web applications, including how browsers load resources and respond to user interactions.
• Employ industry-standard "tools of the trade," including code editors, Git/GitHub, linting, testing, and the responsible use of AI as a learning and debugging tool.
• Use mapping, visualization, and analysis libraries such as Leaflet, D3, ApexCharts, and Turf.js.
• Access and manipulate data in a variety of formats directly in the browser, particularly GeoJSON, CSV, and Mapbox Vector Tiles.
• Access web services and APIs, such as Mapbox and Nominatim, to extend application functionality.
• Confidently read, interpret, and apply technical documentation for JavaScript libraries and APIs.

Course Outline

Throughout this 14-week course, you will learn to program applications using HTML, CSS, and JavaScript. In addition to programming skills, we will emphasize the "tools of the trade": you will use a text editor designed for programming, manage your code with Git, and submit your assignments using "Pull Requests" through GitHub. You will be operating with the same tools used by software developers in the industry.

I like to keep the course somewhat freeform. While there are foundational skills we must cover, your personal interests will help shape the direction of the class, especially in the final weeks. The course will follow flipped-classroom mechanics -- you will be expected to read and watch videos before we meet, allowing us to spend class time on discussions, live code demonstrations, or actively working on exercises and projects.

This syllabus is a living document. As the course progresses, greater detail will be added to reflect the content of each week.

Exercises

• You will have short exercises to complete for almost every class, particularly during the first half of the semester.
• While these exercises are not graded, you are accountable for the skills practiced within them. We will not cover all of these skills comprehensively during class time, so completing them promptly is critical to your success in the course.
• Solutions for earlier exercises will be checked automatically, allowing you to tweak your code until it passes.
• Solutions for later exercises are more subjective and will not have automated checks. For many of these, I have included a sample solution in the solutions branch of the repository. We will review and discuss select solutions together in class.

Projects

Your core portfolio for this class will consist of three individual projects. To help you build expertise and depth, I highly encourage you to use the same domain of data for all three assignments, allowing your work to compound over the semester. Your chosen dataset should relate to urban or environmental spatial analytics -- this can cover a broad range of social, infrastructural, political, economic, or environmental concerns, so long as it connects back to cities and/or nature.

While each project has a suggested structure, I am very open to self-directed proposals that align with your interests, provided they utilize the tools we are learning. Together, these projects represent three critical classes of interface responsibilities that conscientious builders of civic technology must master:

1. Telling a Narrative (starter repo) -- Interfaces that communicate a narrative. You will choose a dataset and create an interactive experience that guides users through the insights and patterns within the data. You will present this narrative accessibly using maps, text, and multimedia. The focus of this project is storytelling with data.

   Note: Because you will just be getting started with HTML, CSS, JavaScript, and working with data in the browser, I will provide a couple of starter templates (such as a scrolly-telling layout or a click-through story map). At a minimum, you can focus simply on integrating GeoJSON datasets into one of these templates. However, if you want to stretch out of your comfort zone and make further modifications to the provided templates -- or use other templates you find elsewhere -- I will fully support you in doing so.

   Weeks 1-4 will be spent working on this project.

2. Supporting Decisions (starter repo) -- Interfaces that support decision-making. You will use data to build visualizations and analyses that help users make informed choices. While dashboards are a common tool for this (and we will discuss them in class), a dashboard is not the only way to provide data for making decisions. You are encouraged to build whatever type of interactive tool best fits your use case, provided the focus remains on ensuring the right information is presented to the user in the right time and context. The focus of this project is actionable data delivery.

   Weeks 5-8 will be spent working on this project.

3. Inviting Participation (starter repo) -- Interfaces that enable participation and collaboration. Your final project will focus on engaging the public around data. Building upon the concepts learned throughout the class, you will incorporate a significant amount of interactivity to invite members of the public to create, manipulate, or add to a dataset in some way.

   Final projects may be done in groups or independently. Criteria for success will be hammered out in a final project proposal. Group projects will be expected to engage with a wider scope and greater difficulty. The focus of this project is public engagement and data generation.

   Weeks 9-14 will be spent working on this project.

Work Evaluation & Feedback

My primary target for this course is to help each of you learn how to create data-backed interfaces that inform, empower, and engage people in the real world. I want you all to become conscientious builders of civic technology. I believe the best way to achieve this is through practice, which is why the course is centered around the three interface responsibilities outlined above.

Part of my job, however, is to evaluate your work and assign a grade. In data analysis, there is a concept called Goodhart's Law (which we will discuss when we get to dashboards) that states: when a measure becomes a target, it ceases to be a good measure.

Your grade is, ostensibly, a measure of the quality of your work. Getting you to a good grade is not my target. In fact, your grade is a second-order measure. The quality of your work is itself merely a measure of whether you are learning and able to put into practice the things I want you to learn.

As such, while I will provide a default set of grading criteria in this syllabus so that I am not grading you simply on "vibes," I do not deeply care about the grade itself. If there is a different way you want to measure your learning and practice, come talk to me. I am happy to offer flexibility for those who want to do something specific, as long as it hits the core competencies I think are important. Like any well-chosen defaults, the grading criteria can be overridden when it makes sense to do so.

Beyond (and, in my opinion, more important than) a grade, more thorough, practical evaluation of and feedback on your work will come in the form of:

1. Code reviews -- You will submit pull requests (PRs) via GitHub, which the course instructors will review to leave direct feedback and suggestions on your code.
2. Linters -- You will learn to read the automated output from linters and accessibility checkers, using them to debug and improve your work before submission.
3. Real-time Discussions -- Some of the most valuable feedback happens before you write a single line of code. You are highly encouraged to use class time, coworking hours, or scheduled appointments with me to talk through your logic, ask questions, and get immediate feedback on your ideas, wireframes, and code in progress.

Software

• Code Editors
  • Visual Studio Code
  • Sublime Text
• Terminals
  • Windows Terminal
  • Mac and Linux each come with a full-featured terminal already installed
• Git Clients
  • GitHub Desktop
  • Visual Studio Code Git extensions (built-in, though you may have to install git first; VS Code should walk you through the installation)
  • Sublime Merge
• Web Browsers (for Developer Tools)
  • Google Chrome, Mozilla Firefox, or Microsoft Edge
• Node.js
  • Node.js
• AI Coding Assistants (Optional but Recommended)
  • Tools like ChatGPT, Claude, or GitHub Copilot (to be used responsibly for exploring repositories, debugging, and cementing concepts as we will discuss in class)
  • I encourage you to use these agent skills when using an AI coding assistant or other LLM tool

Supplementary Resources

• Mozilla Developer Network (MDN) - A highly authoritative body of documentation on JavaScript and many other web development topics.
• Introduction to Web Mapping - A web-based textbook specifically for JavaScript-based mapping. A good portion of this class will overlap with the material in this book.
• Javascript.info - An excellent linear reference -- like a textbook for JavaScript.
• Just JavaScript - A distilled mental model of how JavaScript works -- a way of thinking about JS that is intended to shift your understanding of the language. It's not free, but it's good.
• Fundamentals of HTML, SVG, CSS and JavaScript for Data Visualisation - An ideal foundation if you are looking for a straight-to-the-point guide to the languages driving web-based data visualization.
• D3 in Depth: Geographic - A detailed look at D3's approach to rendering geographic information.
• The A11Y Project - A community-driven effort to make web accessibility easier, which will be essential as you build intuitive interfaces.
• 18F Guide on Accessibility - From a collection of best practices and guides for building digital services, including web development and accessibility (archived from 18f.gsa.gov).
• FreeCodeCamp - Lots of exercises; courses in "Responsive Web Design", "Basic JavaScript", "ES6", and "Data Visualization" would be particularly useful for this class.
• Eloquent Javascript - This is a free book with some advanced content. As you think about the application you might like to build for your final, the chapters on HTML forms, drawing with JavaScript, building a game, and constructing your own painting application will push you further than we can in class.
• Map-based Web Application Examples

There will be additional resources on topics covered in the class in the resources/ folder.

Schedule

Subject to change as necessary!

Week	Date	Topic(s)	Learning Objective(s) (Students should be able to...)
1	26 Aug	Getting started Responsible use of AI coding assistants Project Introduction: Telling a Narrative	Know my name and what I do Describe what JavaScript is good for in planning and data Establish a responsible, documented workflow for using AI tools Identify a potential dataset and overarching narrative for the first project
2	02 Sep	Designing for the User Intro to Web Tech (HTML/CSS) Intro to Web Accessibility (A11y)	Describe the right questions to ask when starting a product Put together an HTML page structure with simple semantic tags Evaluate the accessibility of existing civic tech platforms using personas, developer tools, and WCAG criteria Identify when to use which CSS units
3	09 Sep	Using JavaScript on the Web Intro to Web Maps The GeoJSON Data Format	Create a script file to link to an HTML page Explain what a library, framework, and CDN are Import Leaflet for use and add a map to a page Explain the relationship between JSON and GeoJSON
4	16 Sep	The Box Model Flexbox and Grid Layouts Debugging layouts & specificity Asynchronous Behavior #1 (Events) JS Style & Linting	Explain an element's padding, margin, border, and width/height Create linear layouts with flexbox and tabular layouts with grid Use browser developer tools to inspect layouts and CSS specificity Use addEventListener to trigger JS on map and layer objects Use tools in VS Code to auto-format code and identify issues
5	23 Sep	Working with Data in JS (filtering, sorting, mapping, Turf.js) Charting libraries Organizing JavaScript Using Modules Project Introduction: Supporting Decisions	Use filter, map, and reduce functions to manipulate data Generate GeoJSON structures and chart configurations from other data formats Use import and export statements to organize code into modules Discuss the strengths, weaknesses, and alternatives to dashboards
6	30 Sep	DOM Manipulation Asynchronous behavior #2 (Requests, Timers)	Query, insert, and remove elements in the DOM Format a request URL with query string parameters Use GET and POST requests Explain the Promise vs async/await syntax of fetch
7	07 Oct	Map Tiles	Render vector vs raster images (SVG vs Canvas)
8	14 Oct	Browser APIs (Geolocation) 3rd-party APIs (Routing, Geocoding)	Access and utilize user geolocation data in the browser Integrate external APIs for routing and address translation
9	21 Oct	Project Introduction: Inviting Participation Browser-based data persistence (in-memory, session, and local storage)	Case Study: Bikeshare Station Suggestion Tool
10	28 Oct	Back-end as a Service (Firebase, Supabase) Remote data persistence (Firestore)	Set up and utilize a BaaS backend to persist and sync user-generated data
11	04 Nov	Reactive JavaScript patterns	Implement state management and reactive data binding
12	11 Nov	Front-end build tools	Utilize build tools (e.g., Vite) to prepare a client-side application for production
13	18 Nov	GIS Day @ Van Pelt, RDDSx
	25 Nov	(No class - Thanksgiving Break / Friday Schedule)
14	02 Dec	Project presentations

Academic Integrity

In compliance with Penn's Code of Academic Integrity, blatantly and egregiously copying another student's work will not be tolerated. However, because this course is designed to help prepare students for work in professional programming environments, copying and pasting is not universally prohibited: we encourage students to work together and to freely use the internet as a resource for finding solutions to vexing problems. Citing every copied and pasted line of code is not necessary. Large patterns or multiple lines of code taken from external sources should, however, be noted with in-code comments. If an instance is unclear, you should feel free to speak with the instructors.

Note about AI tools...

I actually want you to use AI tools (like ChatGPT, Claude, or GitHub Copilot) in this class. You should use them to explore repositories, ask how to make modifications to code, and act as a personalized tutor to go deeper on concepts we discuss in class.

However, you must use a responsible process. This course is about learning to program and design interfaces, not just learning how to prompt an agent. When you use AI to help write code, you must:

1. Make frequent Git commits so your progress is clear.
2. Document your LLM context (either via code comments or PR descriptions).
3. Deeply understand the code you are submitting.

Understand that these tools often make mistakes that can be difficult to identify if you don't know what you're doing. If you come to me or any other instructor to help debug something generated with AI, you must disclose the source of the code (we can usually tell anyway). The expectation is that you can explain why the code was written the way it was, not just that an AI generated it for you.