Introducing Charon File Uploader

I've wanted to build a useful JavaScript library for a while, but never found any of the ones out there lacking.  I've been working on a new project recently and one of the things I needed to do for that was be able to upload an image via AJAX, along with the alt-text and other information for the image.  There's libraries out there for uploading files and images, but I've not found one which lets you add other information to the post easily.  That's when I figured I could build it myself.  Charon was born!

Charon is named after the ferryman who took souls across the river Styx in Greek mythology.  In this case, it takes files and other information across the internet whilst the rest of the web page continues as normal.

It's still early days in development, but the majority of the workings are there.  It uses JavaScript alone to do what it needs to and doesn't rely on jQuery.  I might look to build a jQuery version at some point, but I wanted to keep it basic for now.  It's all available on GitLab for use and modification.

Documentation is available as part of the GitHub page, and there's a minified version included which reduces the footprint required to use it on a production server.  It's available under the MIT licence, so do with it what you will, but I'm not responsible for anything that goes wrong with it.

I'll be dogfooding it soon enough as I overhaul the gallery section of this site, and modify my other projects to use it too.  If there's issues, raise them on GitHub, and if I find any, I'll work to fix them too.  If I'm going to use it for things, it's going to be looked after going forward.

If you're wondering about the use case, consider the following scenario.  You've got a website (like this one) and you have a gallery on it (like this one).  For web best practices, you should have an alt-text for your images.  It's something which is better to store with the image at the time, but file uploaders tend to only look after files, not other data.  A traditional web form might be too large to post with several images on it, so you want to do the uploading at the time.  This is where Charon comes in.  You can select an image, set the alt text and upload to a script of your choice, and send back any information of your choice as easy as the following code:

var charon = new Charon({
    url: '/upload.php', // upload location
    file: document.getElementById('image1'), // file field
    additionalData: { altText: document.getElementById('altText1').value }
});
charon.sendFile();

If you then need to change the file and additional data before sending a new file, the following can do that :

charon.file = document.getElementById('image2');
charon.additionalData = { altText: document.getElementById('altText2').value };
// then send the next file
charon.sendFile();

With the custom callback functionality added in, you can get it to run your own functions as it's uploading (for managing progress bars), for when it's completed (for letting you know it's uploaded or for processing any return information) or for any other XMLHttpRequest event.

Update: This post was updated on 4th June 2020 to reflect the new location of the code in GitLab, following the migration from GitHub