После рефакторинга

dbapp/mainapp/static/js/SORTING_README.md

@@ -0,0 +1,148 @@
+# Sorting Functionality Documentation
+
+## Overview
+
+This document describes the centralized sorting functionality implemented for table columns across the Django application.
+
+## Files Created/Modified
+
+### Created Files:
+1. **`dbapp/mainapp/static/js/sorting.js`** - Main sorting JavaScript library
+2. **`dbapp/mainapp/static/js/sorting-test.html`** - Test page for manual verification
+
+### Modified Files:
+1. **`dbapp/mainapp/templates/mainapp/base.html`** - Added sorting.js script include
+2. **`dbapp/mainapp/templates/mainapp/components/_sort_header.html`** - Removed inline script, added data attributes
+
+## Features
+
+### 1. Sort Toggle Logic
+- **First click**: Sort ascending (field)
+- **Second click**: Sort descending (-field)
+- **Third click**: Sort ascending again (cycles back)
+
+### 2. URL Parameter Management
+- Preserves all existing GET parameters (search, filters, etc.)
+- Automatically resets page number to 1 when sorting changes
+- Updates the `sort` parameter in the URL
+
+### 3. Visual Indicators
+- Shows up arrow (↑) for ascending sort
+- Shows down arrow (↓) for descending sort
+- Automatically initializes indicators on page load
+- Adds `sort-active` class to currently sorted column
+
+## Usage
+
+### In Templates
+
+Use the `_sort_header.html` component in your table headers:
+
+```django
+<thead class="table-dark sticky-top">
+    <tr>
+        <th>{% include 'mainapp/components/_sort_header.html' with field='id' label='ID' current_sort=sort %}</th>
+        <th>{% include 'mainapp/components/_sort_header.html' with field='name' label='Название' current_sort=sort %}</th>
+        <th>{% include 'mainapp/components/_sort_header.html' with field='created_at' label='Дата создания' current_sort=sort %}</th>
+    </tr>
+</thead>
+```
+
+### In Views
+
+Pass the current sort parameter to the template context:
+
+```python
+def get(self, request):
+    sort = request.GET.get('sort', '-id')  # Default sort
+    
+    # Validate allowed sorts
+    allowed_sorts = ['id', '-id', 'name', '-name', 'created_at', '-created_at']
+    if sort not in allowed_sorts:
+        sort = '-id'
+    
+    # Apply sorting
+    queryset = Model.objects.all().order_by(sort)
+    
+    context = {
+        'sort': sort,
+        'objects': queryset,
+        # ... other context
+    }
+    return render(request, 'template.html', context)
+```
+
+## JavaScript API
+
+### Functions
+
+#### `updateSort(field)`
+Updates the sort parameter and reloads the page.
+
+**Parameters:**
+- `field` (string): The field name to sort by
+
+**Example:**
+```javascript
+updateSort('created_at');  // Sort by created_at ascending
+```
+
+#### `getCurrentSort()`
+Gets the current sort field and direction from URL.
+
+**Returns:**
+- Object with `field` and `direction` properties
+- `direction` can be 'asc', 'desc', or null
+
+**Example:**
+```javascript
+const sort = getCurrentSort();
+console.log(sort.field);      // 'created_at'
+console.log(sort.direction);  // 'asc' or 'desc'
+```
+
+#### `initializeSortIndicators()`
+Automatically called on page load to show current sort state.
+
+## Requirements Satisfied
+
+This implementation satisfies the following requirements from the specification:
+
+- **5.1**: Supports ascending and descending order for sortable columns
+- **5.2**: Toggles between ascending, descending when clicking column headers
+- **5.3**: Displays visual indicators (arrow icons) showing sort direction
+- **5.5**: Preserves sort state in URL parameters during navigation
+- **5.6**: Preserves other active filters and resets pagination when sorting
+
+## Testing
+
+### Manual Testing
+
+1. Open `dbapp/mainapp/static/js/sorting-test.html` in a browser
+2. Click column headers to test sorting
+3. Verify URL updates correctly
+4. Add query parameters (e.g., ?page=5&search=test) and verify they're preserved
+
+### Integration Testing
+
+Test in actual Django views:
+1. Navigate to any list view (sources, objitems, transponders)
+2. Click column headers to sort
+3. Verify data is sorted correctly
+4. Apply filters and verify they're preserved when sorting
+5. Navigate to page 2+, then sort - verify it resets to page 1
+
+## Browser Compatibility
+
+- Modern browsers supporting ES6 (URLSearchParams)
+- Chrome 49+
+- Firefox 44+
+- Safari 10.1+
+- Edge 17+
+
+## Notes
+
+- The sorting.js file is loaded with `defer` attribute for better performance
+- All GET parameters are preserved except `page` which is reset to 1
+- The function is globally available and can be called from any template
+- Sort indicators are automatically initialized on page load