File inputs

A File input lets your team members upload a file to your repository or DAM, reference the file path for existing assets, and link to external assets. File inputs have a file preview in the Data Editor and sidebar of the Visual and Content Editors, as well as a repository or DAM browser for searching assets.

There are three types of File input:

File
Document
Image

For each input, you can configure the default path for uploading assets, which MIME types an input will accept, which DAMs you can upload to and browse, and how CloudCannon handles empty values. For inputs that accept images, you can configure how CloudCannon resizes images, MIME type, and whether CloudCannon creates additional images of different sizes when you upload a new asset.

You can also use the general configuration options available for all inputs.

File#

The File input provides an editing interface for uploading files to your repository or DAM and browsing existing assets.

You can configure a File input using the type key with the value file. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

cloudcannon.config.yaml

copied

_inputs:
  example_css:
    type: file

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This File input is called example_css.

The value of the type key determines the input type. This is a file input.

cloudcannon.config.json

copied

{
  "_inputs": {
    "example_css": {
      "type": "file"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This File input is called example_css.

The value of the type key determines the input type. This is a file input.

Once configured, the File input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

blog.md

copied

---
example_css: /guides/tutorial-styles.css
---

Blog content goes here.

Document#

The Document input provides an editing interface for uploading documents to your repository or DAM and browsing existing assets.

You can configure a Document input using the type key with the value document. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

cloudcannon.config.yaml

copied

_inputs:
  download_newsletter:
    type: document

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Document input is called download_newsletter.

The value of the type key determines the input type. This is a document File input.

cloudcannon.config.json

copied

{
  "_inputs": {
    "download_newsletter": {
      "type": "document"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Document input is called download_newsletter.

The value of the type key determines the input type. This is a document File input.

Once configured, the Document input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

about.md

copied

---
download_newsletter: /newsletters/july-2024.pdf
---

Page content goes here.

Image#

The Image input provides an editing interface for uploading images to your repository or DAM and browsing existing assets.

You can configure an Image input using the type key with the value image. Define the type key under your input key name within _inputs. For more information, please read our documentation on configuring your inputs.

cloudcannon.config.yaml

copied

_inputs:
  logo:
    type: image

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Image input is called logo.

The value of the type key determines the input type. This is a image File input.

cloudcannon.config.json

copied

{
  "_inputs": {
    "logo": {
      "type": "image"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Image input is called logo.

The value of the type key determines the input type. This is a image File input.

Once configured, the Image input will appear in the Data Editor or sidebar of the Visual or Content Editor when you add it to a data file or the front matter of a markup file.

footer.yml

copied

logo: /web-assets/logo.png

Options#

You can configure File inputs using the options key under your input key, inside of _inputs.

cloudcannon.config.yaml

copied

_inputs:
  image:
    type: image
    options:
      paths:
        uploads: images
      accepts_mime_types:
        - image/png
        - image/jpeg
      allowed_sources:
        - site-files
      empty_type: 
      resize_style: crop
      width: 400
      height: 300
      expandable: true
      prevent_resize_existing_files: false
      mime_type: image/png
      sizes:
        - size: 2x
          target: _retina_image_file
image: /uploads/image.png
_retina_image_file: /uploads/image-2x.png

cloudcannon.config.json

copied

{
  "_inputs": {
    "image": {
      "type": "image",
      "options": {
        "paths": {
          "uploads": "images"
        },
        "accepts_mime_types": [
          "image/png",
          "image/jpeg"
        ],
        "allowed_sources": [
          "site-files"
        ],
        "empty_type": null,
        "resize_style": "crop",
        "width": 400,
        "height": 300,
        "expandable": true,
        "prevent_resize_existing_files": false,
        "mime_type": "image/png",
        "sizes": [
          {
            "size": "2x",
            "target": "_retina_image_file"
          }
        ]
      }
    }
  },
  "image": "/uploads/image.png",
  "_retina_image_file": "/uploads/image-2x.png"
}

File inputs have the following options available:

paths — Object#

This key enables you to define paths for your Rich Text editors or File inputs. The following nested keys are available:

dam_static
dam_uploads
dam_uploads_filename
static
uploads
uploads_filename
uploads_use_relative_paths

This key has no default. If undefined at higher levels of the configuration cascade, paths will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Rich Text editors or File inputs.

paths.dam_static — String#

This key enables you to define the path for the location of statically copied assets for DAM files.

paths.dam_uploads — String#

This key enables you to define the path for the default location of newly uploaded DAM files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.dam_uploads_filename — String#

This key enables you to define the name of a file, after uploading it to a DAM.

paths.static — String#

This key enables you to define the path for the location of statically copied assets.

paths.uploads — String#

This key enables you to define the path for the default location of newly uploaded files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.uploads_filename — String#

This key enables you to define the name of a file, after uploading it.

paths.uploads_use_relative_paths — Boolean#

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

accepts_mime_types — String or array of strings#

This key restricts which file types you are allowed to select or upload through an input. Each File input type has a different default:

File: *
Image: image/x-icon,image/gif,image/jpeg,image/jpeg,image/png,image/webp,image/bmp,image/svg+xml
Document: application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-powerpoint,application/vnd.openxmlformats-officedocument.presentationml.presentation

If this key uses a string value, the value format should be a comma-separated (no spaces) list of accepted MIME types. The string * allows any type.

If this key uses an array of values, each item in the array should be a string containing a single accepted MIME type.

allowed_sources — Array#

This key lists which DAMs you are allowed to upload to and browse. Valid values include site-files and the reference key for any DAM connected to your site.

If site-files is omitted from the array, site files will not be available as an asset source for this input.

empty_type — String#

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

string - an empty value for this input will be stored as "".
null - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

If the input accepts images, the following options are also available:

resize_style — String#

This key determines how CloudCannon resizes images prior to uploading them to your repository or DAM. CloudCannon resizes images using a bounding box defined by the width and height options. Defaults to contain, if width and height are defined.

Value must be one of the following:

crop — Prompts the user to choose a region of the image that matches the dimensions of the bounding box.
cover — Keeps the original aspect ratio of the uploaded image but enlarges the image to match the largest dimension of the bounding box.
contain — Keeps the original aspect ratio of the uploaded image but reduces the image to match the smallest dimension of the bounding box.
stretch — Ignores the original aspect ratio and resizes the image to match the dimensions of the bounding box.

If either width or height are not defined, the contain, cover and stretch options will not work. For the cropoption, width and height are optional, and control the minimum size and aspect ratio of the crop region.

width — Integer#

This key determines the width of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the resize_style option.

height — Integer#

This key determines the height of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the resize_style option.

mime_type — String#

This key determines what format CloudCannon will convert an image to prior to uploading it. CloudCannon also updates the file extension. Defaults to keeping an image's original MIME type.

Value must be one of:

image/jpeg
image/png
image/webp

expandable — Boolean#

This key determines whether you can expand an image to fit the bounding box when resizing an image prior to upload. Defaults to false. Has no effect if files are not resized.

prevent_resize_existing_files — Boolean#

This key determines whether CloudCannon will prompt you to resize an existing image when you select it through this input. Defaults to false.

When resizing an existing image, CloudCannon will save the resized copy without overwriting the original file.

sizes — Array of objects#

This key determines whether CloudCannon will create additional images of different sizes when uploading or selecting an image through this input. This key has no default.

Each entry in the array contains the following fields:

size — Set the dimensions for the additional image file. Value must be a number with the "x" suffix for relative size or "w" suffix for fixed width (e.g., 2x, 3x, 100w, 360w).
target — References another input. CloudCannon sets the value of this target input to the file path of the additional image file.

If CloudCannon cannot create an additional image (e.g., the image you uploaded is too small), CloudCannon does not set the value of the target input.

Unconfigured File inputs#

In some cases, CloudCannon can still detect a File input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name:

path, or that ends in _path, as a File input.
document or document_path, or that ends in _document or _document_path, as a Document input.
image or image_path, or that ends in _image or _image_path, as an Image input.

data.yml

copied

background_image: /images/forest.jpeg

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

We recommend configuring your inputs for greater control over their functionality and appearance.

Valid values#

Here are some examples of valid values for the key file. These work for File, Document, and Image inputs.

Empty/null value:

file:

Any valid string (quoted or unquoted):

file: ""
file: ''
file: path/to
file: "path/to"
file: 'path/to'

Any valid string:

file = ""
file = ''
file = "path/to"
file = 'path/to'

Null value:

"file": null

Any valid string:

"file": ""
"file": "path/to"