Attachment Table macro - 8.x

On this page

Overview

The Attachment Table macro produces a table of attachments based on various selection criteria, including powerful space and page selection.

Further customization is possible by specifying filters to select attachments by name, comment content, and labels. You can select and indicate the order in which columns are to be displayed based on their column name or number. Refer to Columns available to display for details.

The resulting table can be customized and supports most common table capabilities.

Depending on the selection criteria used and a number of attachments, pages, and spaces that need to be processed, this could be a long running process. Choose your selection criteria carefully and consider using the Cache macro to limit the number of times the attachment list generation needs to be done and/or the Future macro to defer processing. The limit parameter described below can also be used to limit processing.

Basic use

This macro can be deployed using any of the following methods:

Selected from the macro browserAdvanced Tables - Attachment Table
Markup shortcut{attachment-table}

Screenshot

See a live site creatively using the attachment-table macro

Parameters

Refer to Use regex expressions to select attachments to learn how to form the regular expressions that are supported by several parameters of the macro. 

Click a column heading to toggle the sorting of that column.

Attachment settings

TabsMacro editor label
Default
DescriptionMacro parameter
Page filteringSourcecurrent page

Select the available source of a page from which you can fetch the attachments.

  • Single page: This is the default option. Select the source Space and Page values from the respective drop-down lists to fetch the attachment from.
  • Regular expression: Enter the respective parameter values as explained in the succeeding four rows.
attachmentSource
Filter by space key or space name

Enter a regular expression (regex) to match with space keys or space names. Used in combination with the Page name regex parameter to select pages from which attachments are to be chosen. If left blank, the Page to list attachments from parameter is required.

The following options indicate:

  • @self - current space or page
  • @home - homepage of current space
  • @parent - parent page of current page or space 

    It is possible that in page preview, before publishing for the first time, the result for @self and @parent are not displayed as expected. Once you save the document, you can view the result as expected.

spaceRegex
Include personal spacesOffEnable to control whether personal spaces matching Space key or space name regex are to be included or not, to process and render attachments from the specified spaces.includePersonalSpaces
Filter by page name
Enter a regular expression (regex) pattern to match on page names (titles). Used in combination with the Space key or space name regex parameter to select pages from which attachments are to be chosen.pageRegex
Filter by page label
Enter a regular expression (regex) pattern match on page labels. Used in combination with the Page name regex and Space key or space name regex parameters to select pages from which attachments are to be chosen. Pages must match with every selection criteria.pageLabelRegex
Attachment filteringAttachment name regex
Enter a regular expression (regex) pattern to match on attachment names. Used in combination with the Attachment comment regex and Attachment label regex parameters to select attachments. Attachment must match with every selection criteria.attachmentRegex
Attachment comment regex
Enter a regular expression (regex) pattern to match on attachment comments. Used in combination with the Attachment name regex and Attachment label regex parameters to select attachments. Attachment must match with every selection criteria.commentRegex
Attachment label regex
Enter a regular expression (regex) pattern to match on attachment labels. Used in combination with the Attachment name regex and Attachment comment regex parameters to select attachments. Attachment must match with every selection criteria. Matching technique is determined using the Label match option parameter.labelRegex
Label match optionsingle

Specify the manner in which to apply the Attachment label regex parameter (for attachments) and the Page label regex parameter (for pages) when looking for matching labels. The options are:

  • single: An attachment, that has at least one label that matches the Page label regex or Attachment label regex pattern, is considered as selected.
  • allPage label regex and Attachment label regex are used to match a blank separated list of all labels.
labelMatchOption
Data settingsColumns to displaydefault columns

Enter a comma-separated list of column names or numbers in any order. When blank, a default set of columns is shown. Columns are enumerated starting at 1.

See Columns available for display below for a list of columns.

columns
Text to display when no attachments match
Enter the text to be displayed when no attachments are found that match the given search criteria. If left blank, no text is displayed if no attachments are found.textForNone
Date formatConfluence default

Enter a date format to format the dates in the created and modified columns. Use a simple date format string.

dateFormat
Limit number of attachments to retrieve1000Enter the number of attachments that the macro must retrieve in total. Processing stops after the number of attachments found matching the selection criteria reaches the limit value. Space, page, and attachment processing is ordered by attachment name.limit
Retrieve attachments from child pagesfalse

Enable this option to list the child page attachments of the specified page in Space and Page parameters in the Page filtering tab. By default, only the attachments on the specified page are displayed.

This option works only if Single page is selected in Page filtering > Source.

fromAllChildPages

Common parameters

The parameters listed on this page are a part of our common table capabilities that are available in many macros that produce or modify tables.

Click a column heading to toggle the sorting of that column.



Columns available for display

The Attachment Table macro allows the user to select the columns to be displayed as well as the order in which the columns are to be displayed. A default set of columns is displayed unless an explicit list is provided. You can select and indicate the order in which columns are to be displayed based on their column name or number. Use the columns parameter to specify a comma separated list of column names or numbers. 

The column names are case insensitive.

In most cases, the column heading can be used instead of the column name, but there are a few cases where that is ambiguous. In such a case, the first column matching the heading is used.

Default columns for single page attachmentsfile, size, creator, created, comment
Default columns for multiple page attachmentspage, file, size, creator, created, comment


Examples

Other macros

The list of all other macros available within this app is as follows:

Additional references