Attachment Table macro - Cloud

Overview

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

Further customization is possible by specifying filters to select attachments by name, comments, and labels. You can select and indicate the order of the columns in the table to be displayed based on column name or number. Refer to the Columns available to display section 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 Limit number of attachments to retrieve parameter described below to limit processing.

Basic use

This macro can be added to a page using any of the following methods:

Selected from the macro browserAdvanced Tables - Attachment Table
Markup shortcut (Old editor){attachment-table}
Markup shortcut (New editor - case insensitive)/Attachment Table

Screenshot

See a live site creatively using the attachment-table macro

Parameters

Refer to How to use regex expressions to select attachments to learn how to form the regular expressions with the parameters. 

Macro specific parameters

Macro Editor LabelDefaultDescriptionMacro Parameter
Page to list attachments fromMost recent attachment uploaded to the current page

Enter the location where the attachments are available. The following locations are supported:

  • page - Data is read from an attachment to the page specified here; provided that page is in the same space as the macro.
  • space:page - Data is read from an attachment to the specified page that is in the specified space.

Space key or space name regex

Enter a regular expression (regex) pattern 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 - home page 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 spacesfalseEnable 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
Page name regex
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
Page label regex
Enter a regular expression (regex) pattern to 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 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
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 defaultEnter 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 here are a part of our common table capabilities that are available to many macros that produce or modify tables.
Macro Editor LabelDefaultDescriptionMacro Parameter
Heading rows1

Enter the number of rows that act as heading rows. Heading rows are not included when columns are sorted.

This parameter is not available for the Attachment Table macro.

heading
Footing rows0

Enter the number of rows that act as footing rows. Footing rows are not included when columns are sorted.

This parameter is not available for the Attachment Table macro.

footing
Columns to show

Enter a comma-separated list of column names or numbers in any order. By default, all columns are displayed in their existing order. Note that columns are indexed beginning at "1" and excludes any auto-numbered columns.

This parameter is not available for the Table Plus macro.

columns
Enable column sortingtrueDeselect this option to disable sorting of columns. By default, all columns are sorted automatically based on their column types.enableSorting
Enable row highlighting on mouse overtrueDisable this option to stop row highlighting as the mouse moves over a table row. By default, the row is highlighted as the mouse moves.enableHighlighting
Enable heading attributestrueDisable this option to apply the column attributes only to data rows. By default, any column attributes provided are applied to the all column rows including heading rows. enableHeadingAttributes
Auto number on each rowfalseEnable this option to show an additional column that displays the row number for each row. By default, the table rows are not numbered.autoNumber
Auto total rowfalse

Enable this option to append a row at the end of the table that contain the totals of all numeric columns. 

Specify the relevant numeric types in Column types to render the totals. See Column types for more information.

autoTotal
Allow download and exportfalse

Enable this option to allow download or export of the current table view as a CSV file. When enabled, download and export icons () are displayed to the right of the table. File is downloaded to the user's local file system, or is exported as an attachment to the current page. Note that only those users that have the permission to add attachments to the page are allowed to export tables.

allowExport
Export file delimiter, (Comma)

Enter a single character to be used as a delimiter for the table to be downloaded or exported. By default, a comma (,) is used as the delimiter. Valid only if Allow download and export is enabled. Available since 2.9.0. 

  • Any character can be used as a delimiter for the table contents.
  • If multiple characters are entered in the text box, an error is displayed. Specify a single character in the macro editor to be used as a delimiter to complete the export process.
  • After the export is complete, the file contains the table data interspersed with the specified delimiter.

Display data filterfalse

Enable this option to see filter panel above the table to filter the data. Panel contains a text box to enter the required search criteria and buttons: Filter to proceed with the search, and Clear to clear the box to start a new search. Can use regular expressions. To know more about regular expressions, refer to this article

This parameter is not available for the Attachment Table macro.

displayDataFilter
Sort auto number columnfalse

Select this option to enable the auto number column to be sortable. This retains the original data row count even after row sorting. 

This parameter is not available for the Attachment Table macro.

autoNumberSort
Sort descendingfalseEnable this option to sort in the descending order, to be done automatically, before display. This works only if Auto sort column is specified.sortDescending
Show sort iconfalseEnable this option to include a sort icon in the first heading row for sortable columns. An icon is displayed for the last column sorted indicating the direction in which the column was sorted.sortIcon
Auto sort column
Enter a valid column name or number to automatically sort the table before it is displayed. No automatic sorting is done if this value is not provided or is invalid. A column number is indexed beginning at "1" and excludes any auto-numbered columns.sortColumn
Sort tip on mouse over


Enter the text to be displayed when the mouse is over a sortable column. 

Example: Click to sort or an equivalent translation.

sortTip
Column types
Column types determine how column data can be sorted and displayed. By default, column data is treated as a text string, and thus, can be sorted automatically when a column heading is clicked. CSV macros may automatically generate more precise column types. When the default behavior is less than optimal for your situation, the Column types parameter can be set specifically.

Numeric types are right-aligned, by default. To display the totals of any numeric column(s), you must specify the relevant numeric type for the required columns in Column types, and enable the Auto total row option.

This table describes the behavior of the various types. 

columnTypes
Column calculations
When an auto total parameter is selected, this parameter can be used to customize the calculation or text that is shown on the total row. By default, all numeric fields, as specified by column types, are totaled. By specifying a comma separated list of calculation requests, the behavior can be modified using special values for the corresponding column.
columnCalculations
Row styles

Enter a comma-separated list of styles to be applied to the specified rows. Each style is made up of one or more properties. The first style is applied to all heading rows determined by the Number of heading rows parameter. The remaining styles are applied to the remaining rows in order with repetition as necessary. A style can be reused for subsequent rows by referring to it using a 1-based numeric reference. A column number is indexed beginning at "1" and excludes any auto-numbered columns. 

Row styles are applied to the table row and participate with other CSS properties to determine the look of an element. In particular, some properties can be overridden by table or element styles or classes.

Example: background:lightyellow, background:lightblue

rowStyles
Retain row style order after resortingtrueEnable this option to make the row styles correspond to the order in which the rows are displayed on the screen. If not selected, the original style given to a row is retained regardless of where the row lands after sorting.retainRowStyleOrder
Apply row style to individual cellfalseEnable this option to apply the styles mentioned in Row styles to each cell of the specified row(s). This option is used to override the default Confluence styles and make the user-defined styles persist for the specified table rows. Available since version 2.8.
Column styles

Enter a comma-separated list of styles to be applied to the columns in the specified sequence. Each style is made up of one or more CSS properties (semi-colon separated). If a column is skipped, supply a comma before adding the next columns style. A style can be reused for subsequent columns by referring to it using a 1-based numeric reference. A column number is indexed beginning at "1" and excludes any auto-numbered columns. 

Column styles are applied to the table column and participate with other CSS properties to determine the look of an element. In particular, some properties may be overridden by table, row, or element styles or classes.

Example: background:lightyellow, background:lightblue,1,2,1,2

columnStyles
Apply Column styles to data column cells
Enable this option to apply the styles mentioned in Row styles to each cell of the specified row(s). This option is used to override the default Confluence styles and make the user-defined styles persist for the specified table rows. Available since version 2.8.
Column attributes
Enter a comma-separated list of values used to modify cell HTML attributes for all cells in a column. The position in the comma-separated list corresponds to the column that the values apply to. Each value is a double semi-colon list of attributeName=value pairs to be applied to the column cells. See HTML attributes for more information.columnAttributes
Highlight colorlightgoldenrodyellowEnter a color to highlight when the mouse is over a row element. See Web Colors for instructions on how to specify this.highlightColor
Table idAuto generatedDisplays the table ID that can be referenced for use in other macros (like the Chart macro) or Javascript.id
Table class@default

Specify the table class (CSS) to apply to render tables.

  • @default - Apply the default Confluence table class to rendered tables.
  • @none - Do not apply any style to rendered tables.

Currently, Confluence Cloud does not support the use of custom user-defined styles.

class
Table style

Specify style attributes for the table.

Example: font-style:italic; background:lightblue;.

style
Table width

Enter width for the table border in pixels or as a percentage (%). It is recommended to use Table style instead. 

This parameter is not available for the Attachment Table macro.

width
Table border width

Enter width for the table border in pixels. Set Table class to blank if the width specified here is to be applied to the table. It is recommended to use Table style instead. 

This parameter is not available for the Attachment Table macro.

border

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

Below is a list of all other macros available within this app: