Bob's Guides

FileUpload Snippet Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

This snippet is for use with MODX Revolution. FileUpload can be used to upload a variable number of files in the front end of your site. FileUpload is based on Michel van de Wetering's FileUpload snippet for MODX Evolution. It has been refactored for MODX Revolution and some new capabilities have been added. If it fully compatible with MODX 3.

Installing FileUpload for MODX Revolution

Go to Extras | Installer (Package Management) on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put FileUpload in the search box and press Enter. Click on the "Download" button, and when the download is finished, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Find FileUpload in the grid and click on the "Install" button. Follow the prompts to install FileUpload.

Using FileUpload

You can place a file upload form on any page by inserting the following tag:

[[!FileUpload]]

The form will present a number of file upload fields. The user can browse to each file to be uploaded. When the user clicks on the "Upload File(s)" button, the snippet will attempt to upload the files. The user will get feedback on the success or failure of the upload for each file. You can place more than one upload form on a page simply by repeating the snippet tag. Each form can send files to a separate directory.

You can control the number of file upload fields shown on each form with the &filefields property. There is no limit on the number of fields. The default is 5. You restrict the groups who can upload with the &uploadgroups property. If you leave out that property, anyone can upload. The &path property specifies the directory where the uploaded files will be placed. The path you specify will be appended to the value in the assets_path System Setting and your path should not have a slash at the beginning. If you leave out the &path property, the files will go to assets/uploads/ directory. Here is an example using those properties:

[[!FileUpload?
    &filefields=`20`
    &uploadgroups=`Administrator,Editors,Subadmins`
    &path=`uploads/mygallery/picnic/`
]]

Using a TV to specify the path

Rather than supplying a &path property, you can put the upload path in a template variable and send the name of that TV in the &uploadtv property.

For example, create a TV called "UploadPath" and attach it to the template for the pages where the snippet will be used. Edit those pages, and on the TV tab, set the upload path for that TV. The upload path you specify will be appended to the MODX base path. It should have a slash at the end, but not at the beginning.

If you set the default value of the TV to something like this when you create it:

@INHERIT some/path/

You'll only have to set it for a parent document and the children will inherit the value. If the value is unset for some page, the default path will be used.

To use the TV to specify where the uploaded files will go, do this in the FileUpload tag:

[[!FileUpload? &uploadTv=`UploadPath`]]

Each page that uses the snippet will then have its own upload path, depending on the setting of the TV for that page.

Directory Creation and Permissions

If you specify a path for the files that does not exist, the &createpath property determines whether the directories for the path will be created or not. The default is not to create the path, which is somewhat more secure, but you may choose to override that if you want Manager users to be able to create file directories.

The &dirpermission property sets the permission for any newly created directories. The default is 0755.

File Size and File Extension Issues

The &maxsize property limits the size of uploaded files, though any upload limit set in php.ini will also be respected. If you leave out this property, the upload_maxsize System Setting will be used. The &extensions property specifies a comma-separated list of the allowable extensions for uploaded files. The list should have no spaces and no periods. If omitted, the value from the upload_files System Setting will be used. Note that the default value of upload_files is a long list, but at this writing, some of the standard image types are missing.

FileUpload Plugin

FileUpload fires the OnFileManagerUpload System Event. It sends information on the uploads. For each attempted file, it includes the name, size, type, tmp_name, extension, and error. If the upload was successful, error will be 0, if not it will contain an error message. The information also includes the directory to which the files were intended to be uploaded.

The package includes an example plugin that shows how to process the upload information. The plugin is disabled. To create your own plugin, duplicate the example, make sure it's connected to the OnFileManagerUpload event, and enable it. Don't forget that last step.

You can do whatever you like in the plugin. One common use is to email someone the information about the uploaded files. You could also create a file containing a log of uploaded files.

Note that the format of the information is not the same as that sent from other MODX code that fires the OnFileManagerUpload event (it's much more convenient to work with). The code at the top of the plugin prevents it from executing unless the Event was fired by the FileUpload snippet. Be sure not to remove it.

FileUpload Properties

Styling FileUpload Sections

The file: /assets/components/fileupload/css/fileupload.css contains the CSS for the upload form. You'll probably want to change it. Create a copy of the file in the same location called myfileupload.css and edit that file so your work won't be overwritten when you upgrade the component. Add the following property to your FileUpload snippet tag:

&cssfile=`myfileupload.css`

Copyright © 2011-2025
Bob Ray