Views and Business Logic

Relevant source files

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

• finder/views.py
• finder/models.py
• finder/static/finder/js/scripts.js
• finder/templates/finder/search.html
• finder/templates/finder/upload_excel.html
• README.md
• generate_sample_data.py

The business logic of the Campuspal Room Finder application is primarily handled within the finder app's views.py file. These views are responsible for processing user requests, interacting with the database models, and rendering the appropriate HTML templates or JSON responses. The core functionality revolves around two main operations: searching for room availability and uploading room/schedule data from Excel files.

The views are designed to support a dynamic, AJAX-driven frontend, allowing for a responsive user experience. The search_rooms view generates a comprehensive daily timeline for rooms, while the upload_excel view provides an administrative interface for bulk data management.

Key Views and Functions

The application's server-side logic is encapsulated in three main view functions.

Function	URL Path	Description
search_rooms	/	Handles room searching and timeline display. Responds to both standard page loads and AJAX requests.
upload_excel	/upload/	Provides a form for staff to upload rooms.xlsx and timetable.xlsx files to populate the database.
home	(Not directly mapped, used for redirect)	A simple view that redirects the root URL to the search_rooms view.

Sources: finder/views.py:16-271, README.md:200-204

Room Search Logic (search_rooms)

This is the primary view for users. It handles the logic for displaying room schedules and filtering for availability based on user-submitted criteria.

Sources: finder/views.py:16-116

Request Handling and Data Flow

The search_rooms view processes both GET requests (for initial page load) and POST requests (when a user submits the search form). It is designed to work with AJAX to provide a seamless update of the results without a full page reload.

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

Sources: finder/views.py:20-116, finder/static/finder/js/scripts.js:6-25

Timeline Generation

A core feature is the generation of a daily timeline (7 AM to 11 PM) for each room. The view constructs this timeline by:

1. Fetching all non-cancelled ClassSchedule entries for a given room and day, ordered by start_time.
2. Initializing a last_end_time to 7:00 AM.
3. Iterating through the schedules:
   • If a gap exists between last_end_time and the current schedule's start_time, a "free" block is created for that gap.
   • A "booked" block is created for the duration of the current schedule.
   • last_end_time is updated to the current schedule's end_time.
4. After the loop, if last_end_time is before 11:00 PM, a final "free" block is added to fill the rest of the day.

This process results in a list of dictionaries, where each dictionary represents a block of time.

Sources: finder/views.py:42-59

Availability Check

If the user provides a specific start time and duration, the view performs an availability check. A room is marked as "available" only if the requested time slot fits entirely within a single "free" block in its generated timeline.

# finder/views.py:70-76
for block in room_data["timeline"]:
    if block["type"] == "free":
        # Check if the search window fits entirely within this free block
        if block["start"] <= search_start_time and block["end"] >= search_end_time:
            is_available = True
            break

Sources: finder/views.py:64-79

Data Structure for Frontend

To render the timeline visually, the view calculates percentage-based values for positioning and width. This offloads the complex time-to-pixel conversion from the frontend.

Key	Type	Description
type	string	"free" or "booked".
start	datetime.time	The start time of the block.
end	datetime.time	The end time of the block.
course	string	The course name if the block is "booked".
start_percentage	float	The block's start position as a percentage of the total timeline width (7 AM - 11 PM).
width_percentage	float	The block's duration as a percentage of the total timeline width.

Sources: finder/views.py:88-94

Excel Data Upload (upload_excel)

This view is restricted to staff members and provides a mechanism to populate or overwrite the Room and ClassSchedule data from .xlsx files.

Sources: finder/views.py:118-265

File Processing Logic

The view uses the pandas library to read data from two uploaded files: rooms_file and timetable_file. Before processing, it clears all existing data from the corresponding database tables.

The flow for processing the timetable file is as follows:

Sources: finder/views.py:151-260

Expected Excel Formats

The view expects specific column names in the uploaded files.

rooms.xlsx

Column	Description
Room	The name/number of the room (e.g., "HH101").
Building	The building name (e.g., "Hephaestus Hall").
capacity	The seating capacity of the room.
amenities	A JSON string representing a list of amenities (e.g., ["Projector"]).
photo_url	A URL to an image of the room.

Sources: finder/views.py:130-132, generate_sample_data.py:43-45, finder/models.py:6-10

timetable.xlsx

Column	Description
Course	The course code (e.g., "CS101").
Subject	The full subject name.
Day/Time	A string representing the schedule (e.g., "Mon 9:00-10:30").
Room	The name of the room, must match a name in the Room table.
Building	The building of the room, must match a building in the Room table.
Lecturer	The name of the lecturer.

Sources: finder/views.py:154-160, generate_sample_data.py:68-70

The Day/Time column is parsed using a regular expression to extract the day, start time, and end time.

# finder/views.py:180-184
match = re.match(
    r"(?P<day>\w+)\s+(?P<start>\d{1,2}:\d{2}\s*"
    r"(?:AM|PM)?)[-–](?P<end>\d{1,2}:\d{2}\s*"
    r"(?:AM|PM)?)",
    day_time)

Sources: finder/views.py:180-184

Database Model Interaction

The views heavily rely on the Room and ClassSchedule models. The relationship between these two models is central to the application's logic.

Sources: finder/models.py:6-57

The search_rooms view uses prefetch_related('schedules') to efficiently query all schedules for a set of rooms, minimizing database hits.

Sources: finder/views.py:32

Conclusion

The views in finder/views.py form the core of the application's backend logic. They effectively handle user input for both searching and data administration. The search_rooms view implements a sophisticated timeline generation and availability-checking algorithm, passing carefully structured data to the frontend for rendering. The upload_excel view provides a robust data ingestion pipeline using pandas for parsing and includes comprehensive validation and error reporting. Together, these components create a powerful and responsive system for finding and managing room schedules.