135 lines
No EOL
5.2 KiB
Markdown
135 lines
No EOL
5.2 KiB
Markdown
# 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:
|
|
```python
|
|
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:
|
|
```bash
|
|
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 |