0
# Django Admin Integration
1

2
Complete Django admin integration with import/export functionality, including file upload, validation, confirmation workflows, and error handling.
3

4
## Capabilities
5

6
### Import Mixin
7

8
Adds import functionality to Django ModelAdmin with comprehensive workflow support.
9

10
```python { .api }
11
class ImportMixin(BaseImportMixin, ImportExportMixinBase):
12
    import_template_name = 'admin/import_export/import.html'
13
    import_form_class = ImportForm
14
    confirm_form_class = ConfirmImportForm
15
    from_encoding = 'utf-8'
16
    import_error_display = 'first'  # 'first' or 'all'
17
    skip_admin_log = None
18
    tmp_storage_class = TempFolderStorage
19

20
    def import_action(self, request, **kwargs):
21
        """
22
        Handle import action in Django admin.
23
        
24
        Parameters:
25
        - request: Django HttpRequest
26
        - **kwargs: Additional action parameters
27
        
28
        Returns:
29
        HttpResponse with import form or confirmation
30
        """
31

32
    def process_import(self, request, **kwargs):
33
        """
34
        Process import request with file upload and validation.
35
        
36
        Parameters:
37
        - request: Django HttpRequest
38
        - **kwargs: Import processing options
39
        
40
        Returns:
41
        HttpResponse with results or error page
42
        """
43

44
    def has_import_permission(self, request):
45
        """
46
        Check if user has import permission.
47
        
48
        Parameters:
49
        - request: Django HttpRequest
50
        
51
        Returns:
52
        bool, True if user can import
53
        """
54

55
    def get_import_formats(self):
56
        """
57
        Get list of available import formats.
58
        
59
        Returns:
60
        List of format classes available for import
61
        """
62

63
    def get_import_context_data(self, **kwargs):
64
        """
65
        Get context data for import template.
66
        
67
        Parameters:
68
        - **kwargs: Additional context data
69
        
70
        Returns:
71
        dict, context data for template rendering
72
        """
73

74
    def get_import_form_class(self, request):
75
        """
76
        Get form class for import step.
77
        
78
        Parameters:
79
        - request: Django HttpRequest
80
        
81
        Returns:
82
        Form class for import file selection
83
        """
84

85
    def get_import_form_kwargs(self, request):
86
        """
87
        Get kwargs for import form instantiation.
88
        
89
        Parameters:
90
        - request: Django HttpRequest
91
        
92
        Returns:
93
        dict, keyword arguments for form creation
94
        """
95

96
    def create_import_form(self):
97
        """
98
        Create import form instance.
99
        
100
        Returns:
101
        ImportForm instance
102
        """
103

104
    def create_confirm_form(self):
105
        """
106
        Create import confirmation form instance.
107
        
108
        Returns:
109
        ConfirmImportForm instance
110
        """
111

112
    def get_import_resource_kwargs(self, request, *args, **kwargs):
113
        """
114
        Get kwargs for resource initialization during import.
115
        
116
        Parameters:
117
        - request: Django HttpRequest
118
        - *args: Additional arguments
119
        - **kwargs: Additional keyword arguments
120
        
121
        Returns:
122
        Dict of resource kwargs
123
        """
124

125
    def get_import_data_kwargs(self, request, *args, **kwargs):
126
        """
127
        Get kwargs for import_data method.
128
        
129
        Parameters:
130
        - request: Django HttpRequest
131
        - *args: Additional arguments
132
        - **kwargs: Additional keyword arguments
133
        
134
        Returns:
135
        Dict of import_data kwargs
136
        """
137

138
    def get_confirm_import_form(self, request):
139
        """
140
        Get confirmation form for import.
141
        
142
        Parameters:
143
        - request: Django HttpRequest
144
        
145
        Returns:
146
        ConfirmImportForm instance
147
        """
148

149
    def get_import_formats(self):
150
        """
151
        Get available import formats.
152
        
153
        Returns:
154
        List of format classes available for import
155
        """
156

157
    def get_resource_classes(self):
158
        """
159
        Get resource classes for this admin.
160
        
161
        Returns:
162
        List of resource classes
163
        """
164

165
    def choose_import_resource_class(self, form):
166
        """
167
        Choose resource class based on form data.
168
        
169
        Parameters:
170
        - form: Import form instance
171
        
172
        Returns:
173
        Resource class to use for import
174
        """
175

176
    def write_to_tmp_storage(self, import_file, input_format):
177
        """
178
        Write uploaded file to temporary storage.
179
        
180
        Parameters:
181
        - import_file: Uploaded file
182
        - input_format: Format class
183
        
184
        Returns:
185
        Storage instance with written file
186
        """
187
```
188

189
### Export Mixin
190

191
Adds export functionality to Django ModelAdmin with format selection and queryset filtering.
192

193
```python { .api }
194
class ExportMixin(BaseExportMixin, ImportExportMixinBase):
195
    export_template_name = 'admin/import_export/export.html'
196
    export_form_class = ExportForm
197
    to_encoding = 'utf-8'
198

199
    def export_action(self, request):
200
        """
201
        Handle export action in Django admin.
202
        
203
        Parameters:
204
        - request: Django HttpRequest
205
        
206
        Returns:
207
        HttpResponse with export form or file download
208
        """
209

210
    def get_export_data(self, file_format, request, queryset, **kwargs):
211
        """
212
        Get export data in specified format.
213
        
214
        Parameters:
215
        - file_format: Format class for export
216
        - request: Django HttpRequest
217
        - queryset: QuerySet to export
218
        - **kwargs: Export options
219
        
220
        Returns:
221
        Formatted export data
222
        """
223

224
    def get_export_queryset(self, request):
225
        """
226
        Get queryset for export operations.
227
        
228
        Parameters:
229
        - request: Django HttpRequest
230
        
231
        Returns:
232
        QuerySet to export
233
        """
234

235
    def has_export_permission(self, request):
236
        """
237
        Check if user has export permission.
238
        
239
        Parameters:
240
        - request: Django HttpRequest
241
        
242
        Returns:
243
        bool, True if user can export
244
        """
245

246
    def get_export_resource_kwargs(self, request, *args, **kwargs):
247
        """
248
        Get kwargs for resource initialization during export.
249
        
250
        Parameters:
251
        - request: Django HttpRequest
252
        - *args: Additional arguments
253
        - **kwargs: Additional keyword arguments
254
        
255
        Returns:
256
        Dict of resource kwargs
257
        """
258

259
    def get_export_formats(self):
260
        """
261
        Get available export formats.
262
        
263
        Returns:
264
        List of format classes available for export
265
        """
266

267
    def get_export_filename(self, request, queryset, file_format):
268
        """
269
        Generate filename for export.
270
        
271
        Parameters:
272
        - request: Django HttpRequest
273
        - queryset: QuerySet being exported
274
        - file_format: Format class
275
        
276
        Returns:
277
        str, filename for export file
278
        """
279

280
    def create_export_form(self):
281
        """
282
        Create export form instance.
283
        
284
        Returns:
285
        ExportForm instance
286
        """
287
```
288

289
### Combined Import/Export Mixin
290

291
Combines both import and export functionality in a single mixin.
292

293
```python { .api }
294
class ImportExportMixin(ImportMixin, ExportMixin):
295
    """
296
    Mixin that combines both import and export functionality.
297
    Inherits all methods from ImportMixin and ExportMixin.
298
    """
299
```
300

301
### Export Action Mixin
302

303
Adds export functionality as Django admin actions.
304

305
```python { .api }
306
class ExportActionMixin(ExportMixin):
307
    def get_actions(self, request):
308
        """
309
        Get admin actions including export actions.
310
        
311
        Parameters:
312
        - request: Django HttpRequest
313
        
314
        Returns:
315
        Dict of available actions
316
        """
317

318
    def export_admin_action(self, request, queryset):
319
        """
320
        Export selected items as admin action.
321
        
322
        Parameters:
323
        - request: Django HttpRequest
324
        - queryset: Selected items QuerySet
325
        
326
        Returns:
327
        HttpResponse with export or redirect
328
        """
329
```
330

331
### Complete Admin Classes
332

333
Ready-to-use admin classes that combine ModelAdmin with import/export functionality.
334

335
```python { .api }
336
class ImportExportModelAdmin(ImportExportMixin, admin.ModelAdmin):
337
    """
338
    ModelAdmin with full import/export functionality.
339
    Combines Django's ModelAdmin with ImportExportMixin.
340
    """
341

342
class ExportActionModelAdmin(ExportActionMixin, admin.ModelAdmin):
343
    """
344
    ModelAdmin with export functionality as admin actions.
345
    Combines Django's ModelAdmin with ExportActionMixin.
346
    """
347

348
class ImportExportActionModelAdmin(ImportMixin, ExportActionModelAdmin):
349
    """
350
    ModelAdmin with import functionality and export as admin actions.
351
    Combines ImportMixin with ExportActionModelAdmin.
352
    """
353
```
354

355
### Base Mixins
356

357
Lower-level mixins that provide core functionality without admin-specific features.
358

359
```python { .api }
360
class BaseImportExportMixin:
361
    resource_classes = None
362
    resource_class = None
363

364
    def get_resource_classes(self):
365
        """Get resource classes for this mixin."""
366

367
    def get_resource_class(self):
368
        """Get primary resource class."""
369

370
    def get_import_resource_classes(self):
371
        """Get resource classes available for import."""
372

373
    def get_export_resource_classes(self):
374
        """Get resource classes available for export."""
375

376
class BaseImportMixin(BaseImportExportMixin):
377
    """Base import functionality without Django admin dependencies."""
378

379
class BaseExportMixin(BaseImportExportMixin):
380
    """Base export functionality without Django admin dependencies."""
381
```
382

383
### View Mixins
384

385
Mixins for use with Django class-based views.
386

387
```python { .api }
388
class ExportViewMixin(BaseExportMixin):
389
    """Export functionality for class-based views."""
390
    
391
    def get_export_response(self, export_data, file_format, filename):
392
        """
393
        Create HttpResponse for export download.
394
        
395
        Parameters:
396
        - export_data: Exported data
397
        - file_format: Format class
398
        - filename: Export filename
399
        
400
        Returns:
401
        HttpResponse with file download
402
        """
403

404
class ExportViewFormMixin(ExportViewMixin, FormView):
405
    """Export functionality with form handling for class-based views."""
406
    
407
    form_class = ExportForm
408
    template_name = 'import_export/export.html'
409
```
410

411
## Usage Examples
412

413
### Basic Admin Integration
414

415
```python
416
from django.contrib import admin
417
from import_export.admin import ImportExportModelAdmin
418
from myapp.models import Book
419
from myapp.resources import BookResource
420

421
@admin.register(Book)
422
class BookAdmin(ImportExportModelAdmin):
423
    resource_class = BookResource
424
    list_display = ['title', 'author', 'published_date']
425
    list_filter = ['published_date', 'author']
426
    search_fields = ['title', 'author']
427
```
428

429
### Custom Permissions
430

431
```python
432
class BookAdmin(ImportExportModelAdmin):
433
    resource_class = BookResource
434

435
    def has_import_permission(self, request):
436
        # Only allow import for staff users
437
        return request.user.is_staff and request.user.has_perm('myapp.add_book')
438

439
    def has_export_permission(self, request):
440
        # Allow export for all authenticated users
441
        return request.user.is_authenticated
442
```
443

444
### Multiple Resource Classes
445

446
```python
447
from myapp.resources import BookResource, BookAdvancedResource
448

449
class BookAdmin(ImportExportModelAdmin):
450
    resource_classes = [BookResource, BookAdvancedResource]
451
    
452
    def get_resource_classes(self):
453
        # Choose resource based on user permissions
454
        if self.request.user.is_superuser:
455
            return [BookAdvancedResource, BookResource]
456
        return [BookResource]
457
```
458

459
### Custom Template and Forms
460

461
```python
462
from myapp.forms import CustomImportForm, CustomExportForm
463

464
class BookAdmin(ImportExportModelAdmin):
465
    resource_class = BookResource
466
    import_template_name = 'admin/myapp/custom_import.html'
467
    export_template_name = 'admin/myapp/custom_export.html'
468
    import_form_class = CustomImportForm
469
    export_form_class = CustomExportForm
470
```
471

472
### Custom Resource Kwargs
473

474
```python
475
class BookAdmin(ImportExportModelAdmin):
476
    resource_class = BookResource
477

478
    def get_import_resource_kwargs(self, request, *args, **kwargs):
479
        kwargs = super().get_import_resource_kwargs(request, *args, **kwargs)
480
        # Pass current user to resource
481
        kwargs['user'] = request.user
482
        return kwargs
483

484
    def get_export_resource_kwargs(self, request, *args, **kwargs):
485
        kwargs = super().get_export_resource_kwargs(request, *args, **kwargs)
486
        # Pass user preferences to resource
487
        kwargs['user_preferences'] = request.user.preferences
488
        return kwargs
489
```
490

491
### Export as Admin Action Only
492

493
```python
494
@admin.register(Book)
495
class BookAdmin(ExportActionModelAdmin):
496
    resource_class = BookResource
497
    list_display = ['title', 'author', 'published_date']
498
    
499
    def export_admin_action(self, request, queryset):
500
        # Custom export action behavior
501
        response = super().export_admin_action(request, queryset)
502
        # Log export action
503
        self.log_export_action(request, queryset)
504
        return response
505

506
    export_admin_action.short_description = "Export selected books"
507
```
508

509
### Import with Custom Processing
510

511
```python
512
class BookAdmin(ImportExportModelAdmin):
513
    resource_class = BookResource
514

515
    def get_import_data_kwargs(self, request, *args, **kwargs):
516
        kwargs = super().get_import_data_kwargs(request, *args, **kwargs)
517
        # Always use transactions for imports
518
        kwargs['use_transactions'] = True
519
        # Collect failed rows for analysis
520
        kwargs['collect_failed_rows'] = True
521
        return kwargs
522

523
    def process_import(self, request, **kwargs):
524
        response = super().process_import(request, **kwargs)
525
        # Send notification after import
526
        if hasattr(self, 'import_result') and not self.import_result.has_errors():
527
            send_import_notification(request.user, self.import_result)
528
        return response
529
```
530

531
### Custom Storage for Large Files
532

533
```python
534
from import_export.tmp_storages import CacheStorage
535

536
class BookAdmin(ImportExportModelAdmin):
537
    resource_class = BookResource
538
    tmp_storage_class = CacheStorage  # Use cache for large files
539

540
    def write_to_tmp_storage(self, import_file, input_format):
541
        # Custom file processing before storage
542
        if import_file.size > 10 * 1024 * 1024:  # 10MB
543
            # Process large files differently
544
            return self.process_large_file(import_file, input_format)
545
        return super().write_to_tmp_storage(import_file, input_format)
546
```
547

548
### Integration with Class-Based Views
549

550
```python
551
from django.views.generic import FormView
552
from import_export.mixins import ExportViewFormMixin
553

554
class BookExportView(ExportViewFormMixin):
555
    model = Book
556
    resource_class = BookResource
557
    template_name = 'books/export.html'
558
    
559
    def get_export_queryset(self):
560
        # Custom queryset filtering
561
        return Book.objects.filter(published_date__year=2023)
562

563
    def form_valid(self, form):
564
        file_format = form.cleaned_data['file_format']
565
        queryset = self.get_export_queryset()
566
        resource = self.resource_class()
567
        dataset = resource.export(queryset)
568
        response = self.get_export_response(
569
            dataset, file_format, 'books_2023.csv'
570
        )
571
        return response
572
```