quality_recticel/py_app/PRINT_PROGRESS_FEATURE.md

Print Progress Modal Feature

Overview

Added a visual progress modal that displays during label printing operations via QZ Tray. The modal shows real-time progress, updates the database upon completion, and refreshes the table view automatically.

Features Implemented

1. Progress Modal UI

• Modal Overlay: Full-screen semi-transparent overlay to focus user attention
• Progress Bar: Animated progress bar showing percentage completion
• Status Messages: Real-time status updates during printing
• Label Counter: Shows "X / Y" format for current progress (e.g., "5 / 10")

2. Print Flow Improvements

The printing process now follows these steps:

1. Validation: Check QZ Tray connection and printer selection
2. Modal Display: Show progress modal immediately
3. Sequential Printing: Print each label one by one with progress updates
   • Update progress bar after each successful print
   • Show current label number being printed
   • 500ms delay between labels for printer processing
4. Database Update: Call /update_printed_status/<order_id> endpoint
   • Marks the order as printed in the database
   • Handles errors gracefully (prints still succeed even if DB update fails)
5. Table Refresh: Automatically click "Load Orders" button to refresh the view
6. Modal Close: Hide modal after completion
7. Notification: Show success notification to user

3. Progress Updates

The modal displays different status messages:

• "Preparing to print..." (initial)
• "Printing label X of Y..." (during printing)
• "✅ All labels printed! Updating database..." (after prints complete)
• "✅ Complete! Refreshing table..." (after DB update)
• "⚠️ Labels printed but database update failed" (on DB error)

4. Error Handling

• Modal automatically closes on any error
• Error notifications shown to user
• Database update failures don't prevent successful printing
• Graceful degradation if DB update fails

Technical Details

CSS Styling

• Modal: Fixed position, z-index 9999, centered layout
• Content Card: White background, rounded corners, shadow
• Progress Bar: Linear gradient blue, smooth transitions
• Responsive: Min-width 400px, max-width 500px

JavaScript Functions Modified

handleQZTrayPrint(selectedRow)

Changes:

• Added modal element references
• Show modal before printing starts
• Update progress bar and counter in loop
• Call database update endpoint after printing
• Handle database update errors
• Refresh table automatically
• Close modal on completion or error

Backend Integration

Endpoint Used: /update_printed_status/<int:order_id>

• Method: POST
• Purpose: Mark order as printed in database
• Authentication: Requires superadmin, warehouse_manager, or etichete role
• Response: JSON with success/error message

User Experience Flow

1. User selects an order row in the table
2. User clicks "Print Label (QZ Tray)" button
3. Modal appears showing "Preparing to print..."
4. Progress bar fills as each label prints
5. Counter shows current progress (e.g., "7 / 10")
6. After all labels print: "✅ All labels printed! Updating database..."
7. Database updates with printed status
8. Modal shows "✅ Complete! Refreshing table..."
9. Modal closes automatically
10. Success notification appears
11. Table refreshes showing updated order status

Benefits

✅ Visual Feedback: Users see real-time progress instead of a frozen UI ✅ Status Clarity: Clear messages about what's happening ✅ Automatic Updates: Database and UI update without manual intervention ✅ Error Recovery: Graceful handling of database update failures ✅ Professional UX: Modern, polished user interface ✅ Non-Blocking: Progress modal doesn't interfere with printing operation

Files Modified

1. print_module.html
   • Added modal HTML structure
   • Added modal CSS styles
   • Updated handleQZTrayPrint() function
   • Added database update API call
   • Added automatic table refresh

Testing Checklist

• Modal appears when printing starts
• Progress bar animates smoothly
• Counter updates correctly (1/10, 2/10, etc.)
• All labels print successfully
• Database updates after printing
• Table refreshes automatically
• Modal closes after completion
• Success notification appears
• Error handling works (if DB update fails)
• Modal closes on printing errors

Future Enhancements

Potential improvements:

• Add "Cancel" button to stop printing mid-process
• Show estimated time remaining
• Add sound notification on completion
• Log printing history with timestamps
• Add printer status monitoring
• Show print queue if multiple orders selected