# `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 the default `images` or `office` groups, or a custom group, 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
`readOnly`	Boolean	`false`	If `true`, prevents the user from editing the field value

NOTE

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 or addFileGroups options of the @apostrophecms/attachment module. Those custom group 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>

← array boolean →