You can add file upload functionality in Pages, Config, Plugins and Themes blueprints. File uploads are always Ajax based and allow Drag & Drop from the desktop or picking them as regular file fields. Everytime a file is added to the field, it's automatically uploaded to a temporary folder, and will only be stored when the Save (or Submit) action takes place.
Example of usage:
custom_file: type: file label: A Label destination: 'user/plugins/my-plugin/assets' multiple: true accept: - image/*
A file field has multiple options available, from the accepted MIME type or extension, to the file size allowed:
custom_file: type: file label: A Label multiple: false destination: 'self@' random_name: false avoid_overwriting: false limit: 10 filesize: 5 accept: - image/*
multiple: false # [false | true]
Like a regular HTML5 file field, when the
multiple option is enabled, it allows to upload more than a single file. This setting is also tied to the
limit option, which determines how many of the multiple files are allowed for the field.
destination: 'self@' # [<path> | self@ | page@:<path> | theme@:<path>]
Destination is the location where uploaded files should be stored. This can be either a regular
path (relative to the root of Grav),
self@ or one of the special
self@ is not allowed outside of the Pages scope, an error will be thrown. If you use a file field outside of a Page, you should always change the
If it's desired to upload files to a plugin
testing folder (
user/plugins/testing), destination would be:
Assuming we have a blog item at the route
/blog/ajax-upload (physical location being
user/pages/02.blog/ajax-upload), with the
page@: prefix the destination would be:
Assuming the current theme is
antimatter and we want to upload to the assets folder (physical location being
user/themes/antimatter/assets), with the
theme@: prefix the destination would be:
random_name: false # [false | true]
random_name is enabled, the uploaded file will get renamed with a random string 15 characters long. This is helpful if you wish to hash your uploaded files or if you are looking for a way to reduce names collision.
'my_file.jpg' => 'y5bqsGmE1plNTF2.jpg'
avoid_overwriting: false # [false | true]
avoid_overwriting is enabled and a file with the same name of the uploaded one already exists in
destination, it will be renamed. The newly uploaded file will be prefixed with the current date and time, concatenated by a dash.
'my_file.jpg' => '20160901130509-my_file.jpg'
limit: 10 # [1...X | 0 (unlimited)]
multiple setting is enabled,
limit allows to constrain the number of allowed files for an individual field. If
multiple is not enabled (not enabled by default),
limit automatically falls back to 1.
limit is set to 0, it means that there are no restrictions on the amount of allowed files that can be uploaded.
It is good practise to always ensure you have a set limit of allowed files that can be uploaded. This way you have more control over your server resources utilizasions.
filesize: 5 # in MB, [1...X | 0 (unlimited: constraint to `system.media.upload_limit` setting)]
This setting allows to constrain the maximum size, in MB, for each individual file. When set to 0, it is considered unlimited, however it is constraint to your Grav
system.media.upload_limit as well as your PHP settings.
accept: - 'image/*' # Array of MIME types and/or extensions. ['*'] for allowing any file.
accept setting allows an array of MIME type as well as extensions definitions. All of the extensions need to be starting with the
. (dot) plus the extension itself.
In addition you can also allow any file by simply using the * (star) notation
accept: - .yaml - .json
accept: - 'image/*' - 'video/*'
accept: - 'image/*' - 'video/*' - .mp3
accept: - '*'