tykayn/oedb-backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oedb-backend/doc/demo_endpoint.md
Tykayn 1048f4af45 up static routes
2025-09-21 16:57:24 +02:00

5.2 KiB
Raw Blame History

Demo Endpoint Implementation

Overview

A new endpoint /demo has been added to the OpenEventDatabase API. This endpoint serves an interactive HTML page with a MapLibre map that displays current events from the database.

Features

  • Interactive MapLibre map showing current events
  • Events are fetched from the /event endpoint with the current date
  • Each event is displayed as a marker on the map
  • Clicking on a marker shows a popup with event details
  • The map automatically zooms to fit all displayed events
  • Sidebar with links to other API endpoints and the GitHub repository

Implementation Details

The implementation consists of the following components:

  1. DemoResource Class: A new resource class in oedb/resources/demo.py that handles GET requests to the /demo endpoint and returns an HTML page.

  2. HTML Page: The HTML page includes:

    • MapLibre JS and CSS libraries
    • Custom CSS for styling the page
    • A full-screen map
    • A sidebar with information and links

  3. JavaScript: The JavaScript code:

    • Initializes a MapLibre map
    • Fetches events from the /event endpoint
    • Displays events as markers on the map
    • Creates popups with event details
    • Fits the map view to include all events

  4. Route Registration: The /demo endpoint is registered in backend.py with the line:

    app.add_route('/demo', demo)

  5. Documentation: The root endpoint (/) has been updated to include information about the demo endpoint.

How to Test

To test the demo endpoint:

  1. Start the server:

    python3 backend.py

  2. Open a web browser and navigate to:

    http://127.0.0.1:8080/demo

  3. Verify that:

    • The page loads correctly with a MapLibre map
    • Events are displayed on the map (if there are events for the current date)
    • Clicking on a marker shows a popup with event details
    • Links to other endpoints work correctly

Troubleshooting

If no events appear on the map:

  1. Check if there are events for the current date in the database
  2. Try adding a test event using the /event endpoint
  3. Check the browser console for any JavaScript errors
  4. Verify that the /event endpoint is working correctly by accessing it directly

Additional Demo Pages

The demo section includes several specialized pages:

  1. Main Demo Page (/demo): Shows a map with all current events
  2. Search Page (/demo/search): Provides advanced search functionality
  3. Events by Type (/demo/by-what): Lists events grouped by their type
  4. Map by Event Type (/demo/map-by-what): Shows events on a map with filtering by type
  5. Add Event (/demo/add): Form for adding new events
  6. Edit Event (/demo/edit/{id}): Form for editing existing events
  7. Traffic Jam Reporting (/demo/traffic): Form for reporting traffic jams with geolocation

Traffic Jam Reporting Page

The traffic jam reporting page (/demo/traffic) provides a specialized form for reporting traffic jams. Features include:

  • Button to automatically detect the user's current location using browser geolocation
  • Map for selecting the location of the traffic jam
  • Form fields for traffic jam details (description, severity, cause, etc.)
  • Automatic reverse geocoding to determine the road/location name
  • Submission to the API as a traffic.jam event type
  • OpenStreetMap OAuth2 authentication to include the reporter's OSM username in the event

OpenStreetMap Authentication

All demo pages include OAuth2 authentication with OpenStreetMap:

  • Users can authenticate with their OpenStreetMap account on any demo page
  • Authentication state is shared across all demo pages using localStorage
  • After authentication, the user's OSM username and a link to their profile are displayed
  • When submitting reports or creating events, the OSM username is included in the event properties as reporter:osm
  • OAuth2 configuration parameters are stored in the .env file:
    • CLIENT_ID: The OAuth2 client ID for the application
    • CLIENT_SECRET: The OAuth2 client secret for the application
    • CLIENT_AUTORIZATIONS: The permissions requested (default: "read_prefs")
    • CLIENT_REDIRECT: The redirect URL after authentication

Common Styling

All demo pages share a common CSS style for consistent look and feel:

  • Common CSS file located at /static/demo/demo_styles.css
  • Improved styling for the OpenStreetMap login button
  • Consistent styling for forms, buttons, and other UI elements
  • Responsive design for better mobile experience

JavaScript Modules

The demo pages use JavaScript modules for shared functionality:

  • Authentication module located at /static/demo/demo_auth.js
  • Handles OAuth2 authentication flow with OpenStreetMap
  • Stores and retrieves authentication information in localStorage
  • Provides methods for checking authentication status and getting user information

Future Improvements

Potential future improvements for the demo pages:

  1. Add date selection to view events from different dates
  2. Add more filtering options (by event type, location, etc.)
  3. Add a search box to find specific events
  4. Improve the mobile experience
  5. Add more interactive features to the map
  6. Expand the traffic reporting functionality to include other traffic-related events