URL Routing

Relevant source files

The following files were used as context for generating this wiki page: - [roomfinder/urls.py](https://github.com/Allen739/roomfinder/blob/HEAD/roomfinder/urls.py) - [finder/urls.py](https://github.com/Allen739/roomfinder/blob/HEAD/finder/urls.py) - [finder/views.py](https://github.com/Allen739/roomfinder/blob/HEAD/finder/views.py) - [roomfinder/settings.py](https://github.com/Allen739/roomfinder/blob/HEAD/roomfinder/settings.py) - [finder/static/finder/js/scripts.js](https://github.com/Allen739/roomfinder/blob/HEAD/finder/static/finder/js/scripts.js) - [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) - [README.md](https://github.com/Allen739/roomfinder/blob/HEAD/README.md)

URL routing in the Campuspal Room Finder project is handled by Django's URL dispatcher. The system follows a standard two-tiered approach, with a main project-level URL configuration that delegates to application-specific configurations. This creates a modular and maintainable structure, separating the finder app's endpoints from project-wide routes like the admin interface.

The routing configuration is responsible for mapping incoming URL requests to the appropriate view functions in finder/views.py. It defines paths for user-facing pages, such as the main search interface and the data upload page, as well as a JSON-based API endpoint used by the frontend for dynamically fetching room details.

Project-Level Routing

The entry point for all URL routing is defined in the roomfinder/settings.py file, which specifies the ROOT_URLCONF.

# roomfinder/settings.py
ROOT_URLCONF = "roomfinder.urls"

Sources: roomfinder/settings.py:59

This setting directs Django to use roomfinder/urls.py as the primary URL resolver. This file contains the project's main urlpatterns list. Its primary role is to include the URL configurations from other applications, in this case, the finder app.

# roomfinder/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("finder.urls", namespace="finder"))
]

Sources: roomfinder/urls.py:17-21

The configuration performs two key actions:

1. It maps the /admin/ path to the built-in Django admin site.
2. It uses include("finder.urls", namespace="finder") to pass any request to the root path ("") and all sub-paths to the finder/urls.py file for further processing. The namespace="finder" allows for unambiguous URL naming in templates and views.

The following diagram illustrates this delegation flow.

Application-Level Routing

The finder/urls.py file contains all URL patterns specific to the finder application. These patterns map directly to view functions that handle the application's logic.

Sources: finder/urls.py, README.md

URL Patterns

Based on the project's views, templates, and documentation, the URL patterns in finder/urls.py are as follows:

Path	View Function	URL Name	Description
""	views.home	home	The root URL of the app. Immediately redirects to the search_rooms view.
search/	views.search_rooms	search_rooms	The main room search page. Renders the search form and timeline results. Handles both GET requests and POST submissions for searching.
upload/	views.upload_excel	upload_excel	A page for staff to upload rooms.xlsx and timetable.xlsx files.
api/room/<int:room_id>/	api.room_details	room_details	A JSON API endpoint that returns detailed information and a full-day schedule for a specific room.

Sources: finder/urls.py, finder/views.py:15, 120, 270, finder/templates/finder/upload_excel.html:18, finder/static/finder/js/scripts.js:41, README.md

Main Page Request Flow

When a user first visits the site's root URL, they are immediately redirected to the main search page. This is handled by the home view.

This diagram shows the sequence of a user accessing the main search page.

API Endpoint Routing

The application exposes a RESTful API endpoint to provide data for dynamic frontend components, specifically the room details modal.

GET /api/room/<int:room_id>/

This endpoint is used to fetch details for a single room. The <int:room_id> part of the URL is a path converter that captures an integer from the URL and passes it as the room_id argument to the view.

The frontend JavaScript constructs and calls this URL when a user clicks on a room in the timeline.

// finder/static/finder/js/scripts.js
resultsContainer.addEventListener('click', function(e) {
    const timelineRow = e.target.closest('.timeline-row');
    if (timelineRow) {
        const roomId = timelineRow.dataset.roomId;
        const day = document.getElementById('id_day').value;
        fetch(`/api/room/${roomId}/?day=${day}`)
            .then(response => response.json())
            .then(data => {
                // ... populate modal with data ...
            });
    }
});

Sources: finder/static/finder/js/scripts.js:38-44

The following sequence diagram illustrates the interaction between the frontend and the room_details API endpoint.

Summary

The URL routing configuration in Campuspal Room Finder effectively uses Django's include mechanism to create a clean separation between project and app-level concerns. It defines clear, RESTful paths for both standard web pages and a dynamic JSON API. This structure supports the application's features, from initial page load and data submission to asynchronous data fetching for an interactive user experience.