@neoflow/extended-file-input v0.0.1

Extended File Input

A JavaScript library which extends file inputs with translation and validation support.

• Simple and lightweight. Only ~1KB (gzipped).
• Written in TypeScript. Compiled to ES6.
• Native JavaScript. No jQuery required.
• Easy to configure. Options and callbacks.

Coming soon: Check out the demo page to see the library in action.

Table of Contents

• Requirements
• Installation
• Usage
  • Configuration
  • Events
• jQuery
• Contributors
• License

Requirements

• Any browser which fully supports ES6.

Please note Internet Explorer 11 and older is not supported.

Installation

You have 2 options to install the library.

Via npm...

npm install @neoflow/extended-file-input

...or manually download the latest release from here.

Usage

1. Create a file input.

<input type="file"  />

2. Link the JavaScript-library and add the following JavaScript-code to initialize the library.

<script src="your/path/to/extended-file-input.min.js"></script>
<script>
    // Select each file input
    document.querySelectorAll('file[type="file"]').forEach((input) => {
        
        // Initialize the library for each file input
        extendedFileInput(input, {
            // Your custom options
        });
    });
</script>

3. Enjoy the validation and translation support for your file inputs.

Configuration

The library is configurable on initialization with two arguments.

The first argument is the selected file input you want to use. The second argument is an object literal for the options, separated in four different categories.

// Select each file input
document.querySelectorAll('file[type="file"]').forEach((input) => {

    // Initialize the library for each file input
    extendedFileInput(input, {
    
        // Validation rules
        rules: {
            
            // Allowed size in bytes of each file
            filesize: 2097152, // 2MB
            
            // Allowed file extension for each file
            // Can be false or set as string[], e.g: ['zip', 'rar'] 
            fileExtensions: false, 
    
            // Allowed number of files
            // Can be false or set as number
            numberOfFiles: false,
        },
    
        // Translations
        rules: {
            chooseFile: 'Choose file...',
            chooseFiles: 'Choose files...',
            browse: 'Browse',
            invalidNumberOfFiles: 'The number of files is limited to {num} file(s)',
            invalidFileExtensions: 'The files are restricted to the following file extensions: {ext}',
            invalidFileSize: 'The file size is limited to {size}',
        },
    
        // Callbacks
        callbacks: {
    
            // Triggered once after the initialization
            initialized: (detail) => {},
    
            // Triggered after each change
            changed: (detail) => {
                if (!detail.result.valid) {
                    alert(detail.result.message);
                }
            }
        }
    });
});

Events

Similar to the callbacks in the options, the library triggers also two different events on the file input.

// Select each file input
document.querySelectorAll('file[type="file"]').forEach((input) => {
    
    // Initialize the library for each file input
    const fs = extendedFileInput(input, {
        // Your custom options
    });

    // Triggered once after the initialization
    fs.addEventListener('fs-initialized', (e) => {
        console.log('Extended file input initialized');
    });
    
    // Triggered after each change
    fs.addEventListener('fs-changed', (e) => {
        if (!e.detail.result.valid) {
            alert(detail.result.message);
        }
    });
});

jQuery

The library does not offer any support for jQuery or as a jQuery-plugin implementation. If needed, then you have to create the jQuery handling with a few lines of code by yourself.

// Wait until jQuery is ready 
(($) => {

    // Select each file input
    const $fileInput = $('input:file').each(function(_index, input) {

         // Initialize the library for each file input
        extendedFileInput(input, {
            // Your custom options
        });
    });

    // Listen to the events trigger by the library
    $fileInput.on('fs-initialized', function () {
        console.log('Extended file input initialized');
    });
})(jQuery);

Contributors

• Jonathan Nessier, Neoflow

If you would like to see this library develop further, or if you want to support me or show me your appreciation, please donate any amount through PayPal. Thank you! :beers:

License

Licensed under MIT.

Made in Switzerland with :cheese: and :heart: