Feature: Room Details Modal
Relevant source files
The following files were used as context for generating this wiki page:The Room Details Modal is a UI component that provides users with comprehensive, on-demand information about a specific room without navigating away from the main search results page. When a user clicks on a room's timeline, a modal window appears, displaying the room's name, building, capacity, amenities, and its full schedule for the selected day.
This feature was implemented to address the need for more detailed room information beyond simple availability. It enhances the user experience by presenting a complete profile of a room in a "sleek, non-overwhelming" interface, allowing for better-informed decisions.
Sources: README.md:33-41
Component Breakdown
The modal is composed of three core frontend components: an HTML structure defined in the main template, CSS for styling and animation, and JavaScript for handling user interaction and data fetching.
HTML Structure
The modal's HTML is defined within finder/search.html. It consists of a main container (#room-modal) that acts as an overlay and a child content card (.modal-content) that holds the dynamic information. The content itself is populated by JavaScript.
<!-- Room Details Modal -->
<div id="room-modal" class="modal">
<div class="modal-content card">
<button class="close-button">×</button>
<div id="modal-body"></div>
</div>
</div>
Sources: finder/templates/finder/search.html:80-86
CSS Styling
The appearance and behavior of the modal are controlled by styles in styles.css. Key classes manage its visibility, positioning, and animations.
The following diagram shows the key CSS classes and their properties for the modal component.
A summary of the primary CSS classes is below:
| Class / ID | Purpose | File |
|---|---|---|
.modal | The main container and overlay. Hidden by default (display: none). | styles.css:371 |
.modal.show | Applied by JavaScript to make the modal visible (display: flex). | styles.css:387 |
.modal-content | The card that contains the room details. Includes a fade-in animation. | styles.css:389 |
.close-button | The '×' button to hide the modal. | styles.css:402 |
#modal-body | The container for dynamically injected room details and schedule. | styles.css:412 |
.schedule-list | A scrollable list for the room's daily schedule. | styles.css:428 |
Sources: finder/static/finder/css/styles.css:371-453
JavaScript Interaction
The client-side logic in scripts.js is responsible for the modal's entire lifecycle, from being triggered to being closed.
- Event Listening: An event listener is attached to the
results-container. It uses event delegation to detect clicks on any element with the.timeline-rowclass. - API Request: Upon a click, it extracts the
data-room-idfrom the clicked row and the selecteddayfrom the search form. It then makes an asynchronousfetchrequest to the/api/room/<room_id>/?day=<day>endpoint. - DOM Population: When the JSON data is received from the API, the script dynamically generates HTML for the room's details and schedule and injects it into the
#modal-bodyelement. - Display and Dismissal: The script adds the
.showclass to the modal container to display it. It also includes event listeners on the close button and the window to remove the.showclass, hiding the modal.
The following flowchart illustrates the JavaScript logic for displaying the modal.
Backend API
The modal is populated with data from a dedicated RESTful API endpoint.
API Endpoint
The endpoint provides detailed information for a single room.
| Method | Path | Description | Source File |
|---|---|---|---|
GET | /api/room/<int:room_id>/ | Retrieves details and a full-day timeline for a specific room. | README.md:114 |
Query Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
day | String | The day of the week (e.g., "Mon") for which to fetch the schedule. | Yes |
Sources: finder/static/finder/js/scripts.js:44, README.md:113-123
Data Payload
The API returns a JsonResponse containing an object with two main keys: room and timeline.
Example JSON Response Structure:
{
"room": {
"name": "AB101",
"building": "Apollo Building",
"capacity": 50,
"amenities": ["Projector", "Whiteboard"]
},
"timeline": [
{
"type": "free",
"start": "07:00",
"end": "09:00",
"course": null
},
{
"type": "booked",
"start": "09:00",
"end": "11:00",
"course": "CS101"
}
]
}
The backend ensures that time values (start and end) are formatted as strings (%H:%M) to prevent "undefined" errors in the frontend JavaScript.
Sources: finder/static/finder/js/scripts.js:47-65, README.md:121-123
End-to-End Data Flow
The following sequence diagram illustrates the complete interaction from a user's click to the modal being displayed with data.
This flow demonstrates how the frontend initiates a request based on user action, the backend processes this request by querying the database, and the frontend renders the response in the UI.
Sources: finder/static/finder/js/scripts.js:40-70, README.md:113-123, finder/views.py:38-51
Summary
The Room Details Modal is a key feature that significantly improves the application's usability. By leveraging a simple frontend structure, client-side JavaScript for dynamic interaction, and a dedicated backend API, it provides users with immediate access to detailed room schedules and attributes. This asynchronous, on-demand data loading creates a responsive and modern user experience.
Sources: README.md:33-41