NTK CMS File Uploader

ntk-cms-fileuploader - Simple and efficient file upload component with progress tracking and validation

📋 Overview

The NTK CMS File Uploader is a lightweight and efficient file upload component designed for Angular applications. It provides drag & drop functionality, progress tracking, file validation, and customizable upload interface with minimal configuration.

🚀 Installation

``bash
npm install ntk-cms-fileuploader
`

📦 Features

$3

- Drag & Drop Upload - Intuitive file upload interface
- Progress Tracking - Real-time upload progress
- File Validation - Type and size validation
- Multiple File Support - Upload multiple files simultaneously
- Customizable UI - Flexible styling and theming
- Error Handling - Comprehensive error management
- Responsive Design - Mobile-friendly interface

$3

- Chunked Upload - Large file upload support
- Retry Mechanism - Automatic retry on failure
- Preview Support - File preview before upload
- Queue Management - Upload queue with priority
- Cancel Upload - Ability to cancel ongoing uploads

🔧 Usage

$3

`typescript
import { NgModule } from "@angular/core";
import { HttpClientModule } from "@angular/common/http";
import { NtkCmsFileuploaderModule } from "ntk-cms-fileuploader";

@NgModule({
imports: [HttpClientModule, NtkCmsFileuploaderModule],
})
export class AppModule {}
`

$3

`html

`

$3

`typescript
import { Component } from "@angular/core";

export class FileUploaderComponent {
uploadConfig = {
apiUrl: "https://api.example.com/upload",
maxFileSize: 10485760, // 10MB
allowedFileTypes: ["image/*", "application/pdf", "text/plain"],
multiple: true,
chunkSize: 1024 * 1024, // 1MB chunks
retryAttempts: 3,
autoUpload: true,
showProgress: true,
showPreview: true,
};

onUploadComplete(event: any): void {
console.log("Upload completed:", event);
// Handle successful upload
}

onUploadError(event: any): void {
console.error("Upload failed:", event);
// Handle upload error
}

onFileSelected(event: any): void {
console.log("File selected:", event);
// Handle file selection
}

onUploadProgress(event: any): void {
console.log("Upload progress:", event.progress);
// Handle progress updates
}
}
`

📚 API Reference

$3

| Property | Type | Default | Description |
| ------------------ | -------- | ------------ | ----------------------------- |
| apiUrl | string | - | Upload endpoint URL |
| maxFileSize | number | 5242880 | Maximum file size (5MB) |
| allowedFileTypes | string[] | [] | Allowed file types |
| multiple | boolean | false | Allow multiple file selection |
| chunkSize | number | 1024 \* 1024 | Chunk size for large files |
| retryAttempts | number | 3 | Number of retry attempts |
| autoUpload | boolean | true | Auto-upload on file selection |
| showProgress | boolean | true | Show progress bar |
| showPreview | boolean | false | Show file preview |
| disabled | boolean | false | Disable upload functionality |

$3

| Event | Type | Description |
| ---------------- | ------------ | ------------------------- |
| uploadComplete | EventEmitter | Upload completion event |
| uploadError | EventEmitter | Upload error event |
| fileSelected | EventEmitter | File selection event |
| uploadProgress | EventEmitter | Upload progress event |
| uploadCancel | EventEmitter | Upload cancellation event |

$3

#### FileUploaderService

`typescript
// Upload single file
uploadFile(file: File): Observable

// Upload multiple files
uploadFiles(files: File[]): Observable

// Cancel upload
cancelUpload(uploadId: string): void

// Get upload progress
getUploadProgress(uploadId: string): Observable

// Validate file
validateFile(file: File): boolean
`

🎨 Customization

$3

`scss
// Custom uploader styles
.ntk-cms-fileuploader {
.upload-zone {
border: 2px dashed #ccc;
border-radius: 8px;
padding: 40px;
text-align: center;
transition: all 0.3s ease;

&:hover {
border-color: #2196f3;
background-color: #f5f5f5;
}

&.drag-over {
border-color: #2196f3;
background-color: #e3f2fd;
transform: scale(1.02);
}
}

.file-item {
display: flex;
align-items: center;
padding: 10px;
margin: 5px 0;
border: 1px solid #ddd;
border-radius: 4px;
background-color: #fafafa;

.file-info {
flex: 1;
margin-left: 10px;
}

.file-name {
font-weight: 500;
color: #333;
}

.file-size {
font-size: 12px;
color: #666;
}

.progress-bar {
height: 4px;
background-color: #e0e0e0;
border-radius: 2px;
overflow: hidden;
margin-top: 5px;

.progress-fill {
height: 100%;
background-color: #2196f3;
transition: width 0.3s ease;
}
}

.upload-status {
margin-left: 10px;

&.success {
color: #4caf50;
}

&.error {
color: #f44336;
}

&.uploading {
color: #2196f3;
}
}
}
}
`

$3

`html

Drop files here or click to upload

Maximum file size: {{ maxFileSize | fileSize }}

Allowed types: {{ allowedFileTypes.join(', ') }}

{{ file.name }}

{{ file.size | fileSize }}

{{ progress }}%

`

🔐 Security

$3

`typescript
export class FileUploaderComponent {
validateFile(file: File): boolean {
// Check file size
if (file.size > this.maxFileSize) {
this.showError(File size exceeds ${this.formatFileSize(this.maxFileSize)});
return false;
}

// Check file type
const allowedTypes = this.allowedFileTypes;
if (allowedTypes.length > 0) {
const isValidType = allowedTypes.some((type) => {
if (type.endsWith("/*")) {
return file.type.startsWith(type.replace("/*", ""));
}
return file.type === type;
});

if (!isValidType) {
this.showError(File type ${file.type} is not allowed);
return false;
}
}

// Check file name
if (!this.isValidFileName(file.name)) {
this.showError("Invalid file name");
return false;
}

return true;
}

private isValidFileName(fileName: string): boolean {
// Check for invalid characters
const invalidChars = /[<>:"/\\|?*]/;
return !invalidChars.test(fileName);
}

private formatFileSize(bytes: number): string {
if (bytes === 0) return "0 Bytes";
const k = 1024;
const sizes = ["Bytes", "KB", "MB", "GB"];
const i = Math.floor(Math.log(bytes) / Math.log(k));
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
}

private showError(message: string): void {
// Show error message to user
console.error(message);
}
}
`

🧪 Testing

$3

`typescript
import { ComponentFixture, TestBed } from "@angular/core/testing";
import { HttpClientTestingModule } from "@angular/common/http/testing";
import { NtkCmsFileuploaderModule } from "ntk-cms-fileuploader";

describe("FileUploaderComponent", () => {
let component: FileUploaderComponent;
let fixture: ComponentFixture;

beforeEach(async () => {
await TestBed.configureTestingModule({
imports: [HttpClientTestingModule, NtkCmsFileuploaderModule],
declarations: [FileUploaderComponent],
}).compileComponents();

fixture = TestBed.createComponent(FileUploaderComponent);
component = fixture.componentInstance;
fixture.detectChanges();
});

it("should create", () => {
expect(component).toBeTruthy();
});

it("should validate file size correctly", () => {
const mockFile = new File(["test"], "test.txt", { type: "text/plain" });
Object.defineProperty(mockFile, "size", { value: 1024 * 1024 }); // 1MB

component.maxFileSize = 5242880; // 5MB
expect(component.validateFile(mockFile)).toBe(true);

component.maxFileSize = 512 * 1024; // 512KB
expect(component.validateFile(mockFile)).toBe(false);
});

it("should validate file type correctly", () => {
const mockFile = new File(["test"], "test.txt", { type: "text/plain" });

component.allowedFileTypes = ["text/plain", "application/pdf"];
expect(component.validateFile(mockFile)).toBe(true);

component.allowedFileTypes = ["image/*"];
expect(component.validateFile(mockFile)).toBe(false);
});

it("should handle upload completion", () => {
const mockEvent = { file: "test.txt", response: { success: true } };
spyOn(component.uploadComplete, "emit");

component.onUploadComplete(mockEvent);

expect(component.uploadComplete.emit).toHaveBeenCalledWith(mockEvent);
});
});
`

📊 Performance

$3

1. Chunked Upload: Use chunked upload for large files
2. Compression: Compress files before upload when possible
3. Queue Management: Implement upload queue for better control
4. Caching: Cache upload progress and file metadata
5. Lazy Loading: Load uploader component on demand

$3

`typescript
export class FileUploaderComponent implements OnDestroy {
private destroy$ = new Subject();
private uploadSubscriptions: Subscription[] = [];

ngOnInit(): void {
// Subscribe to upload events
this.uploadService.uploadProgress$.pipe(takeUntil(this.destroy$)).subscribe((progress) => {
this.updateProgress(progress);
});
}

uploadFile(file: File): void {
const uploadSub = this.uploadService
.uploadFile(file)
.pipe(takeUntil(this.destroy$))
.subscribe(
(result) => this.onUploadComplete(result),
(error) => this.onUploadError(error)
);

this.uploadSubscriptions.push(uploadSub);
}

ngOnDestroy(): void {
this.destroy$.next();
this.destroy$.complete();

// Cancel all ongoing uploads
this.uploadSubscriptions.forEach((sub) => sub.unsubscribe());
}
}
``

🔄 Version History

$3

- Initial release with core functionality
- Drag & drop support
- Progress tracking
- File validation
- Basic error handling

$3

- Bug fixes and performance improvements
- Enhanced error handling
- Improved UI/UX

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Submit a pull request

📄 License

This library is licensed under the ISC License.

🆘 Support

For support and questions:

- Create an issue on GitHub
- Contact: ntk.ir
- Documentation: Check the main README.md

---

Note: This library is part of the NTK CMS Angular Libraries collection. For more information, see the main project README.