Key Features

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• finder/views.py
• finder/static/finder/js/scripts.js
• finder/static/finder/css/styles.css
• finder/templates/finder/search.html
• finder/templates/finder/upload_excel.html
• generate_sample_data.py
• roomfinder/settings.py
• CONTRIBUTING.md
• TODO.md

The Campuspal Room Finder is a web application designed to help students and staff find available rooms on campus. It transforms a basic list-based search into a modern, visual, and intuitive experience. The core features focus on providing an at-a-glance overview of room availability, detailed room information on demand, and a powerful, categorized search.

The application is built on Django, with a dynamic frontend that uses AJAX for a seamless user experience without page reloads. Key features include a visual timeline, a detailed room profile modal, enhanced time-based searching, a tabbed results interface, and a robust data management system via Excel uploads and sample data generation.

Sources: README.md:3-5, README.md:19-25

Enhanced Search and Visual Timeline

The primary feature is the ability to search for rooms and view their availability on a visual timeline. This provides a comprehensive overview of all room schedules for a selected building and day, making it easy to spot open slots.

Sources: README.md:27-32

Search and Categorization Logic

The search functionality is handled by the search_rooms view. It accepts POST requests from the search form, which can include building, day, and optional start time and duration.

1. The view fetches all rooms for the selected building (or all buildings).
2. For each room, it constructs a timeline list representing the day from 7 AM to 11 PM. This list contains "free" and "booked" blocks based on ClassSchedule entries.
3. If a time and duration are specified in the search, the backend calculates the required time window. It then iterates through each room's timeline to check if this window fits within a single "free" block.
4. Based on this check, rooms are categorized into available_rooms and unavailable_rooms lists. If no time is specified, all rooms are placed in the unavailable_rooms list for general browsing.

This entire process is triggered via an AJAX request, and the server responds by rendering a partial HTML template (timeline_partial.html) to dynamically update the results on the page.

Sources: finder/views.py:15-80, finder/static/finder/js/scripts.js:8-27

The following diagram illustrates the data flow for a search request.

Visual Timeline Rendering

The backend calculates positioning and width percentages for each timeline block. These are passed to the frontend and used by CSS to visually represent the schedule.

• start_percentage: Determines the left position of the block.
• width_percentage: Determines the width of the block.

The timeline itself is styled with a grid background to represent time intervals, and blocks are colored differently for "free" (green) and "booked" (red) states, with subtle animated patterns for better visual distinction.

Sources: finder/views.py:88-91, finder/static/finder/css/styles.css:307-353

Detailed Room Profile Modal

Users can click on any room's timeline to view more details in a modal window without leaving the page.

API and Frontend Interaction

1. A click event on a .timeline-row is captured by the frontend JavaScript.
2. The data-room-id attribute is extracted from the clicked element.
3. An AJAX GET request is sent to the /api/room/<room_id>/?day=<day> endpoint.
4. The backend API (described in README.md and handled by scripts.js) returns a JSON object with the room's details (name, capacity, amenities) and its full daily schedule.
5. The JavaScript dynamically populates the modal's HTML with this data and displays it.

Sources: finder/static/finder/js/scripts.js:41-71, README.md:112-121

The sequence diagram below shows the interaction for fetching and displaying room details.

The modal displays the following room information:

• Name and Building
• Capacity
• Amenities (e.g., Projector, Whiteboard)
• A chronological list of the day's schedule, showing free and booked slots.

Sources: finder/static/finder/js/scripts.js:50-66

UI/UX and Interface Components

The application features a modern UI/UX design with several key components that enhance usability.

Tabbed Interface

When a search yields results, they are organized into "Available" and "Unavailable" tabs.

• Implementation: This is handled entirely on the client side. The search_rooms view renders the content for both tabs, and JavaScript toggles the .active class on the tab links and content panes based on user clicks. This provides instant feedback without another server request.

Sources: finder/static/finder/js/scripts.js:86-100, finder/static/finder/css/styles.css:249-277, finder/templates/finder/search.html:68-73

Styling and Design

The visual design is defined in finder/static/finder/css/styles.css. It employs a modern aesthetic with:

• CSS Variables: A comprehensive set of HSL-based color variables for easy theming and a defined dark mode.
• Layout: A responsive layout using Flexbox and a sticky sidebar for the search form.
• Component Styling: Custom styles for cards, forms, buttons, and the modal to create a consistent and polished look.
• Micro-interactions: Subtle animations on timeline blocks and modals for a more dynamic feel.

Sources: finder/static/finder/css/styles.css:1-45, finder/static/finder/css/styles.css:135-150, finder/static/finder/css/styles.css:355-363

Data Management

The application relies on a robust system for generating and importing data.

Sample Data Generation

A script, generate_sample_data.py, is provided to create realistic test data. This is crucial for development, testing, and demonstrating the application's capabilities.

The script generates two Excel files: rooms.xlsx and timetable.xlsx.

File	Generated Data Fields	Description
rooms.xlsx	Room, Building, capacity, amenities, photo_url	Creates a list of rooms with detailed attributes.
timetable.xlsx	Course, Subject, Day/Time, Room, Building, Lecturer	Creates a list of class schedules, randomly assigning them to rooms and times.

Sources: generate_sample_data.py, README.md:78-84

Excel Data Upload

Administrators can upload room and timetable data directly through the UI.

• Interface: The /upload/ page provides a drag-and-drop interface for uploading rooms.xlsx and timetable.xlsx files.
• Backend Logic: The upload_excel view in finder/views.py handles the file processing. It uses the pandas library to read the Excel files into DataFrames.
• Processing: The view iterates through the rows of the DataFrames, validates the data (e.g., checking for valid day formats), and creates or updates Room and ClassSchedule objects in the database. It provides feedback to the user via Django's messaging framework.

Sources: finder/views.py:103-222, finder/templates/finder/upload_excel.html

The following diagram shows the Excel upload process.

Summary

The key features of the Campuspal Room Finder work together to create a powerful and user-friendly tool. The visual timeline provides an immediate, high-level understanding of room availability, while the on-demand modal offers deep-dive details. The enhanced search and categorization logic ensures users can find exactly what they need, and the client-side tabbed interface makes browsing results effortless. These frontend features are supported by a robust Django backend with flexible data management capabilities, including sample data generation and Excel-based imports.

Sources: README.md:19-84