admin/freealberta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
freealberta/mkdocs/docs/manual/map.md

18 KiB
Raw Blame History

Map System Manual

This comprehensive manual covers all features of the Map System - a powerful campaign management platform with interactive mapping, volunteer coordination, data management, and communication tools. (Insert screenshot - feature overview)

1. Getting Started

Logging In

  1. Go to your map site URL (e.g., https://yoursite.com or http://localhost:3000).
  2. Enter your email and password on the login page.
  3. Click Login.
  4. If you forget your password, use the Reset Password link or contact an admin.
  5. Password Recovery: Check your email for reset instructions if SMTP is configured. (Insert screenshot - login page)

User Types & Permissions

  • Admin: Full access to all features, user management, and system configuration
  • User: Access to map, shifts, profile management, and location data
  • Temp: Limited access (add/edit locations only, expires automatically after shift date)

2. Interactive Map Features

Basic Map Navigation

  1. After login, you'll see the interactive map with location markers.
  2. Use mouse or touch to pan and zoom around the map.
  3. Your current location may appear as a blue dot (if location services enabled).
  4. Use the zoom controls (+/-) or mouse wheel to adjust map scale. (Insert screenshot - main map view)

Advanced Search (Ctrl+K)

  1. Press Ctrl+K anywhere on the site to open the universal search.
  2. Search for:
    • Addresses: Find and navigate to specific locations
    • Documentation: Search help articles and guides
    • Locations: Find existing data points by name or details
  3. Click results to navigate directly to locations on the map.
  4. QR Code Generation: Search results include QR codes for easy mobile sharing. (Insert screenshot - search interface)

Map Overlays (Cuts)

  1. Public Cuts: Geographic overlays (wards, neighborhoods, districts) are automatically displayed.
  2. Cut Selector: Use the multi-select dropdown to show/hide different cuts.
  3. Mobile Interface: On mobile, tap the 🗺️ button to manage overlays.
  4. Legend: View active cuts with color coding and labels.
  5. Cuts help organize and filter location data by geographic regions. (Insert screenshot - cuts interface)

3. Location Management

Adding New Locations

  1. Click the Add Location button (+ icon) on the map.
  2. Click on the map where you want to place the new location.
  3. Fill out the comprehensive form:
    • Personal: First Name, Last Name, Email, Phone, Unit Number
    • Political: Support Level (1-4 scale), Party Affiliation
    • Address: Street Address (auto-geocoded when possible)
    • Campaign: Lawn Sign (Yes/No/Maybe), Sign Size, Volunteer Interest
    • Notes: Additional information and comments
  4. Address Confirmation: System validates and confirms addresses when possible.
  5. Click Save to add the location marker. (Insert screenshot - add location form)

Editing and Managing Locations

  1. Click on any location marker to view details.
  2. Popup Actions:
    • Edit: Modify all location details
    • Move: Drag marker to new position (admin/user only)
    • Delete: Remove location (admin/user only - hidden for temp users)
  3. Quick Actions: Email, phone, or text contact directly from popup.
  4. Support Level Color Coding: Markers change color based on support level.
  5. Apartment View: Special clustering for apartment buildings. (Insert screenshot - location popup)

Bulk Data Import

  1. Admin Panel → Data Converter → Upload CSV
  2. Supported Formats: CSV files with address data
  3. Batch Geocoding: Automatically converts addresses to coordinates
  4. Progress Tracking: Visual progress bar with success/failure reporting
  5. Error Handling: Downloadable error reports for failed geocoding
  6. Validation: Preview and verify data before final import
  7. Edmonton Data: Pre-configured for City of Edmonton neighborhood data. (Insert screenshot - data import interface)

4. Volunteer Shift Management

Public Shift Signup (No Login Required)

  1. Visit the Public Shifts page (accessible without account).
  2. Browse available volunteer opportunities with:
    • Date, time, and location information
    • Available spots and current signups
    • Detailed shift descriptions
  3. One-Click Signup:
    • Enter name, email, and phone number
    • Automatic temporary account creation
    • Instant email confirmation with login details
  4. Account Expiration: Temp accounts automatically expire after shift date. (Insert screenshot - public shifts page)

Authenticated User Shift Management

  1. Go to Shifts from the main navigation.
  2. View Options:
    • Grid View: List format with detailed information
    • Calendar View: Monthly calendar with shift visualization
  3. Filter Options: Date range, shift type, and availability status.
  4. My Signups: View your confirmed shifts at the top of the page.

Shift Actions

  • Sign Up: Join available shifts (if spots remain)
  • Cancel: Remove yourself from shifts you've joined
  • Calendar Export: Add shifts to Google Calendar, Outlook, or Apple Calendar
  • Shift Details: View full descriptions, requirements, and coordinator info. (Insert screenshot - shifts interface)

5. Advanced Map Features

Geographic Cuts System

What are Cuts?: Polygon overlays that define geographic regions like wards, neighborhoods, or custom areas.

Viewing Cuts (All Users)

  1. Auto-Display: Public cuts appear automatically when map loads.
  2. Multi-Select Control: Desktop users see dropdown with checkboxes for each cut.
  3. Mobile Modal: Touch the 🗺️ button for full-screen cut management.
  4. Quick Actions: "Show All" / "Hide All" buttons for easy control.
  5. Color Coding: Each cut has unique colors and opacity settings. (Insert screenshot - cuts display)

Admin Cut Management

  1. Admin Panel → Map Cuts for full management interface.
  2. Drawing Tools: Click-to-add-points polygon creation system.
  3. Cut Properties:
    • Name, description, and category
    • Color and opacity customization
    • Public visibility settings
    • Official designation markers
  4. Cut Operations:
    • Create, edit, duplicate, and delete cuts
    • Import/export cut data as JSON
    • Location filtering within cut boundaries
  5. Statistics Dashboard: Analyze location data within cut boundaries.
  6. Print Functionality: Generate professional reports with maps and data tables. (Insert screenshot - cut management)

Location Filtering within Cuts

  1. View Cut: Select a cut from the admin interface.
  2. Filter Locations: Automatically shows only locations within cut boundaries.
  3. Statistics Panel: Real-time counts of:
    • Total locations within cut
    • Support level breakdown (Strong/Lean/Undecided/Opposition)
    • Contact information availability (email/phone)
    • Lawn sign placements
  4. Export Options: Download filtered location data as CSV.
  5. Print Reports: Generate professional cut reports with statistics and location tables. (Insert screenshot - cut filtering)

6. Communication Tools

Universal Search & Contact

  1. Ctrl+K Search: Find and contact anyone in your database instantly.
  2. Direct Contact Links: Email and phone links throughout the interface.
  3. QR Code Generation: Share contact information via QR codes.

Admin Communication Features

  1. Bulk Email System:
    • Rich HTML email composer with formatting toolbar
    • Live email preview before sending
    • Broadcast to all users with progress tracking
    • Individual delivery status for each recipient
  2. One-Click Communication Buttons:
    • 📧 Email: Launch email client with pre-filled recipient
    • 📞 Call: Open phone dialer with contact's number
    • 💬 SMS: Launch text messaging with contact's number
  3. Shift Communication:
    • Email shift details to all volunteers
    • Individual volunteer contact from shift management
    • Automated signup confirmations and reminders. (Insert screenshot - communication tools)

7. Walk Sheet Generator

Creating Walk Sheets

  1. Admin Panel → Walk Sheet Generator
  2. Configuration Options:
    • Title, subtitle, and footer text
    • Contact information and instructions
    • QR codes for digital resources
    • Logo and branding elements
  3. Location Selection: Choose specific areas or use cut boundaries.
  4. Print Options: Multiple layout formats for different campaign needs.
  5. QR Integration: Add QR codes linking to:
    • Digital surveys or forms
    • Contact information
    • Campaign websites or resources. (Insert screenshot - walk sheet generator)

Mobile-Optimized Walk Sheets

  1. Responsive Design: Optimized for viewing on phones and tablets.
  2. QR Code Scanner Integration: Quick scanning for volunteer check-ins.
  3. Offline Capability: Download for use without internet connection.

8. User Profile Management

Personal Settings

  1. User Menu → Profile to access personal settings.
  2. Account Information:
    • Update name, email, and phone number
    • Change password
    • Communication preferences
  3. Activity History: View your shift signups and location contributions.
  4. Privacy Settings: Control data sharing and communication preferences. (Insert screenshot - user profile)

Password Recovery

  1. Forgot Password link on login page.
  2. Email Reset: Automated password reset via SMTP (if configured).
  3. Admin Assistance: Contact administrators for manual password resets.

9. Admin Panel Features

Dashboard Overview

  1. System Statistics: User counts, recent activity, and system health.
  2. Quick Actions: Direct access to common administrative tasks.
  3. NocoDB Integration: Direct links to database management interface. (Insert screenshot - admin dashboard)

User Management

  1. Create Users: Add new accounts with role assignments:
    • Regular Users: Full access to mapping and shifts
    • Temporary Users: Limited access with automatic expiration
    • Admin Users: Full system administration privileges
  2. User Communication:
    • Send login details to new users
    • Bulk email all users with rich HTML composer
    • Individual user contact (email, call, text)
  3. User Types & Expiration:
    • Set expiration dates for temporary accounts
    • Visual indicators for user types and status
    • Automatic cleanup of expired accounts. (Insert screenshot - user management)

Shift Administration

  1. Create & Manage Shifts:
    • Set dates, times, locations, and volunteer limits
    • Public/private visibility settings
    • Detailed descriptions and requirements
  2. Volunteer Management:
    • Add users directly to shifts
    • Remove volunteers when needed
    • Email shift details to all participants
    • Generate public signup links
  3. Volunteer Communication:
    • Individual contact buttons (email, call, text) for each volunteer
    • Bulk shift detail emails with delivery tracking
    • Automated confirmation and reminder systems. (Insert screenshot - shift management)

System Configuration

  1. Map Settings:
    • Set default start location and zoom level
    • Configure map boundaries and restrictions
    • Customize marker styles and colors
  2. Integration Management:
    • NocoDB database connections
    • Listmonk email list synchronization
    • SMTP configuration for automated emails
  3. Security Settings:
    • User permissions and role management
    • API access controls
    • Session management. (Insert screenshot - system config)

10. Data Management & Integration

NocoDB Database Integration

  1. Direct Database Access: Admin links to NocoDB sheets for advanced data management.
  2. Automated Sync: Real-time synchronization between map interface and database.
  3. Backup & Migration: Built-in tools for data backup and system migration.
  4. Custom Fields: Add custom data fields through NocoDB interface.

Listmonk Email Marketing Integration

  1. Automatic List Sync: Map data automatically syncs to Listmonk email lists.
  2. Segmentation: Create targeted lists based on:
    • Geographic location (cuts/neighborhoods)
    • Support levels and volunteer interest
    • Contact preferences and activity
  3. One-Direction Sync: Maintains data integrity while allowing email unsubscribes.
  4. Compliance: Newsletter legislation compliance with opt-out capabilities. (Insert screenshot - integration settings)

Data Export & Reporting

  1. CSV Export: Download location data, user lists, and shift reports.
  2. Cut Reports: Professional reports with statistics and location breakdowns.
  3. Print-Ready Formats: Optimized layouts for physical distribution.
  4. Analytics Dashboard: Track user engagement and system usage.

11. Mobile & Accessibility Features

Mobile-Optimized Interface

  1. Responsive Design: Fully functional on phones and tablets.
  2. Touch Navigation: Optimized touch controls for map interaction.
  3. Mobile-Specific Features:
    • Cut management modal for overlay control
    • Simplified navigation and larger touch targets
    • Offline capability for basic functions

Accessibility

  1. Keyboard Navigation: Full keyboard support throughout the interface.
  2. Screen Reader Compatibility: ARIA labels and semantic markup.
  3. High Contrast Support: Compatible with accessibility themes.
  4. Text Scaling: Responsive to browser zoom and text size settings.

12. Security & Privacy

Data Protection

  1. Server-Side Security: All API tokens and credentials kept server-side only.
  2. Input Validation: Comprehensive validation and sanitization of all user inputs.
  3. CORS Protection: Cross-origin request security measures.
  4. Rate Limiting: Protection against abuse and automated attacks.

User Privacy

  1. Role-Based Access: Users only see data appropriate to their permission level.
  2. Temporary Account Expiration: Automatic cleanup of temporary user data.
  3. Audit Trails: Logging of administrative actions and data changes.
  4. Data Retention: Configurable retention policies for different data types. (Insert screenshot - security settings)

Authentication

  1. Secure Login: Password-based authentication with optional 2FA.
  2. Session Management: Automatic logout for expired sessions.
  3. Password Policies: Configurable password strength requirements.
  4. Account Lockout: Protection against brute force attacks.

13. Performance & System Requirements

System Performance

  1. Optimized Database Queries: Reduced API calls by over 5000% for better performance.
  2. Smart Caching: Intelligent caching of frequently accessed data.
  3. Progressive Loading: Map data loads incrementally for faster initial page loads.
  4. Background Sync: Automatic data synchronization without blocking user interface.

Browser Requirements

  1. Modern Browsers: Chrome, Firefox, Safari, Edge (recent versions).
  2. JavaScript Required: Full functionality requires JavaScript enabled.
  3. Local Storage: Uses browser storage for session management and caching.
  4. Geolocation: Optional location services for enhanced functionality.

14. Troubleshooting

Common Issues

  • Locations not showing: Check database connectivity, verify coordinates are valid, ensure API permissions allow read access.
  • Cannot add locations: Verify API write permissions, check coordinate bounds, ensure all required fields completed.
  • Login problems: Verify email/password, check account expiration (for temp users), contact admin for password reset.
  • Map not loading: Check internet connection, verify site URL, clear browser cache and cookies.
  • Permission denied: Confirm user role and permissions, check account expiration status, contact administrator.

Performance Issues

  • Slow loading: Check internet connection, try refreshing the page, contact admin if problems persist.
  • Database errors: Contact system administrator, check NocoDB service status.
  • Email not working: Verify SMTP configuration (admin), check spam/junk folders.

Mobile Issues

  • Touch problems: Ensure touch targets are accessible, try refreshing page, check for browser compatibility.
  • Display issues: Try rotating device, check browser zoom level, update to latest browser version.

15. Advanced Features

API Access

  1. RESTful API: Programmatic access to map data and functionality.
  2. Authentication: Token-based API authentication for external integrations.
  3. Rate Limiting: API usage limits to ensure system stability.
  4. Documentation: Complete API documentation for developers.

Customization Options

  1. Theming: Customizable color schemes and branding.
  2. Field Configuration: Add custom data fields through admin interface.
  3. Workflow Customization: Configurable user workflows and permissions.
  4. Integration Hooks: Webhook support for external system integration.

16. Getting Help & Support

Built-in Help

  1. Context Help: Tooltips and help text throughout the interface.
  2. Search Documentation: Use Ctrl+K to search help articles and guides.
  3. Status Messages: Clear feedback for all user actions and system status.

Administrator Support

  1. Contact Admin: Use the contact information provided during setup.
  2. System Logs: Administrators have access to detailed system logs for troubleshooting.
  3. Database Direct Access: Admins can access NocoDB directly for advanced data management.

Community Resources

  1. Documentation: Comprehensive online documentation and guides.
  2. GitHub Repository: Access to source code and issue tracking.
  3. Developer Community: Active community for advanced customization and development.

For technical support, contact your system administrator or refer to the comprehensive documentation available through the help system. (Insert screenshot - help resources)