Home

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Allen739/roomfinder/blob/HEAD/README.md) - [finder/static/finder/js/scripts.js](https://github.com/Allen739/roomfinder/blob/HEAD/finder/static/finder/js/scripts.js) - [finder/static/finder/css/styles.css](https://github.com/Allen739/roomfinder/blob/HEAD/finder/static/finder/css/styles.css) - [finder/templates/finder/search.html](https://github.com/Allen739/roomfinder/blob/HEAD/finder/templates/finder/search.html) - [finder/templates/finder/upload_excel.html](https://github.com/Allen739/roomfinder/blob/HEAD/finder/templates/finder/upload_excel.html) - [generate_sample_data.py](https://github.com/Allen739/roomfinder/blob/HEAD/generate_sample_data.py) - [roomfinder/settings.py](https://github.com/Allen739/roomfinder/blob/HEAD/roomfinder/settings.py) - [CONTRIBUTING.md](https://github.com/Allen739/roomfinder/blob/HEAD/CONTRIBUTING.md) - [TODO.md](https://github.com/Allen739/roomfinder/blob/HEAD/TODO.md)

The Home page, also known as the Campuspal Room Finder, is the main user interface of the application. It provides a modern, intuitive experience for students and staff to find available rooms on campus. The core functionality revolves around a powerful search form, a visual timeline of room availability, and a detailed modal view for specific room information. The entire interface is designed to be sleek, responsive, and user-friendly.

The page is served from the root URL (/) and is handled by the search_rooms view, which also processes search requests. It is built as a single-page experience, using AJAX to update search results dynamically without full page reloads.

Sources: README.md:1-5, 80-82, finder/templates/finder/search.html, finder/static/finder/js/scripts.js:5-32

Key Features

The Home page integrates several key features to provide a comprehensive room finding experience.

Feature	Description	Source Files
Visual Timeline View	Displays all rooms for a selected building and day, with booked (red) and free (green) slots shown as horizontal blocks. Provides an at-a-glance overview of room schedules.	README.md:30-36
Detailed Room Profile Modal	A modal window triggered by clicking a room. It shows room details (capacity, amenities) and a full chronological schedule for the selected day.	README.md:38-46
Enhanced Time-Based Search	Allows users to optionally specify a start time and duration. Results are then categorized into "Available" and "Unavailable" rooms.	README.md:48-57
Tabbed Interface	Organizes search results into "Available" and "Unavailable" tabs, allowing users to toggle between views for clarity. The toggling is handled client-side.	README.md:59-64
AJAX-Powered Search	Submits search criteria without a page reload, dynamically updating the results section for a seamless user experience.	finder/static/finder/js/scripts.js:5-23
Responsive UI/UX	A complete UI overhaul inspired by modern applications, featuring a card-based layout, refined typography, a harmonious color palette, and a responsive design for various screen sizes.	README.md:66-77

Architecture and Data Flow

The Home page operates on a client-server model where the frontend (HTML/CSS/JS) interacts with the Django backend via standard page loads and asynchronous API calls.

High-Level Component Interaction

This diagram shows the main components and their interactions when a user searches for a room.

AJAX Search Flow

When a user submits the search form, the request is handled by JavaScript to prevent a full page reload.

This flow illustrates the dynamic update of the search results.
Sources: README.md:103-104, finder/static/finder/js/scripts.js:5-23

Room Details Modal Flow

Clicking on a room in the timeline triggers a separate AJAX call to fetch detailed information for that specific room.

This flow shows how the modal is populated with on-demand data.
Sources: README.md:108-118, finder/static/finder/js/scripts.js:35-61

Frontend Implementation

The frontend is composed of the HTML structure, CSS styling, and JavaScript for interactivity.

Sources: finder/templates/finder/search.html, finder/static/finder/css/styles.css, finder/static/finder/js/scripts.js

Page Structure (search.html)

The main layout is defined in finder/templates/finder/search.html and uses a two-column design.

• Header: Contains the application title "Campuspal" and navigation links to "Upload Data" and a theme toggle button.
• Sidebar (<aside class="sidebar">): A sticky container on the left that holds the search form card.
• Main Content (<section class="results-section">): The right-hand section that displays the search results within an element with the ID results-container. Initially, it shows a welcome message.
• Modal (<div id="room-modal">): A hidden modal structure at the end of the body, which is shown by JavaScript to display room details.

Sources: finder/templates/finder/search.html:15-72

Search Form

The search form allows users to filter rooms.

Field	HTML Element	Description	Required
Building	{{ form.building }}	A dropdown to select a campus building or "ALL".	Yes
Day	{{ form.day }}	A dropdown to select the day of the week.	Yes
Time	{{ form.time }}	A time input for the desired start time.	No
Duration	{{ form.duration }}	A dropdown to select the desired duration.	No

Sources: README.md:135-140, finder/templates/finder/search.html:31-48

Styling (styles.css)

The application's visual identity is defined in finder/static/finder/css/styles.css. It establishes a modern and clean aesthetic.

• Color Palette: Uses HSL variables for easy theming, with a primary color (--primary-color), success (--success-color), and danger (--danger-color) states.
• Layout: Employs Flexbox for the main layout (.main-content) and a sticky sidebar (.sidebar-inner).
• Components:
  • Cards (.card): Used for the search form and modal, featuring a subtle gradient, rounded corners, and a box shadow.
  • Timeline (.timeline-row, .timeline-block): The core visual element. Free slots have an animated green stripe pattern, while booked slots have a static red stripe pattern.
  • Modal (.modal): A full-screen overlay with a blurred backdrop (backdrop-filter: blur(8px)) and a centered content card.
• Responsiveness: Media queries (@media (max-width: 768px)) adapt the layout for smaller screens, stacking the sidebar and main content vertically.

Sources: finder/static/finder/css/styles.css:1-51, 137-141, 281-301, 461-470, README.md:150-163

Client-Side Logic (scripts.js)

All interactivity on the home page is managed by finder/static/finder/js/scripts.js.

• Event Delegation: The primary event listeners for modal triggers and tab toggling are attached to the resultsContainer to handle dynamically added content.
• AJAX Search: An event listener on the search form's submit event intercepts the submission, uses the fetch API to send a POST request with form data, and injects the HTML response into the #results-container.
• Modal Population: A click listener on .timeline-row fetches room details from the /api/room/<room_id>/ endpoint. It then dynamically builds the HTML for the modal body and adds the .show class to the modal element to display it.
• Tab Toggling: A click listener on .tab-link elements manages .active classes on tabs and tab content panes to show/hide the "Available" and "Unavailable" sections.

Sources: finder/static/finder/js/scripts.js:5-102

Backend Implementation

The backend logic is handled by the Django finder app.

Sources: README.md:84-118, roomfinder/settings.py:38-39

search_rooms View

This view, described in finder/views.py, is the engine behind the home page.

1. Input Handling: Accepts building, day, and optional time and duration from the form submission.
2. Timeline Generation: For the selected day and building(s), it fetches all rooms and their corresponding schedules. It constructs a timeline list for each room, representing the day from 7 AM to 11 PM with "free" and "booked" blocks. Each block includes start_percentage and width_percentage for accurate CSS rendering.
3. Availability Check: If time and duration are provided, it iterates through each room's timeline to check if the requested slot fits within a single "free" block.
4. Categorization: Rooms are sorted into available_rooms and unavailable_rooms lists based on the availability check.
5. Response:
   • For a standard GET request, it renders the full search.html template.
   • For an AJAX request (identified by the X-Requested-With header), it renders only the timeline_partial.html template and returns it as an HTML fragment.

Sources: README.md:86-104

room_details API Endpoint

This API endpoint, described in finder/api.py, provides data for the room details modal.

• URL: /api/room/<int:room_id>/
• Method: GET
• Query Parameters:
  • day: The day to fetch the schedule for (e.g., Mon).
• Success Response (200 OK): Returns a JsonResponse containing the room's attributes (name, building, capacity, amenities) and its full daily timeline. Times are formatted as strings (%H:%M) for consistent frontend rendering.

Sources: README.md:106-118, finder/static/finder/js/scripts.js:39-41

Conclusion

The Home page is the central and most feature-rich component of the Campuspal Room Finder. It successfully combines a powerful, direct search with a rich, contextual timeline view. Through a modern frontend architecture using AJAX for dynamic updates and a well-structured Django backend, it provides a seamless and intuitive user experience for finding available campus rooms.

Sources: README.md:1-5, 209-216