DropMate

DropMate is a powerful drag-and-drop TypeScript / JavaScript library designed to streamline image uploads and file management. It supports customizable file input fields, image previews, reordering, and options for editing pre-existing images. The library offers flexible options for integrating into both static HTML and modern frameworks like React, Vue, and TypeScript.

Features

• Drag-and-Drop File Upload: Effortlessly upload images via drag-and-drop, or click on the DropMate box to open a file selection dialog.
• Image Preview: Instantly view uploaded images in a preview container.
• Max Files Limit: Control how many images a user can upload.
• Custom Input Name & ID: Automatically generate input fields with default or custom attributes.
• Edit Existing Images: Load pre-existing images for editing and reordering.
• Reordering: Rearrange uploaded or existing images.
• Auto-load Images: Automatically load images with names and sources for easy management.

Installation

Using NPM (for frameworks like React, Vue, etc.)

1. Install DropMate via npm:

   npm install dropmate

2. In your main JavaScript/TypeScript file, import the DropMate library and CSS:

   import DropMate from 'dropmate';
   import 'dropmate/dist/bundle.css';

Using Direct Script & CSS Links (for HTML only environments)

You can include the pre-built JavaScript and CSS files directly in your HTML:

<script src="path-to-dropmate/dist/bundle.js"></script>
<link rel="stylesheet" href="path-to-dropmate/dist/bundle.css">

This will make the DropMate object globally available in your HTML environment.

Usage

Basic Setup

For DropMate to function, you need two elements: a container for the image previews and a dropMate for file uploads. Here’s an example:

HTML

<div>
    <div id="dropMatePreviewContainer"></div>
    <div id="dropMate"></div>
</div>

JavaScript

To initialize DropMate, use the following script:

document.addEventListener("DOMContentLoaded", function() {
    const dropMate = new DropMate('dropMatePreviewContainer', 'dropMate');
});

Options

DropMate uses data attributes in HTML to control its behavior. These attributes can also be passed via the options object in JavaScript.

| Attribute | Description | |-------------------------|--------------------------------------------------------------------------------------------------| | data-max-files | The maximum number of files allowed. If not specified, the default is 10. | | data-input-attributes | JSON object specifying the attributes for the file input field (e.g., name, multiple, id). | | data-image-names | An array of image names (for editing). | | data-image-srcs | An array of image URLs (for loading preview images). |

If attributes are provided both via data attributes and JavaScript options, JavaScript options take precedence.

Options - Usage

Through HTML

You can provide options through HTML using data attribute. Here’s an example:

<div>
    <div id="dropMatePreviewContainer"></div>
    <div id="dropMate"
        data-max-files="10" 
        data-input-attributes='{"id": "dropmate-input", "name": "dropmate-input[]"}'
    >
    </div>
</div>

Through JavaScript

You can provide options through JavaScript as well. Here’s an example:

document.addEventListener("DOMContentLoaded", function() {
    const dropMate = new DropMate('dropMatePreviewContainer', 'dropMate', {
        maxFiles: 10,
        inputAttributes: {
            id: 'dropmate-input',
            name: 'dropmate-input[]',
            multiple: true
        }
    });
});

Handling Pre-existing Images

DropMate supports pre-loading images for editing scenarios. Use the imageNames and imageSrcs options to load images:

Through HTML

<div>
    <div id="dropMatePreviewContainer"></div>
    <div id="dropMate"
        data-image-names='["image 1", "image 2"]'
        data-image-srcs='["/images/image1.jpg", "/images/image2.jpg"]'
    >
    </div>
</div>

Through JavaScript

const dropMate = new DropMate('containerId', 'dropMateId', {
    imageNames: ['image 1', 'image 2'],
    imageSrcs: ['/images/image1.jpg', '/images/image2.jpg']
});

Input Field Customization

DropMate automatically generates an input field. The default attributes are:

{
  type: 'file',
  id: 'dropmate-images',
  name: 'dropmate-images[]',
  multiple: true,
  autocomplete: 'off',
  required: false
}

You can customize these attributes by passing an inputAttributes object in the constructor:

const dropMate = new DropMate('containerId', 'dropMateId', {
    inputAttributes: {
        name: 'custom-file-input',
        multiple: false
    }
});

Reordering Images

DropMate allows users to easily reorder uploaded images through a drag-and-drop interface, enhancing the management of image sequences.

How It Works

When you drag an image and place it on top (or near) another previewed image, the following behavior occurs:

• The dragged image takes the place of the image it is dropped onto.
• The image that was previously in the dropped position shifts forward to the next available spot.
• All images that are positioned between the dragged image and the replaced image also shift forward, while any images after this sequence remain unchanged.

Example of Reordering Behavior

Consider a scenario where you have the following ten images displayed:

1. Image 1
2. Image 2
3. Image 3
4. Image 4
5. ...
6. Image 10

If you drag Image 3 and drop it onto Image 1, the resulting order will be:

1. Image 3 (now in place of Image 1)
2. Image 1 (now moved to the position of Image 2)
3. Image 2 (now moved to the position of Image 3)
4. Image 4 (remains unchanged)
5. ...
6. Image 10 (remains unchanged)

In this case, only the images between the dragged Image 3 and the replaced Image 1 move forward by one position, while all other images (4 through 10) remain in their original places.

Example

Here’s a full example of DropMate,with options from HTML, in action:

<div id="dropMatePreviewContainer"></div>
<div id="dropMate"
     data-max-files="5"
     data-input-attributes='{"id": "dropMate-files", "name": "dropMate-files[]", "multiple": true}'
     data-image-names='["img1.jpg", "img2.jpg"]'
     data-image-srcs='["/uploads/img1.jpg", "/uploads/img2.jpg"]'></div>

<script>
    document.addEventListener("DOMContentLoaded", function() {
        const dropMate = new DropMate('dropMatePreviewContainer', 'dropMate');
    });
</script>

This setup allows for a maximum of 5 files and preloads two images (img1.jpg and img2.jpg) into the dropMate for preview and reordering.

API

Constructor Options

The DropMate constructor accepts the following options:

• containerId (string): ID of the container where the image previews will be displayed.
• dropMateId (string): ID of the drop zone where files are dropped.
• options (optional object):
  • maxFiles (number): Maximum number of files allowed. Defaults to 10.
  • inputAttributes (object): Custom attributes for the file input field.
  • imageNames (array): Array of image names (for editing).
  • imageSrcs (array): Array of image URLs (for loading).

TypeScript Support

DropMate is fully written in TypeScript, offering complete type support out of the box. You can leverage TypeScript for enhanced development experience and strict typing for DropMate's API and options.

Author

Muneeb

Contact

For support or inquiries, please reach out to me at [email protected].

Contributing

Contributions, issues, and feature requests are welcome !

License

DropMate is licensed under the MIT License.