DOCUMENTATION

  • Field Types
  • Files
Search »

File Upload Field

« Per-field file settings
Adding to your forms »
Uploaded filenames

Uploaded Filenames

Customize uploaded filename format
Customize uploaded filename format
With version 2.2.0 of this module you can now customize the filenames that are created when a user uploads a file. To customize the filename, you'll need to edit the Filename format setting in the Edit field dialog, found in the Edit Form » Fields page.

Placeholders

These are special placeholders that can be used in your Filename format field to control how the filename is generated. See below for some examples on how they can be used.

{$clean_filename}
This is the default value for uploaded files: they get created with a "clean" version of their original filename. Form Tools whitelists specific characters that may be included in uploaded filenames, see the $g_filename_char_whitelist setting in your config.php file for more info. Those whitelisted characters are what's used to determine the clean filename.
{$clean_filename_no_extension}
The clean file string without the filename extension. Handy if you want to add a suffix to the filename.
{$raw_filename}
This placeholder is the original filename as uploaded by the user. Generally you should avoid this placeholder: users could upload filenames with any characters whatsoever.
{$raw_filename_no_extension}
The raw file string without the filename extension.
{$extension}
The file extension (e.g. jpg in filename.jpg).
{$form_id}
The current form ID.
{$submission_id}
The current submission ID.
{$index}
The index of the file in the set of files being uploaded for a field. For fields configured as single file uploads (the default option), this value will always be 0.
{$field_name}
The name of the form field for the file upload field.
{$date}
A simple placeholder containing the current date (in whatever timezone your server thinks it currently is). This outputs the date in YYYYMMDD format, e.g. 20190126.
{$unixtime}
This placeholder outputs the current unixtime, but can also be used to output a date or time in any format you want. To customize the format, you need to use the date_format modifier like so: {$unixtime|date_format:"M-n-Y"}. The content of the double quotes are whatever formatting string you'd like. See the PHP date method for the list of available placeholders.

Note that in case of a filename conflict, the module will rename files to ensure each filename is unique. So if you upload a file that happens to have the same name as an existing file - even after whatever custom filename format you entered, it will still automatically rename it.

Examples

Here are a few examples to get an idea of how you can use the placeholders in the field. As you can see from below, any characters that aren't in a placeholder get included in the filename. The one exception is the colon character: that's not a valid character in filenames on Unix or Windows systems so it will always be stripped out, even if it's part of your date formatting string.

{$submission_id}-{$field_name}-{$index}.{$extension}
Three png images uploaded through a multiple-field upload field, where the submission ID is 35 and the field name is filefield.
  • 35-filefield-0.png
  • 35-filefield-1.png
  • 35-filefield-2.png
{$submission_id}-{$field_name}-{$index+1}.{$extension}
Same as the last one, except it starts the numbering from 1.
  • 35-filefield-1.png
  • 35-filefield-2.png
  • 35-filefield-3.png
f{$form_id}-s{$submission_id}-{$clean_filename}
Tacks on the form ID and submission ID as a prefix to the clean filename. This helps to visually identify which files in your upload folder belong to which form and submission.
  • f5-s39-infodoc.xls
  • f5-s29-happypic.jpg
{$clean_filename_no_extension}-{$date}.{$extension}
Displays the filename with the YYYYMMDD appended as a suffix to the filename.
  • greenbug-20190127.png
  • fritillarybutterfly-20190127.gif
{$clean_filename_no_extension}-{$date}.{$extension}
Displays the filename with the YYYYMMDD appended as a suffix to the filename.
  • greenbug-20190127.png
  • fritillarybutterfly-20190127.gif
{$clean_filename_no_extension}-{$unixtime|date_format:"MjS-h-ia"}.{$extension}
Displays the filename with the YYYYMMDD appended as a suffix to the filename. As mentioned above, you cannot include colons (:) in the date formatting string because they are invalid filename characters on most systems. If you do, they will be stripped out.
  • aniseswallowtail-Jan27th-05-48pm.png
  • beetle-Jan27th-05-48pm.png
« Per-field file settings
Adding to your forms »
Edit Page