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.
requiredIf	Object	{}	Conditions to meet before the field is required. See the guide for details.
hidden	Boolean	false	If true, the field is hidden
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>