Legacy Documentation
You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.
File¶
File fields store uploaded files and images, and utilize the built-in file browser for your publishers to upload and insert files. Your site must have at least one upload directory before you can create a file field.
Field Options¶
Allowed File Types¶
Gives the option to limit the file field to images only, or allow all safe file types.
Allowed Directory¶
Gives the option to limit the file field’s ability to browse and upload to certain directories. You can allow all directories, or only allow one directory to browse and upload to.
Show Existing Files?¶
When the form is rendered on the front-end using Channel Form, this setting allows you to specify whether or not you’d like to show existing files in the selected upload directory and allow the user to choose from those in addition to being able to upload a new file, or do not show existing files and only allow the user to upload a new file.
Existing Files Limit¶
Regarding the Show Existing Files? option above, allows you to limit the number of files that appear in the existing files drop down.
Template Tags¶
Single Variable Usage¶
In its most basic form, a File field can be used as a single tag that simply outputs the URL of the file:
{news_image}
If you have defined any Constrain or Crop you can modify the tag with the Short Name of the manipulation. For example, if you’ve defined a “small” manipulation, the following will output the URL to that version:
{news_image:small}
Wrap Parameter¶
You will frequently want to link to the file in your entry. Using the wrap parameter can simplify this process:
{news_image wrap="link"}
Will render as:
<a href="http://example.com/dir/filename.ext">filename</a>
It can also be used to create image tags. In this case the filename will be used to create the alt parameter.
{news_image wrap="image"}
Which will output as:
<img src="http://example.com/dir/filename.ext" alt="filename" />
Variable Pair Usage¶
You can show detailed information about the file by using it as a tag pair and then referencing any of the available variables:
{news_image}
This file is a {extension} and was uploaded on {upload_date format="%Y %m %d"}
<a href="{url}">View it now</a>
{/news_image}
directory_title¶
{directory_title}
This variable simply displays the content from the “Descriptive name of upload directory” setting for the directory that the file is in.
file_size¶
{file_size}
The size of the file (in bytes). To display the size in a human friendly manner, (e.g. 147KB) use:
{file_size:human}
This includes the appropriate <abbr> HTML tag. Or, if you prefer to have the units spelled out, (e.g. 147 kilobytes), use:
{file_size:human_long}
If you have defined any Constrain or Crop you can modify this tag with the Short Name of the manipulation. For example, if you’ve defined a “small” manipulation, the following will output the file size of that version:
{file_size:small}
{file_size:small:human}
{file_size:small:human_long}
height¶
{height}
The height of the image (in pixels) if applicable.
If you have defined any Constrain or Crop you can modify this tag with the Short Name of the manipulation. For example, if you’ve defined a “small” manipulation, the following will output the height of that version:
{height:small}
id_path¶
{id_path='gallery/full_image'}
The URL to the specified template. The ID number of the entry will be automatically added. For example, this:
<a href="{id_path='gallery/full_image'}">my picture</a>
Would be rendered like this:
<a href="http://example.com/index.php/gallery/full_image/234/">my picture</a>
modified_date¶
{modified_date format="%Y %m %d"}
The date the file was last modified. See Date Variable Formatting for more information.
upload_date¶
{upload_date format="%Y %m %d"}
The date the file was first uploaded. See Date Variable Formatting </templates/date_variable_formatting> for more information.
url¶
{url}
The full URL to the file.
If you have defined any Constrain or Crop you can modify this tag with the Short Name of the manipulation. For example, if you’ve defined a “small” manipulation, the following will output the URL to that version:
{url:small}
width¶
{width}
The width of the image (in pixels) if applicable.
If you have defined any Constrain or Crop you can modify this tag with the Short Name of the manipulation. For example, if you’ve defined a “small” manipulation, the following will output the width of that version:
{width:small}