File Upload UI Components
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The IT Management System utilizes a set of shared UI components and utility scripts to manage file uploads across various modules, including Equipment, Floor Plans, and the File Explorer. These components provide a modern interactive experience within a legacy PHP architecture, supporting features such as drag-and-drop, asynchronous processing, and multi-tenant isolation.
The primary goal of these components is to facilitate the management of IT infrastructure assets through visual and document-based data, such as equipment photos, building layouts (images, PDFs, CAD files), and general file storage.
Sources: js/AGENT_NOTES.md:4, README.md:12-19, modules/explorer/AGENT_NOTES.md:4
System Architecture and Integration
The file upload system is built on vanilla JavaScript with zero external NPM dependencies. It integrates with the PHP backend via asynchronous POST requests, utilizing CSRF tokens for security and session-based company_id for multi-tenant data isolation.
Component Interaction Flow
The following diagram illustrates the interaction between the frontend upload utilities and the backend storage modules.
Key Modules and File Handling
Different modules implement specific logic for file handling based on their purpose:
| Module | Purpose | File Types Supported | Storage Location |
|---|---|---|---|
| Explorer | Web-based file management | General files | files/{company_id}/ |
| Floor Plans | Building layouts and drawings | Image, PDF, AutoCAD (DWG, DXF) | floor_plans/{company_id}/ |
| Equipment | Asset tracking | Photos (JPEG, PNG, etc.) | images/ |
| Tickets | Support system | Attachments/Photos | tickets_photos/ |
| Settings | System configuration | Favicons, SQL Backups | backups/ |
Sources: README.md:144-150, modules/explorer/AGENT_NOTES.md:16, modules/floor_plans/AGENT_NOTES.md:15
Functional Components
1. itm-upload-helper.js
This shared utility serves as the frontend backbone for drag-and-drop file uploads. It abstracts the complexities of handling file events and preparing multi-part form data for the backend. It is designed to be loaded before any blocks that depend on it to avoid common pitfalls.
Sources: js/AGENT_NOTES.md:15, 20
2. Explorer File Management
The Explorer module provides a structured environment for file operations including upload, download, and renaming. It enforces strict path safety to prevent traversal attacks and ensures that files are stored within company-isolated directories.
Sources: modules/explorer/AGENT_NOTES.md:4, 16, 28
3. Floor Plans Gallery
This module handles specialized document types and implements a hierarchical folder structure. It supports a 20MB file size limit and provides a gallery view for image thumbnails.
Technical Requirements and Constraints
- Multi-Tenancy: All file operations must be scoped by the active
company_id. Physical paths are constructed asfiles/{company_id}/orfloor_plans/{company_id}/. - Security: All async POST requests for file operations MUST include the
window.ITM_CSRF_TOKEN. - Validation: Backend handlers must validate Mime Types on upload to prevent the execution of malicious scripts and enforce path sanitization.
- Server Configuration: Server settings such as
post_max_sizeandupload_max_filesizemust be configured to support larger files, particularly for the Floor Plans module (20MB limit).
Sources: js/AGENT_NOTES.md:12, modules/explorer/AGENT_NOTES.md:17, 34, modules/floor_plans/AGENT_NOTES.md:36, README.md:197-200
API Endpoints for File Operations
The system utilizes specific internal AJAX endpoints for managing file uploads and metadata.
| Endpoint | Method | Purpose |
|---|---|---|
modules/explorer/api.php | POST | Explorer actions (create, rename, upload, delete, move) |
modules/floor_plans/index.php | POST | Handles bulk JSON import via import_excel_rows |
scripts/api.php | N/A | Centralized documentation for all JSON/Import endpoints |
Sources: scripts/api.php:123, 203, modules/floor_plans/AGENT_NOTES.md:28
Conclusion
The File Upload UI Components provide a robust and secure method for managing physical documents and media within the IT Management System. By centralizing logic in itm-upload-helper.js and enforcing strict multi-tenant directory structures, the system maintains high data integrity and security while offering a user-friendly drag-and-drop interface.