Attachments Macro
The Attachments macro displays a list of files attached to a page.
It also allows users (with appropriate permissions) to:
- upload a file to the page, directly from the list
- edit attachment properties and labels
- delete an attached file (this deletes all versions of the file)
- preview image attachments
- edit attached Office and PDF documents using the Office Connector.
- download all files attached to the page.
Note: you can use the macro parameters to turn off previews if you have very large attachments.
Screenshot: The Attachments macro, showing details of an attachment
Using the Attachments Macro
To add the Attachments macro to a page:
- In the Confluence editor, choose Insert > Other Macros
- 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 Autocomplete for links, files, macros and mentions.
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
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:
|
Attachment Labels(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 Add, Remove and Search for Labels. |
Include Old Attachment Versions | false | A value of |
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:
|
Sort Order(sortOrder) | 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(page) | (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 ( preview) | true | Used to display a preview of the attached file. If true, preview will be visible when the list item is expanded. |
Code examples
The following examples are provided for advanced users who want to edit the underlying markup for a Confluence page.
Macro name: attachments
Macro body: None.
Storage format example
<ac:structured-macro ac:name="attachments">
<ac:parameter ac:name="old">false</ac:parameter>
<ac:parameter ac:name="patterns">.*png,.*jpg</ac:parameter>
<ac:parameter ac:name="sortBy">name</ac:parameter>
<ac:parameter ac:name="page">
<ac:link>
<ri:page ri:content-title="My page about chocolate"/>
</ac:link>
</ac:parameter>
<ac:parameter ac:name="sortOrder">descending</ac:parameter>
<ac:parameter ac:name="labels">chocolate,cookies</ac:parameter>
<ac:parameter ac:name="upload">false</ac:parameter>
</ac:structured-macro>Wiki markup example
{attachments:old=false|patterns=.*png,.*jpg|sortby=name|page=My page about chocolate|sortorder=descending|labels=chocolate,cookies|upload=false|preview=false}