Homework 8 - Lights Out: jQuery, AJAX, and PHP

This homework is optional as discussed in class.

Due: Monday, April 28, 2025 at 11:59pm

Purpose:

  • Gain experience writing in JavaScript using jQuery
  • Handle form data and manipulate the DOM using jQuery
  • Make AJAX calls using jQuery

Overview

For this homework, you may work alone or with another student in this course. You will implement the classic “Lights Out” game using jQuery in JavaScript.

Lights Out

Lights Out board

In the classic Lights Out game, users are presented with an n by m grid of boxes. For each box, the light is either off (a darker color) or on (a lighter color). When a user clicks any box in the grid, they toggle that box’s light. That is, if the light was off, it will turn on; if it was on, it will turn off. However, as a side-effect of toggling a light, all the adjacent (but NOT diagonal) lights will also toggle.

For example, consider the 3x3 grid below:
All lights off
In this grid, all the lights are off. If the user clicks to toggle the middle light, the adjacent 4 lights will turn on, as shown below:
Toggled middle light
Note that if the user clicks an edge box, not all adjacent boxes will exist, but all adjacent boxes that do exist will have their lights toggled.

The goal of the game is to turn off all the lights. The user wins when all the boxes are a dark color.

Requirements

For this assignment, you must implement a modified Lights Out game, in which the user can determine how large the game board is. Therefore, you must have the following components. (You may implement more functionality if you wish, but remember that we’ll be grading on effort in implementing these components specifically.)

Server-side Components

  1. Write a setup.php back-end file that accepts the number of rows and columns in the board as GET parameters (on the query string) and randomly select 10 starting positions–the boxes in the board where the lights will be on at the start of the game. Each position should be defined by its position–or row-column coordinate–in the board. This script must return a JSON object with the list of the lights-on starting positions.
    • If the board has less than 10 boxes, then your setup.php file should return a JSON object with the list of all positions (all lights are on).

Client-side Components

  1. Write your client-side application in an index.html file. It must contain the following form elements for the user to specify the game’s set up:
    • A form input for the size of the board. This number will be used to create a square board with the same number of rows and columns.
    • A button that allows the user to start the game of the specified size.
  2. You must implement the following event handlers in JavaScript (bind with jQuery):
    1. Start the game: When the user clicks the start game button, this event handler will read the number of rows and columns entered by the user, query the back-end using jQuery’s AJAX methods for which lights to turn on at the start of the game, then add the board to the page below the form.
      • You must use jQuery to make the AJAX call to the server to get the lighted positions, then use jQuery to modify the DOM to display the board. Do NOT directly use XMLHttpRequest.
      • When displaying the board, it’s up to you to determine the best HTML elements to use and how the board looks. However, it must still be a grid of square boxes that the user can click on.
      • If the user clicks the start game button during the game, the old game should end and a new board be displayed.
    2. Clicking a box: When the user clicks a box in the board, the event handler will toggle this box’s light as well as the lights of the adjacent boxes, then check to see if the user has won the game. If the user has won, a message should be displayed and they should not be able to toggle any more lights on the board.
      • The design of the “You’ve won!” message is up to you. Be creative.
      • The user should be able to start a new game with the start game button after they have won. The message should be hidden by the time the new game starts.
  3. Note: For this assignment, you must use jQuery’s methods for selecting elements, updating the DOM, and making AJAX calls. Do not use document.getElementById().

Helpful Hints

  1. You may include your JavaScript code directly in your index.html file or write a separate .js file and include it in index.html.
  2. There are many options for how to display the board. It might be most useful to use a <table> with CSS styling to ensure square boxes.
  3. It might be helpful to determine how to identify the boxes in the board; consider encoding information in an id or class attribute on each HTML element in the board.

Submission

The submission will consist of two parts:

  1. Submit your code (PHP, HTML, and JS if desired) to Gradescope in the “Homework 8” submission. You may choose to upload the files individually, upload a zip folder, or upload from a GitHub repository.
    • You must include a link to your published version in the comments of your index.html page, or you will not receive credit!
  2. Publish your web site to the cs4640 server under a folder titled “hw8”. Therefore, we should be able to access your work at https://cs4640.cs.virginia.edu/yourid/hw8. If you work with a partner, each person should publish the work to their web space.

Grading Rubric

This homework is worth 50 points, based on the following rubric:

  • 10 points - Server-side setup logic
  • 10 points - Client-side display (input boxes, board display)
  • 15 points - Start the game event handler (using jQuery) with AJAX
  • 10 points - Click a box event handler (using jQuery)
  • 5 points - Publish your website to the cs4640 server

Academic Integrity

For this assignment, you are welcome to share/publish your website! You’ll be doing that on our cs4640 server as well. We only ask that you not make any GitHub projects public until after the deadline.

However, we will consider it an honor code violation to view any other student or team’s code or submission before the deadline. Your submitted code should reflect you (and your partner’s) work alone, not that of another student or team.

Note: You must cite any sources you use in a comment at the top of your index.html file. For example:

<?php
// Sources used: https://cs4640.cs.virginia.edu, ...

...

Use of Generative AI

For Homework 8, you are not allowed to use generative AI tools to help you solve this problem.