Image Upload Widget

The Image Upload widget allows users to upload one or multiple files to your application with advanced configuration options for file validation, storage, and user experience.

Overview​

The Image Upload widget provides a robust file upload interface with support for:

• Multiple file uploads
• File type validation
• File size limitations
• Drag and drop functionality
• Cloud storage integration (AWS S3)
• Custom styling and validation

Basic Configuration​

Global Settings​

Name​

• Field: Name
• Description: Display name for the widget
• Type: Text input
• Required: Yes

Variable/Model​

• Field: Variable/Model
• Description: The data model property that will store the uploaded files array
• Type: Text input
• Required: Yes
• Example: uploadedFiles

Upload Configuration​

File Limit​

• Field: Limit
• Description: Maximum number of files that can be uploaded
• Type: Number input
• Default: No limit
• Example: 5 (allows up to 5 files)

File Types​

• Field: File types
• Description: Acceptable file MIME types
• Type: Text input
• Format: Comma-separated MIME types
• Examples:
  • image/* (all image types)
  • image/jpeg,image/png,image/gif (specific image types)
  • application/pdf (PDF files only)
  • image/*,application/pdf (images and PDFs)
• Reference: MDN MIME Types

File Size​

• Field: File size
• Description: Maximum file size allowed per file
• Type: Number input
• Unit: Bytes
• Example: 26214400 (25MB in bytes)
• Note: Server limit is 25MB by default

Upload Interface​

Drag and Drop​

• Field: Drag'n Drop
• Description: Enable drag and drop file upload interface
• Type: Toggle switch
• Default: Disabled
• When Enabled: Shows a drop zone with upload icon
• When Disabled: Shows a button for file selection

Button Text​

• Field: Button
• Description: Text displayed on the upload button
• Type: Text input
• Default: "Choose Files"
• Example: "Upload Images"

Tip Text​

• Field: Tip
• Description: Helper text displayed below the upload area
• Type: Text input
• Example: "Supported formats: JPG, PNG, PDF. Max size: 25MB"

Storage Configuration​

AWS S3 Storage​

• Field: Store in S3
• Description: Store uploaded files in AWS S3 bucket instead of local storage
• Type: Toggle switch
• Default: Disabled
• Requirements: S3 bucket must be configured in your account
• Note: This will be the default option in future releases

Public File Access​

• Field: Public file
• Description: Make uploaded files publicly accessible
• Type: Toggle switch
• Default: Disabled
• Effect: Files can be accessed without authentication

Validation and Rules​

Built-in Validation​

The widget automatically validates:

• File type against accepted MIME types
• File size against maximum size limit
• Number of files against the limit

Custom Validation Rules​

You can add custom validation rules in the Rules section:

• Required: Make the field mandatory
• Custom Rules: Add JavaScript validation functions

Screen-based Validation​

Configure widget behavior per screen in the Validation section:

• Available: Show/hide widget on specific screens
• Visible: Control visibility with conditions
• Required: Make field required on specific screens
• Disable: Disable widget on specific screens

Styling and Layout​

Basic Styling​

• Width: Set widget width (CSS units)
• Height: Set widget height (CSS units)
• Class: Add custom CSS classes
• Dynamic Classes: Set classes based on conditions

Layout Options​

• Layout: Choose between block or inline display
• Border: Enable/disable border around widget

Events and Actions​

On Change Event​

• Field: On click
• Description: JavaScript function executed when files are uploaded/removed
• Context: Access uploaded files via the model variable
• Available Variables:
  • SF_input: Object containing file information
  • SF_currentIndex: Index in loop contexts

Available Methods​

The widget provides several built-in methods:

• clearValue(): Clear all uploaded files
• setValue(val): Set files programmatically
• triggerOnChange($event): Manually trigger change event

File Object Structure​

Each uploaded file is stored as an object with the following structure:

{
  id: "unique_file_id",
  name: "filename.jpg",
  size: 1024000,
  type: "image/jpeg",
  url: "/uploads/unique_file_id/name/filename.jpg"
}

Usage Examples​

Basic Image Upload​

// Configuration
{
  name: "Profile Picture",
  model: "profileImage",
  options: {
    length: 1,
    accept: "image/*",
    maxSize: 5242880, // 5MB
    buttonName: "Choose Profile Picture",
    tip: "Upload your profile picture (JPG, PNG). Max size: 5MB"
  }
}

Document Upload with Multiple Files​

// Configuration
{
  name: "Supporting Documents",
  model: "documents",
  options: {
    length: 10,
    accept: "application/pdf,image/*",
    maxSize: 26214400, // 25MB
    isDragAndDrop: true,
    buttonName: "Upload Documents",
    tip: "Drag and drop files or click to upload. Accepted: PDF, Images. Max: 10 files, 25MB each"
  }
}

S3 Storage Configuration​

// Configuration
{
  name: "Media Files",
  model: "mediaFiles",
  options: {
    length: 20,
    accept: "image/*,video/*",
    s3: true,
    isPublic: true,
    isDragAndDrop: true,
    buttonName: "Upload Media",
    tip: "Upload images and videos to cloud storage"
  }
}

Advanced Configuration​

Conditional Visibility​

Set the widget to show/hide based on other form values:

// In Validation > Visible field
"{{otherField}} === 'upload_required'"

Dynamic File Type Acceptance​

// In On Change event of another field
function updateFileTypes() {
  if (documentType === 'images') {
    // Update accept property dynamically
    this.comp_management.imgupload_accept = 'image/*';
  } else if (documentType === 'documents') {
    this.comp_management.imgupload_accept = 'application/pdf';
  }
}

File Processing After Upload​

// In On Change event
function processUploadedFiles(files) {
  files.forEach(file => {
    console.log(`Uploaded: ${file.name}, Size: ${file.size} bytes`);
    // Additional processing logic
  });
}

Error Handling​

Common Error Scenarios​

1. File Type Not Accepted: "Type file not acceptable!"
2. File Too Large: "File size can not exceed [maxSize] Bytes!"
3. Too Many Files: "Limit is [limit] files !!"
4. Server Error: "La taille du fichier à télécharger dépasse la limite de 25Mo."

Custom Error Handling​

Add custom error handling in the On Change event:

function handleUploadError(error) {
  // Custom error handling logic
  if (error.type === 'size') {
    alert('File is too large. Please select a smaller file.');
  } else if (error.type === 'type') {
    alert('File type not supported. Please select a valid file.');
  }
}

Best Practices​

1. File Limits: Set reasonable file limits based on your server capacity
2. User Feedback: Always provide clear tip text about accepted formats and sizes
3. Validation: Use both client-side and server-side validation
4. Storage: Consider using S3 for better performance and scalability
5. Security: Be cautious with public file settings
6. UX: Use drag and drop for better user experience
7. Error Messages: Provide clear, actionable error messages

Integration Notes​

• Files are automatically uploaded to /api/v1/files/fileupload or /api/v1/files/fileupload-s3
• The widget integrates with the project's file management system
• Uploaded files are associated with the current project ID
• File metadata is stored in the specified model variable as an array