Stacks4Stacks

The primary purpose of Droplet is to make a directory (folder) on your web server behave like a public depository. Without requiring any specialist software, your website users can use their normal web browser to drag and drop (or select) files they want to upload to you.

Some clever behind-the-scenes code within Droplet will validate and upload these files to the designated directory. From here you can automatically reuse the files in your website (like within ProGallery or PlayLister stacks). Alternatively you can download the files using your preferred FTP software or website file manager.

Droplet is built on the popular Dropzone.js plugin. We coded a smart PHP backend which will process file uploads efficiently. The PHP backend will also make the file names web safe (swapping spaces and tabs for hyphens) and provides some extended options for choosing how uploaded files are renamed. Perfect in instances when you need to add audio, video or images straight into a website.

Droplet v2

Droplet v2 is a combination of over 30 hours work to totally rewrite the underlying codebase for improved speed, compatibility and reliability. Several new features you are sure to benefit personally from have been added in Droplet v2...

• Experimental audio, photograph and video capture direct from mobile devices.
• More language translations for different interface elements.
• Simple email notifications for uploaded files, via a choice of 'mailto' or 'PHP mail' methods.
• Lots more new style and colour settings to adjust. New border styles. Colour pickers support RGBa transparency.
• Refreshed the stack settings and setup interface. Changed the ordering and grouping of some settings.
• Automatic image re-sizing and re-saving, for images you are uploading. Great to use with ProGallery.
• Ability to change the file uploader icon and make it animated.
• File chunking for large uploads, meaning big files are split into smaller upload packages and restart if the upload is interrupted.
• Integration with the updated Sentry password protection stack, so you can keep your uploader more private.
• Critically important compatibility changes with forthcoming web browser updates, like Microsoft Edge.
• More precise control towards limiting the file types and sizes that can be uploaded with this stack.
• Optional CSRF security tokens, to restrict where and how files are uploaded.
• Several other great new additions, towards making this the best possible file uploader stack.

Droplet v2 is recognised by Stacks as a new stack. It will not replace Droplet v1, if you already have that installed on your computer. It is strongly recommended that all users of Droplet v1 pay a donation. Then download and install Droplet v2. Replace copies of Droplet v1 with Droplet v2 in your websites.

Example

Here is an example of Droplet. To test it, try dragging and dropping a file onto the drop zone or selecting a file on your computer. This example is using the default settings (file types and upload limits are fully-customisable in the stack settings).

Setup

To get Droplet working on your website, follow these instructions carefully:

1. Once installed into RapidWeaver and Stacks, open your stacks library. Drag and drop a copy of Droplet into your webpage.
2. If you don't already have a directory on your web server to store uploaded files within, go-ahead and create one now in your FTP software.
3. Customise any of the messages or style settings presented in the Droplet settings. Information about directory paths is shown below.
4. Export or publish your website to a web server with PHP support (Droplet is also compatible with MAMP if you wish to test it offline first).
5. Test the uploading of files to your server, to make sure everything works as expected (the files should appear inside your designated directory).

Important! File permissions may require changing on the directory you want to upload files into. This can be a common cause of file uploads not working. Setting permissions to 777 may be too dangerous from a security perspective and some hosting companies don't allow this. Permissions of 775 might be more sensible to use on the upload directory. However, given the importance of website security, should you have any uncertainty about what permissions to apply on your upload folder, please consult with your web hosting company, and try to go with their recommendations.

It's wise not to mix Droplet stacks with other complicated stacks (like animation stacks) on the same page, as these may change the layering of the dropzone and prevent users adding files. Droplet cannot be integrated with other form stacks or plugins - it is a standalone file uploader designed to work by itself.

The Disable Uploads option disables all file uploads. Droplet will still look and function as normal, but no files will actually get uploaded. This is a useful setting if you are testing Droplet (as per our live example above) or you need to temporarily disable file uploads. Obviously it is worth putting a message somewhere on the Droplet page to tell your users that uploads have been disabled! If you want to disable uploads at an exact time, simply place Droplet inside one of our free Expiry stacks.

Directory Path

You can easily change the location files are uploaded to, by changing the Directory Path setting, in the Droplet options. You should always use a relative path and link to a directory that is stored within the same domain name that Droplet is running on. Use ../ to denote each step back-up to your root domain (from the page hosting Droplet) and then specify the path down to the directory e.g. ../../../files/user-submitted-files/. If for example your page hosting Droplet is at https://example.com/events/share-pictures/ and your uploads directory is at https://example.com/files/user-uploads/, then you would enter ../../files/user-uploads/ as the relative directory path. You can use a directory that already contains files.

File Naming

You'll notice in the Droplet settings that File Naming can be adjusted. This gives you greater control over how uploaded files are managed.

• Convert to web safe is the default setting. This will preserve file names as they are, but will replace tabs or spaces with a hyphen (-). This is the best setting to use if you need to reuse the filenames in other stacks (like PlayLister or ProGallery). If a file is uploaded that conflicts a file of the same name, then the oldest file is deleted and replaced with the new file.
• Convert to web safe and date stamp does the same as above, except the time of the upload is prepended to the file name. The time is measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). This file naming option removes the risk of newer files overwriting older files.
• Randomised will completely rename the uploaded file and give it a unique name / number.

Security

Security has to be our number one priority. The ability for complete strangers to upload files to your web server obviously increases the risk that Droplet or similar plugins could be used maliciously to compromise your websites or data. We have taken steps to reinforce the security of Droplet and follow established / recommend best practices for file uploads. For example, the location of your uploads folder is never disclosed in the source code and uploads only work if Javascript is enabled within a users web browser.

Additionally there are some important things you should action when using Droplet in your own projects:

• Use the Accepted Files option to specify exactly what file types are permitted to be uploaded. Typically you should only list common image file types, documents and .zip compressed files. Never allow executable files, Flash, scripting or other code to be uploaded.
• Adjust the Max. Files setting to restrict how many files a user can upload. This will help thwart DoS attacks, and block a sudden spike of file uploads.
• Set a Max. File Size limit. This will prevent users uploading huge files (like video) which might cause problems. Most web servers already set a file upload limit of 2MB and this is the default we use in Droplet too. Ask your web hosting company if you are unsure what the upload limit is currently set to on your server.
• Does your uploads folder need full read / write permissions? If the files being uploaded do not need to be viewed by anyone else or reused again in the website (like within a slideshow), then you can disable read permissions in your FTP software, on the uploads directory. Upload directories certainly do not need execute permissions either.
• If you don't care for how the uploaded files are named, set the File Naming option in Droplet to Randomised, for maximum security. This action will change file names to a long randomised number. A potential hacker would be unable to put executable code in the file name, and would be unable to execute any scripts uploaded (because they would not be able to see or know what the files have been renamed to).
• If the Droplet stack does not need to be on a public-facing page, put it on a hidden page or make it password protected. Stacks like Sentry are good to use for this task.
• Ensure that your web hosting account has backups and virus scanning enabled. In other words, all the normal things a good hosting clammy should be doing to keep your hosting account secure.

 

Contribute

If you find this stack element useful in your personal or commercial web projects; please consider making a small contribution towards ongoing support and updates. There are many different ways you can contribute to the Stacks4Stacks project, and benefits for doing so.