File
The file fieldtype allows you to upload files through the control panel. File works exceedingly well in conjunction with the grid fieldtype.
- Add file(s) by dragging and dropping onto the drop area on the left or click the drop-area to open a file browser. Files will be instantly uploaded.
- You can alternatively choose existing files from the server.
- Re-order the files by dragging and dropping them amongst the display area on the right.
- Click the
x
while hovering over a thumbnail to delete the file from the field. (It will remain on the server)
header_image:
display: Header Image
type: file
allowed: [png, gif, jpg, jpeg]
destination: assets/img/ # make sure your folder is writable
resize:
width: 500
height: 300
quality: 60
Parameters
allowed
: An array of allowed filetypesdestination
: The directory (from root) you wish to save the file(s)max_files
: The maximum number of files allowed. Unlimited by defaultbrowse
: Set tofalse
to prevent selecting existing files on the serverresize
: Configuration array of how you’d like to resize your images upon uploadforce_array
: When saving a single file, by default its saved as a string. If you’d like to always save an array, set this totrue
.
Resizing
You can choose to resize and/or manipulate all uploaded images. If you don’t add a resize option everything will be uploaded “as-is”. Available (optional) parameters:
width
: Maxiumum widthheight
: Maximum heightquality
: Between 1 and 100 (default is75
)upsize
: Whether to blow up an image to fit the desired image specs (defaults tofalse
)
Deleting files
When viewing the existing files popup, you will have the option to delete files from the server if _allow_file_field_deletions
is set to true
in settings.yaml
. This is disabled by default.
It goes without saying that you should be careful when deleting files. If they are used elsewhere, their links will become broken.
How file data is saved
If you upload a single file, the variable/path will be saved as a string. This allows you to just use a variable to output the URL.
---
my_image: /assets/img/stag.jpg
---
<img src="{{ my_image }}" />
If you upload multiple files, it will be saved as an array. You can use a tag pair to loop through the file URLs.
---
images:
- /assets/img/stag.jpg
- /assets/img/eagle.jpg
---
{{ images }}
<img src="{{ value }}" />
{{ /images }}
If you want to ensure single files are also saved as an array, add force_array: true
to your field config.
When running in a subdirectory
If you are running Statamic in a subdirectory, files will still be saved as if they are relative to the root. This allows you to move environments with file paths staying the same.
For example, if you are running in a /statamic/
subdirectory, a file might get saved to /var/www/mysite.com/public_html/statamic/assets/myfile.jpg
, but in your front-matter, it’ll be saved as /assets/myfile.jpg
(not /statamic/assets/myfile.jpg
).
If you are planning on using a subdirectory setup, you’ll want to make use of the path
tag or img
modifier. Those will adjust your file paths if need be.