Learn

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 filetypes
  • destination: The directory (from root) you wish to save the file(s)
  • max_files: The maximum number of files allowed. Unlimited by default
  • browse: Set to false to prevent selecting existing files on the server
  • resize: Configuration array of how you’d like to resize your images upon upload
  • force_array: When saving a single file, by default its saved as a string. If you’d like to always save an array, set this to true.

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 width
  • height: Maximum height
  • quality: Between 1 and 100 (default is 75)
  • upsize: Whether to blow up an image to fit the desired image specs (defaults to false)

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.

This article was last updated on September 13th, 2016. Find an error? Please let us know!