This documentation is for the old version. Go to the latest Upload Suite docs

Filtering Files by Names and Types

Usually it makes sense to allow to upload only certain kinds of files. For example, if you use Image Uploader to:

  • gather photo print orders, you would prefer to show only JPEG files
  • upload web graphics, you would show GIF and PNG files as well
  • send documents to a storage, you would disable all the images and allow uploading only PDF files

This topic describes how to manage file type restrictions in Image Uploader.

To specify file type limitations, use the Restrictions.FileMaskFileMask (ASP.NET)FileMask (PHP)fileMask (JavaScript) and Restrictions.DeniedFileMaskDeniedFileMask (ASP.NET)DeniedFileMask (PHP)deniedFileMask (JavaScript) properties. The first property specifies a file mask that designates which files should be visible in Image Uploader. The second one specifies a file mask for the files denied to be displayed.

Both properties support the following wildcards:

  • asterisk (*) for arbitrary substring
  • question mark (?) for single arbitrary character

Several masks can be specified. Use a semicolon to separate them.

Here are few examples of file masks:

  • *.jpg for files which have the .jpg extension (most JPEG files)
  • *.* for all the files which have any extension
  • *.doc;*.xls for files which have either .doc or .xls extension (Microsoft Office files)
  • *.mp? for most MPEG audio files (.mp3, .mp2, .mpa, .mp+ and etc)

Although Image Uploader does not show "wrong" files by default, users can see them after clicking Total files. The denied files cannot be selected, so they have no checkboxes near them. If a user tries to add such files to upload list, Image Uploader displays an error message saying why this file is denied. Besides, each denied file is equipped with a tooltip containing the same error message text. This text can be customized using the Messages.FileNameNotAllowedFileNameNotAllowed (ASP.NET)FileNameNotAllowed (PHP)fileNameNotAllowed (JavaScript) property.

Important

The Restrictions.FileMask and Restrictions.DeniedFileMask properties allow infiltrating files only by their names. Though it cannot guarantee that files, say, with the .jpg extension are JPEG files indeed. A malicious user can rename executable files to .jpg and upload them as if they are images. That is why if an application Image Uploader is integrated with has increased security requirements, it is highly recommended to verify uploaded files on the server side.

Another reason for it is that a potential hacker can always emulate Image Uploader using <input type="file">. It will enable them to bypass Image Uploader and upload dangerous files. So the file mask filter never gives a 100% guarantee that only proper files are uploaded.

In other words, the Restrictions.FileMask and Restrictions.DeniedFileMask properties can be used only for the user's convenience. It should not be interpreted as a serious protection from malicious users.

The code samples below demonstrate four different filters.

Allow Images Only

This example shows how to allow only images with .jpg, .jpeg, .png, .gif, .bmp extensions.

ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <Restrictions FileMask="*.jpg;*.jpeg;*.png;*.gif;*.bmp"/>
    <Messages FilenameNotAllowed="You can add only images."/>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$uploader->getRestrictions()->setFileMask("*.jpg;*.jpeg;*.png;*.gif;*.bmp");
$uploader->getMessages()->setFileNameNotAllowed("You can add only images.");
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    restrictions: {fileMask: '*.jpg;*.jpeg;*.png;*.gif;*.bmp'},
    messages: {fileNameNotAllowed: 'You can add only images.'}
});

Allow Documents Only

The code below makes visible documents of following types: .txt, .rtf, .pdf, .doc, .docx, .xls, .xlsx.

ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <Restrictions FileMask="*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx"/>
    <Messages FilenameNotAllowed="You can add only documents."/>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$uploader->getRestrictions()->setFileMask("*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx");
$uploader->getMessages()->setFileNameNotAllowed("You can add only documents.");
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    restrictions: {fileMask: '*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx'},
    messages: {fileNameNotAllowed: 'You can add only documents.'}
});

Deny Executable Files

This example disables executable files via the Restrictions.DeniedFileMask property.

ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <Restrictions DeniedFileMask="*.exe;*.bat;*.cmd;*.wsf"/>
    <Messages FilenameNotAllowed="You are not allowed to add executable files."/>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$uploader->getRestrictions()->setDeniedFileMask("*.exe;*.bat;*.cmd;*.wsf");
$uploader->getMessages()->setFileNameNotAllowed("You are not allowed to add executable files.");
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    restrictions: {deniedFileMask: '*.exe;*.bat;*.cmd;*.wsf'},
    messages: {fileNameNotAllowed: 'You are not allowed to add executable files.'}
});

Allow MPEG Files Only

The last example shows how to use a question mark (?) in files masks. Here Image Uploader allows selecting files like .mp3, .mp2, .mp+ and etc. This mask could be useful for allowing MPEG audio files only.

ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <Restrictions FileMask="*.mp?"/>
    <Messages FilenameNotAllowed="You can add only MPEG audio files."/>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$uploader->getRestrictions()->setFileMask("*.mp?");
$uploader->getMessages()->setFileNameNotAllowed("You can add only MPEG audio files.");
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    restrictions: {fileMask: '*.mp?'},
    messages: {fileNameNotAllowed: 'You can add only MPEG audio files.'}
});

See Also

Reference

Manual