Forms

Relevant source files

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

• finder/forms.py
• finder/templates/finder/search.html
• finder/templates/finder/upload_excel.html
• finder/static/finder/js/scripts.js
• finder/static/finder/css/styles.css
• README.md

The roomfinder application utilizes Django's form handling capabilities to manage user input for both room searching and data administration. Two primary form classes, RoomSearchForm and ExcelUploadForm, are defined in finder/forms.py. These forms provide a structured way to receive and validate data from the user interface before it is processed by the backend views.

The forms are tightly integrated with the frontend templates and JavaScript, creating a responsive and user-friendly experience. RoomSearchForm powers the main search functionality on the home page, while ExcelUploadForm provides a drag-and-drop interface for uploading room and timetable data.

Form Class Diagram

The following diagram illustrates the structure of the two main form classes in the application.

RoomSearchForm

This form is the primary interface for users to find available rooms. It is rendered on the main search page and allows users to specify criteria to filter room availability.

Sources: finder/forms.py:7-60, finder/templates/finder/search.html:28-49

Fields

The form contains fields for specifying the building, day, and an optional time and duration for the search.

Field	Type	Label	Required	Description
building	ChoiceField	Building	True	A dropdown list of buildings. It is dynamically populated with an "All Buildings" option and all distinct buildings from the Room model.
day	ChoiceField	Day	True	A dropdown list of days from Monday to Friday.
time	TimeField	Start Time (Optional)	False	An optional time input for the start of the desired booking.
duration	IntegerField	Duration (minutes, optional)	False	An optional duration in minutes. The minimum value is 15 and the maximum is 480.

Sources: finder/forms.py:8-51

Dynamic Initialization

The building field's choices are not static. The form's __init__ method dynamically queries the Room model to get a distinct list of all buildings, prepending an "ALL" option to allow searching across all buildings.

# finder/forms.py:53-60
def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    buildings = Room.objects.values('building').distinct().order_by('building')
    building_choices = [("ALL", "All Buildings")] + [
        (b["building"], b["building"]) for b in buildings
    ]
    self.fields["building"].choices = building_choices

Sources: finder/forms.py:53-60

Frontend Integration and AJAX Submission

The RoomSearchForm is rendered within a sidebar on the main search page. The form submission is handled asynchronously using JavaScript.

1. The form is rendered in finder/templates/finder/search.html.
2. The finder/static/finder/js/scripts.js file intercepts the form's submit event.
3. It prevents the default page reload and sends the form data to the search_rooms view via an AJAX POST request.
4. The backend processes the request and returns an HTML partial (timeline_partial.html).
5. The JavaScript then injects this partial into the #results-container div, updating the timeline view without a full page refresh.

The following sequence diagram shows the AJAX search flow.

ExcelUploadForm

This form is used for administrative purposes to upload and process Excel files containing room and timetable data. It is rendered on a dedicated upload page and features a modern drag-and-drop interface.

Sources: finder/forms.py:63-107, finder/templates/finder/upload_excel.html:40-62

Fields

The form consists of two optional file fields.

Field	Type	Label	Required	Description
rooms_file	FileField	Rooms Excel File	False	For uploading an .xlsx or .xls file containing room data (e.g., Room, Building, capacity).
timetable_file	FileField	Timetable Excel File	False	For uploading an .xlsx or .xls file with schedule data (e.g., Course, Day/Time, Room).

Sources: finder/forms.py:64-81

Validation Logic

ExcelUploadForm includes several layers of custom validation to ensure data integrity and security.

1. Field-Level Validation (clean_<field_name>):
   • clean_rooms_file and clean_timetable_file methods check that the uploaded file has a valid Excel extension (.xlsx or .xls).
   • They also enforce a file size limit: 5MB for the rooms file and 10MB for the timetable file.
2. Form-Level Validation (clean):
   • The clean method ensures that the user has submitted at least one of the two files (rooms_file or timetable_file), raising a ValidationError if both are empty.

This validation flow ensures that only valid files are processed by the backend.

Drag-and-Drop Interface

The frontend for ExcelUploadForm provides a user-friendly drag-and-drop interface, enhancing the standard file input.

• HTML Structure: The upload_excel.html template uses div elements (.upload-drop-zone) styled to act as drop zones, with hidden input type="file" fields.
• CSS Styling: styles.css defines the appearance of the drop zones, with visual feedback for states like drag-over and file-selected.
• JavaScript Logic: scripts.js contains the setupDropZone function, which adds event listeners (dragover, dragleave, drop) to the drop zones. When a file is dropped, the script assigns it to the corresponding hidden file input and updates the UI to show the selected file's name.

Sources: finder/templates/finder/upload_excel.html:43-57, finder/static/finder/js/scripts.js:132-171, finder/static/finder/css/styles.css:417-456