Uploads
Uploads are used to store the URL and metadata of a file that the user uploaded.
Defining
You can define uploads by adding a property with type
set to upload
, for example:
- name: document
type: upload
Options
Property upload
takes an extra options
parameter, which allows you to configure it.
Option | Description |
---|---|
acl | If set to public (default) the file will be publicly available. If set to private , a signature generated on the server-side will be needed in order to access the file. It will be automatically generated by GraphQL when you provide the expires_in argument to the property_upload GraphQL method. |
content_length | Allows you to set server-side validation for minimum (using gte key) and maximum file size (using lte key) in kilobytes. For example, lte: 2048 will set the max input file size (not the generated version) to 2MB. |
versions | Allows you to define up to 10 versions of the image. For each version you can define multiple different processing instructions - compression, resizing, etc. This option will be ignored if the uploaded file is not an image. Visit List versions options |
cache_control | Allows you to set the Cache-Control header returned with the file. Default is max-age=315576000, public |
content_disposition | Allows you to set the Content-Disposition header. Default is inline , you can change it to attachment . |
Versions
Versions are defined in yml as an array. Each element must have a name
and then a list of options you want to use. Please note that not all combinations make sense. An example configuration might look like this:
properties:
- name: photo
type: upload
options:
content_length:
lte: 2048 # maximum input file size will be 2048 KB
versions:
- name: large_bw # version name
output:
format: jpeg # output format
quality: 70 # output quality
resize:
width: 1600 # width of the image - in this case max width
height: 1200 # height of the image - in this case max height
fit: inside # preserve aspect ratio, do not crop the image, make sure all pixels are within viewport
without_enlargement: false # if image is smaller than width/height, do not enlarge it
manipulate:
greyscale: true # make image greyscale (similar to css "filter: grayscale(1)")
blur: 20 # blur using gaussian mask (similar to css "filter: blur(1.5rem)")
flatten: red # merge alpha transparency channel (if exists) with given color
- name: small
output:
format: webp
quality: 80
resize:
width: 640
height: 480
fit: cover
position: top # define the gravity direction or strategy when cropping the image using fit cover or contain
- name: thumb
output:
format: png
quality: 80
resize:
width: 200
fit: contain
background: "rgba(255, 255, 255, 0.5)" # if the resized image is not covering whole viewport, set background color, can be in hex format (ie. #f0f0f0), or rgb (ie. rgb(255, 255, 255))
- name: center
output:
format: jpeg
quality: 100
resize:
height: 400
width: 400
fit: cover
This is exactly the same configuration which we have used in our examples site to demonstrate Direct s3 upload with uppy. Try it out by going to the Direct S3 upload images and uploading an image. Please note that you will need to create a free account to access that page if you don't have one yet.
Output
format
[String] - Force Extension of an output image, leave blank if you want to keep the format of the original image.
quality
Int - Quality of the output. 100 being the best (and largest in terms of size). Keep in mind compression has different effects on different formats. Defaults: PNG: 80
, WEBP: 80
, JPEG: 85
progressive
[Boolean] - Only format: jpeg
- use progressive (interlace) scan. Default: true
Resize
width
[Int] - width that the user passed as a reference. If left undefined, will depend on other parameters to determine size (like: height)
height
[Int] - height that the user passed as a reference. If left undefined, will depend on other parameters to determine size (like: width)
fit
[String] (cover
, contain
, fill
, inside
, outside
) - how the image should be resized to fit both provided dimensions
cover
: Crop to cover both provided dimensions (the default).contain
: Embed within both provided dimensions.fill
: Ignore the aspect ratio of the input and stretch to both provided dimensions.inside
: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.outside
: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified. Some of these values are based on the object-fit CSS property.
position
[String] (top
, right top
, right
, right bottom
, bottom
, left bottom
, left
, left top
) - position to use when fit
is cover
or contain
. default: center
background
[String|Object] - background color when using a fit of contain, parsed by the color module, defaults to black without transparency. Default: #000000
or { r: 0, g: 0, b: 0, alpha: 1 }
.
without_enlargement
[Boolean] - do not enlarge if the width or height are already less than the specified dimensions. default: false
Manipulate
greyscale
[Boolean] - Convert to 8-bit greyscale; 256 shades of grey. Default: false
blur
[Int|Float] (0.3 - 1000) - value representing the sigma of the Gaussian mask, where sigma = 1 + radius / 2
flatten
[String|Object] - Default: #000000
or { r: 0, g: 0, b: 0 }
Sending the upload to the server
To store an upload, you need to first upload a physical file directly to S3. When you do it successfully, you will receive an URL to the actual file - you need to store this URL in the property. This process is described in detail in User Upload.
Fetching an upload from a server
To fetch the URL of the uploaded image, use the property_upload
argument to generate the signature to access the private file. The signature will automatically expire after the number of seconds you specify. Please note, you will not be able to access the URL when you fetch all properties at once using properties
in your GraphQL query, as the URL is generated on the fly inside the property_upload
method.
You can check the example code of how to store the URL and then retrieve it in the next guide - User Upload