documentation for all JS files

static/js/file-grid.js

@@ -1,3 +1,14 @@
+/**
+ * @fileoverview Manages the file grid view functionality.
+ * This file handles:
+ * - File grid and list view rendering
+ * - File sorting and filtering
+ * - File operations (star, restore, delete)
+ * - View preferences
+ * - Search functionality
+ * - File details display
+ */
+
 let currentView = 'grid';
 let lastSelectedIndex = -1;
 let sortColumn = 'name';  // Set default sort column to name
@@ -10,7 +21,12 @@ window.isAdmin = document.body.dataset.isAdmin === 'true';
 // Check if we're on the trash page
 const isTrashPage = window.location.pathname.includes('/trash');
 
-// Initialize the view and fetch files
+/**
+ * Initializes the file view and fetches files.
+ * Sets up the preferred view and initial file sorting.
+ * @async
+ * @function
+ */
 async function initializeView() {
     try {
         const response = await fetch('/api/user/preferred_view');
@@ -31,6 +47,12 @@ async function initializeView() {
     sortFiles('name');
 }
 
+/**
+ * Toggles between grid and list views.
+ * Updates the UI and saves the user's view preference.
+ * @function
+ * @param {string} view - The view to switch to ('grid' or 'list')
+ */
 function toggleView(view) {
     currentView = view;
     const grid = document.getElementById('fileGrid');
@@ -77,6 +99,12 @@ function toggleView(view) {
     });
 }
 
+/**
+ * Sorts files by the specified column.
+ * Handles different data types (string, number, date) appropriately.
+ * @function
+ * @param {string} column - The column to sort by ('name', 'modified', 'type', 'size', 'auto_delete')
+ */
 function sortFiles(column) {
     if (sortColumn === column) {
         sortDirection *= -1; // Toggle direction
@@ -102,6 +130,12 @@ function sortFiles(column) {
     renderFiles(currentFiles);
 }
 
+/**
+ * Gets the appropriate icon class for a file based on its extension.
+ * @function
+ * @param {string} filename - The name of the file
+ * @returns {string} The Font Awesome icon class for the file type
+ */
 function getFileIcon(filename) {
     const extension = filename.split('.').pop().toLowerCase();
     
@@ -127,6 +161,12 @@ function getFileIcon(filename) {
     return iconMap[extension] || 'fa-file';
 }
 
+/**
+ * Renders the files in either grid or list view.
+ * Handles both trash and normal file views with appropriate actions.
+ * @function
+ * @param {Array} files - Array of file objects to render
+ */
 function renderFiles(files) {
     if (!files) return;
     currentFiles = files;
@@ -223,6 +263,12 @@ function renderFiles(files) {
     }
 }
 
+/**
+ * Fetches files from the server.
+ * Handles both trash and starred file endpoints.
+ * @async
+ * @function
+ */
 async function fetchFiles() {
     try {
         const endpoint = isTrashPage ? '/api/rooms/trash' : '/api/rooms/starred';
@@ -244,6 +290,11 @@ async function fetchFiles() {
     }
 }
 
+/**
+ * Gets the CSRF token from various possible locations in the DOM.
+ * @function
+ * @returns {string} The CSRF token or empty string if not found
+ */
 function getCsrfToken() {
     // First try to get it from the meta tag
     const metaTag = document.querySelector('meta[name="csrf-token"]');
@@ -275,6 +326,13 @@ function getCsrfToken() {
     return '';
 }
 
+/**
+ * Toggles the star status of a file.
+ * @function
+ * @param {string} filename - The name of the file
+ * @param {string} path - The path of the file
+ * @param {number} roomId - The ID of the room containing the file
+ */
 function toggleStar(filename, path = '', roomId) {
     const csrfToken = getCsrfToken();
     if (!csrfToken) {
@@ -308,6 +366,13 @@ function toggleStar(filename, path = '', roomId) {
     });
 }
 
+/**
+ * Restores a file from the trash.
+ * @function
+ * @param {string} filename - The name of the file
+ * @param {string} path - The path of the file
+ * @param {number} roomId - The ID of the room containing the file
+ */
 function restoreFile(filename, path = '', roomId) {
     const csrfToken = getCsrfToken();
     if (!csrfToken) {
@@ -341,6 +406,13 @@ function restoreFile(filename, path = '', roomId) {
     });
 }
 
+/**
+ * Shows the permanent delete confirmation modal.
+ * @function
+ * @param {string} filename - The name of the file
+ * @param {string} path - The path of the file
+ * @param {number} roomId - The ID of the room containing the file
+ */
 function showPermanentDeleteModal(filename, path = '', roomId) {
     fileToDelete = { filename, path, roomId };
     document.getElementById('permanentDeleteItemName').textContent = filename;
@@ -348,6 +420,10 @@ function showPermanentDeleteModal(filename, path = '', roomId) {
     modal.show();
 }
 
+/**
+ * Permanently deletes a file after confirmation.
+ * @function
+ */
 function permanentDeleteFile() {
     if (!fileToDelete) return;
     
@@ -405,6 +481,14 @@ function permanentDeleteFile() {
     });
 }
 
+/**
+ * Navigates to a file or folder.
+ * @function
+ * @param {number} roomId - The ID of the room
+ * @param {string} filename - The name of the file/folder
+ * @param {string} path - The path of the file/folder
+ * @param {string} type - The type of item ('file' or 'folder')
+ */
 function navigateToFile(roomId, filename, path, type) {
     if (type === 'folder') {
         window.location.href = `/room/${roomId}?path=${encodeURIComponent(path ? path + '/' + filename : filename)}`;
@@ -413,11 +497,19 @@ function navigateToFile(roomId, filename, path, type) {
     }
 }
 
+/**
+ * Shows the empty trash confirmation modal.
+ * @function
+ */
 function showEmptyTrashModal() {
     const modal = new bootstrap.Modal(document.getElementById('emptyTrashModal'));
     modal.show();
 }
 
+/**
+ * Empties the trash by permanently deleting all trashed files.
+ * @function
+ */
 function emptyTrash() {
     const csrfToken = getCsrfToken();
     if (!csrfToken) {
@@ -465,6 +557,11 @@ function emptyTrash() {
     });
 }
 
+/**
+ * Shows the file details modal.
+ * @function
+ * @param {number} idx - The index of the file in the currentFiles array
+ */
 function showDetailsModal(idx) {
     const item = currentFiles[idx];
     const icon = item.type === 'folder'
@@ -498,6 +595,12 @@ function showDetailsModal(idx) {
     modal.show();
 }
 
+/**
+ * Formats a date string to a localized format.
+ * @function
+ * @param {string} dateString - The date string to format
+ * @returns {string} The formatted date string
+ */
 function formatDate(dateString) {
     const date = new Date(dateString);
     return date.toLocaleString();