Displaying a List of Attachments

An attachment is any file that is included with your page. Examples of attachments are screenshots, photographs, other images, Word documents, presentations, PDF documents, videos and sound files. Attachments are useful when you want to share information that exists in another file format.

You can display a list of attachments on your page – these may be the files that are attached to the current page or to any page in the space. Use the 

  • Use the Attachments macro to show a list of the attachments on the current page, or 
  • Use the Space Attachments macro to show a list of the attachments in the current space. 

Both these macros generate a table of attachments which is clickable.

Using the macros

To add the Attachments or Space Attachments macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros.
  2. Find and select the required macro.

Speeding up macro entry with autocomplete:

Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Parameters of the Attachments macro

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter

Default

Description

Filename Patterns

all

A comma-separated list of regular expressions, used to filter the attachments by file name. Note that the parameter values must be regular expressions. For example:

  • To match a file suffix of 'jpg', use .*jpg (not *.jpg).
  • To match file names ending in 'jpg' or 'png', use .*jpg,.*png

Attachment Labels (none) A list of labels, used to filter the attachments to display. If you wish to enter more than one label, separate the labels with commas. Confluence will show only attachments that have all the labels specified. (The match is an AND, not an OR.) For information on labelling the attachments, see Adding Labels.

Include Old Attachment Versions

false

A value of true will include previous attachment versions in the list.

Sort By

date

The sort order for attachments. Note that people viewing the page can change the sort order by clicking the column headings. Valid values are:

  • date – sorts by updated date in reverse chronological order (newest first)
  • size – sorts largest to smallest
  • name – sorts alphabetically
  • created date - sorts by creation date in reverse chronological order (newest first)
Sort Order ascending Used in combination with the Sort By parameter, to sort the attachments in ascending or descending order.

Allow Upload

true

If selected, the list of attachments will include options allowing users to browse for, and attach, new files.

Page Title (none) Used to display attachments from another page. If you do not enter a page title, the macro will display the files attached to the current page.
Show Previews true Used to display a preview of the attached file. If true, preview will be visible when the list item is expanded.

Viewing files and changing file properties via the Attachments macro

The list of files displayed by the Attachments macro can be expanded to show options for viewing the files and other actions, provided you have the relevant permissions.

  • If you have specified the 'Allow Upload' parameter, users will be able to upload attachments directly from the list.
  • You can delete attachments. Note that you can only delete the entire attachment (including all versions). To delete a specific version of an attachment, you must go to the 'Attachments' view. See Deleting an Attachment.
  • You can edit attachment properties and labels. If an attachment is an Office or PDF file, they will see the appropriate options for Office Connector files.
  • You can choose not to display previews in the macro. This is useful if you have very large attachments. 

Screenshot: The Attachments macro, showing details of an attachment


Parameters of the Space Attachments macro

The Space Attachments macro displays a list of all the attachments in a space. You can choose to show attachments from the current space, or another space. 

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter Default Description
Space (none) Selects the Confluence space to display attachments for. If you do not specify a space, the current space will be used.
Show Filter Controls true Determines whether or not the filter panel is shown. If you select this option, people viewing the page will be able to filter the list of attachments by file type (extension) and by label.

Screenshot: The Space Attachments macro

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport