# attachment

An attachment field allows the user to upload a file to the server, or replace a file which was previously uploaded. Attachments are most often used indirectly through the core image and file piece types. Each of those piece types contains an attachment field and some metadata fields, making them a convenient way to reuse files.

You may also use attachment fields directly as well, however doing so means that the uploaded file will not be available in the media library or file manager. It will only be accessible as a property of the piece or page where it is uploaded. This can be appropriate for files that are only relevant for a single piece of content, such as resumes and job applications for a specific person.

# Module field definition

All fields in a piece or page module use their object key as their database field name (e.g., resume below).

// Configuring the `resume` field in a module's `fields.add` subsection:
resume: {
  label: 'Resume',
  type: 'attachment',
  fileGroup: 'office'

# Settings

# Required

Property Type Default Description
label String n/a Sets the visible label for the field in the UI
type String n/a Specifies the field type (attachment for this type)

# Optional

Property Type Default Description
fileGroup String n/a Can be set to images or office to limit the file types that can be uploaded. See more below.
help String n/a Help text for the content editor
htmlHelp String n/a Help text with support for HTML markup
if Object {} Conditions to meet before the field is active. See the guide for details.
required Boolean false If true, the field is mandatory


The uploaded files are stored in a web-accessible folder, however their file names are prepended with a randomized ID to avoid naming collisions.

# Custom file groups

Developers can configure file type groups in addition to office and image using the fileGroups option of the @apostrophecms/attachment module. Those custom groups names can then be used for an attachment field's fileGroup setting.

# Use in templates

The attachment field value will be an object with various properties, including many metadata properties. They can be accessed directly, but it is more common to use a template helper when working with attachments in templates.

The most common helper method for attachments in templates is apos.attachments.url. Once an attachment field has a value, you can obtain the file's public URL with the apos.attachments.url template helper.

<!-- `data.piece.resume` is an attachment object -->
<a href="{{ apos.attachment.url(data.piece.resume) }}">Download</a>