| 1 |
=== WP Attachments – Smarter File Management & Download Lists === |
| 2 |
Contributors: Milmor |
| 3 |
Tags: attachments, media, file, list, classicpress |
| 4 |
Donate link: https://www.paypal.me/milesimarco |
| 5 |
Requires at least: 5.0 |
| 6 |
Requires PHP: 7.4 |
| 7 |
Tested up to: 7.2 |
| 8 |
Version: 6.1 |
| 9 |
Stable tag: 6.1 |
| 10 |
License: GPLv2 or later |
| 11 |
License URI: http://www.gnu.org/licenses/gpl-2.0.html |
| 12 |
|
| 13 |
Attach files to any post or page and let WP Attachments list them for you, with icons, file sizes and a download counter. |
| 14 |
|
| 15 |
== Description == |
| 16 |
|
| 17 |
WP Attachments turns the files you upload to a post into a clean, automatic download list. Attach a file while editing, and it shows up under your content — no manual links, no shortcodes to remember. |
| 18 |
|
| 19 |
It also fills the gaps in the WordPress Media Library, letting you attach, unattach and reattach files without leaving the screen you are on. |
| 20 |
|
| 21 |
**Key features** |
| 22 |
|
| 23 |
- 🤖 Lists attachments automatically after the post content |
| 24 |
- ℹ️ Metabox for managing, previewing, renaming and reordering the files of a post |
| 25 |
- 🔃 Attach, Unattach and Reattach actions in the Media Library |
| 26 |
- 🔢 A Files column in the post and page lists: count, visibility and a filter |
| 27 |
- 🔢 Download counter that ignores crawlers, prefetches and repeat clicks |
| 28 |
- ♿ Reordering works with the mouse, the keyboard and screen readers |
| 29 |
- 🧑💻 Filters for developers who want to change the markup |
| 30 |
- 🛍️ WooCommerce compatible, including High-Performance Order Storage |
| 31 |
- 🎨 Modern SVG icons and a Modern Card layout, plus the classic icon packs |
| 32 |
- 📜 Works with posts, pages and custom post types |
| 33 |
- 🎢 Templates with live previews, ready to customise: title, date, size, caption, downloads and more |
| 34 |
|
| 35 |
[Video Overview](https://www.youtube.com/watch?v=J7gf0hxl_z8) |
| 36 |
|
| 37 |
== Contributions == |
| 38 |
|
| 39 |
- Part of [WPGov.it](http://www.wpgov.it), providing open source solutions for Italian Public Government websites. |
| 40 |
- Thanks to the Italian community [Porte Aperte sul Web](http://www.porteapertesulweb.it) for beta testing and ideas. |
| 41 |
- Metabox based on [IJ Post Attachments](http://wordpress.org/plugins/ij-post-attachments/) |
| 42 |
- Some icons by [Yusuke Kamiyamane](http://p.yusukekamiyamane.com/). |
| 43 |
|
| 44 |
== Installation == |
| 45 |
|
| 46 |
1. Install via the WordPress.org plugin directory or upload the files to your server. |
| 47 |
2. Activate the plugin. To customise it, go to **Settings → WP Attachments**. |
| 48 |
3. While editing a post, page or custom post type you will find the **Media Attachments** metabox. Extra actions are available in the Media Library: Attach, Unattach and Reattach. |
| 49 |
|
| 50 |
== Frequently Asked Questions == |
| 51 |
|
| 52 |
= How do I hide the attachment list on a specific post or page? = |
| 53 |
Open the **Media Attachments** metabox while editing and switch off **Display attachments in frontend**, at the bottom left. The files stay attached, they are simply not listed on the site. |
| 54 |
|
| 55 |
To hide the list for a whole post type, untick **Enable Frontend** under **Settings → WP Attachments → Post Type Permissions**. |
| 56 |
|
| 57 |
= How do I avoid the same file being listed twice? = |
| 58 |
Do not insert the link manually. A file uploaded from the editor is attached to the content automatically and listed by WP Attachments, so you can simply close the media popup after uploading. |
| 59 |
|
| 60 |
= How do I reorder the files? = |
| 61 |
Three ways, all of which save straight away: |
| 62 |
|
| 63 |
* drag a row by the grip on its left; |
| 64 |
* use the **Move up** / **Move down** buttons on each row; |
| 65 |
* focus the grip and press the up or down arrow key. |
| 66 |
|
| 67 |
= How do I see which files belong to a post? = |
| 68 |
The **Files** column in the post and page lists shows how many files each one has, and an eye icon tells whether they are shown on the site. Click the number to open the Media Library filtered to just those files. The **Files** filter above the list finds posts with or without files, or with the list hidden. |
| 69 |
|
| 70 |
= Can I change the date format of the list? = |
| 71 |
Yes, under **Settings → WP Attachments → Date Format**. It accepts the standard PHP date characters and applies to the `%DATE%` tag. Leave it empty to follow **Settings → General → Date Format**. |
| 72 |
|
| 73 |
= Does the download counter count everything? = |
| 74 |
No. It skips browser prefetch requests and known crawlers, and it ignores repeat hits from the same visitor on the same file for a few minutes. Those requests still receive the file, they just do not move the number. |
| 75 |
|
| 76 |
= Which files can be previewed in the metabox? = |
| 77 |
Images, video, audio, PDF and plain text open in a preview dialog. Any other format shows its icon and a download link. |
| 78 |
|
| 79 |
= Developer filters = |
| 80 |
|
| 81 |
- **wpatt_list_html** — the whole list markup (`$html`) |
| 82 |
- **wpatt_before_entry_html** — a single entry, before the tags are replaced (`$html`) |
| 83 |
- **wpatt_after_entry_html** — a single entry, after the tags are replaced (`$html`) |
| 84 |
- **wpatt_accepted_formats** — return a falsy value to hide a file (`$mime`) |
| 85 |
- **wpatt_download_throttle** — how long the same visitor is ignored for the same file (`$seconds`, `$attachment_id`) |
| 86 |
- **wpatt_count_download_request** — whether the current request may increment a counter (`$countable`) |
| 87 |
- **wpatt_can_download** — whether the current visitor may follow a download link (`$allowed`, `$attachment_id`) |
| 88 |
- **wpatt_should_render** — whether the list is appended to this content (`$render`, `$post`) |
| 89 |
|
| 90 |
**Examples** |
| 91 |
|
| 92 |
` |
| 93 |
function my_custom_function( $html ) { |
| 94 |
// Alter the final HTML |
| 95 |
return $new_html; |
| 96 |
} |
| 97 |
add_filter( 'wpatt_list_html', 'my_custom_function' ); |
| 98 |
` |
| 99 |
|
| 100 |
` |
| 101 |
function my_pdf_only( $mime ) { |
| 102 |
// Only show PDFs in the list |
| 103 |
return $mime === 'application/pdf'; |
| 104 |
} |
| 105 |
add_filter( 'wpatt_accepted_formats', 'my_pdf_only' ); |
| 106 |
` |
| 107 |
|
| 108 |
` |
| 109 |
// Count each visitor at most once per hour |
| 110 |
add_filter( 'wpatt_download_throttle', function () { |
| 111 |
return HOUR_IN_SECONDS; |
| 112 |
} ); |
| 113 |
` |
| 114 |
|
| 115 |
There is also `wpatt_get_attachments_html( $parent_id )`, which returns the list for any parent ID without going through the `the_content` filter. |
| 116 |
|
| 117 |
== Screenshots == |
| 118 |
|
| 119 |
1. The Modern Card template on a post, with file type icons, size and date |
| 120 |
2. The Media Attachments metabox: manage, preview, reorder, unattach and delete files without leaving the editor |
| 121 |
3. Appearance settings: icon pack, icon colour and template options, each with a live preview |
| 122 |
4. The Files column in the post list: number of files, whether they are shown on the site, and a filter |
| 123 |
5. General settings: list header, display options, download counter and post type permissions |
| 124 |
6. Attach, Unattach and Re-Attach files straight from the Media Library |
| 125 |
|
| 126 |
== Changelog == |
| 127 |
|
| 128 |
= 6.1 2026-10-05 = |
| 129 |
|
| 130 |
* **New:** Modern SVG icon pack, coloured by file type, by the theme text colour or by a custom colour. |
| 131 |
* **New:** Modern Card template, with options for the details shown, the layout and the card width. |
| 132 |
* **New:** template previews in the settings, and a button to start a custom template from any template. |
| 133 |
* **New:** the Files column shows whether a post displays its files, and a Files filter is added to the post lists. |
| 134 |
* **New:** Enable Frontend setting per post type, replacing Display Default. Enable Metabox no longer hides the frontend list. |
| 135 |
* **New:** heading level setting for the list title, and `%EXT%`, `%MIME%` and `%ICON%` template tags. |
| 136 |
* New installs start with Modern SVG and Modern Card. Existing sites keep their settings. |
| 137 |
* Unattach and Delete in the metabox no longer reload the page. |
| 138 |
* **Fix:** files deleted from the metabox were left on the server. |
| 139 |
* **Fix:** download links revealed files attached to private or password protected content. |
| 140 |
* **Fix:** download counter links failed with media on a CDN; file size showed "ERROR" for offloaded media. |
| 141 |
* **Fix:** an empty list header or date format was reset on save. |
| 142 |
* **Fix:** the list no longer appears in feeds, REST responses, automatic excerpts, or under other posts shown on a single post page. |
| 143 |
* **Fix:** the Matrilineare icon pack was missing from the settings. |
| 144 |
* Frontend styles no longer load in the admin. |
| 145 |
|
| 146 |
= 6.0.3 2026-08-31 = |
| 147 |
|
| 148 |
* **New:** a Files column in the post, page and custom post type lists shows how many files are attached to each one, and links straight to them in the Media Library. |
| 149 |
* **New:** the Edit action in the metabox now opens media modal in place, so titles, captions and alt text can be changed without leaving the editor. |
| 150 |
* **Security:** fixed a cross-site request forgery issue. |
| 151 |
* **Accessibility:** files can now be reordered with the keyboard, and the frontend sort control works without JavaScript. |
| 152 |
* The download counter now ignores crawlers and browser prefetch requests. |
| 153 |
* Fixed wrong file sizes, the Date Format setting that had no effect, and the first attachment not showing up until the page was reloaded. |
| 154 |
* New file type icons, and admin assets now load only on the screens that use them. |
| 155 |
* WooCommerce: declared compatibility with High-Performance Order Storage. |
| 156 |
|
| 157 |
= 5.3.4 2026-03-14 = |
| 158 |
* Minor fixes and improvements. |
| 159 |
|
| 160 |
= 5.3 2026-02-02 = |
| 161 |
* Better permission handling |
| 162 |
* Redesigned settings screen |
| 163 |
|
| 164 |
= 5.2.1 2026-01-19 = |
| 165 |
* Minor fixes and improvements. |
| 166 |
|
| 167 |
= 5.2 2025-06-09 = |
| 168 |
* Fixed regression with images (thanks @reesher + @steeltape for feedback) |
| 169 |
* Added option to enable/disable for specific custom post types (completely or only frontend) |
| 170 |
* Other minor fixes and improvements. |
| 171 |
|
| 172 |
= 5.1 2025-05-25 = |
| 173 |
* Date placeholders in attachment templates now use the WordPress date format setting (`Settings > General > Date Format`) for better localization and consistency. |
| 174 |
* Improved templating: You can now use WordPress date formatting in your custom templates, and templating settings are more flexible and reliable. |
| 175 |
* Other minor fixes and improvements. |
| 176 |
* Major code refactoring for improved stability and maintainability |
| 177 |
* Significant performance improvements |
| 178 |
* Enhanced security throughout the plugin |
| 179 |
* Improved admin capabilities and permission handling |
| 180 |
* Brand new metabox for easier attachment management |
| 181 |
* Refreshed admin columns for better overview and usability |
| 182 |
|
| 183 |
= 5.0.12 = |
| 184 |
* Latest stable release |
| 185 |
|
| 186 |
= 5.0.6 2023-02-15 = |
| 187 |
* Compatibility check |
| 188 |
* Security fixes |
| 189 |
* Minor changes |
| 190 |
|
| 191 |
= 5.0.4 2021-10-20 = |
| 192 |
* Compatibility check |
| 193 |
* Linked development workflows on [GitHub](https://github.com/WPGov/wp-attachments) |
| 194 |
* Minor changes |
| 195 |
|
| 196 |
= 5.0 2020-11-28 = |
| 197 |
* WooCommerce compatibility: add files to client orders |
| 198 |
* Major improvements and technical changes |
| 199 |
* Rewritten add_media popup with custom behavior |
| 200 |
* Removed old translation files, now using translate.wordpress.org |
| 201 |
* Minor changes |
| 202 |
|
| 203 |
= 4.4.2 2020-04-29 = |
| 204 |
* Minor improvements |
| 205 |
|
| 206 |
= 4.4.1 2020-02-20 = |
| 207 |
* Compatibility check |
| 208 |
|
| 209 |
= Version 4.4 18/11/2017 = |
| 210 |
* **Fixed** critical bug for missing icons in WP 4.9 |
| 211 |
* Some problems may occur in previous WP versions for icons. Please update! |
| 212 |
|
| 213 |
= Version 4.3.6 10/01/2017 = |
| 214 |
* **Tested** with WP 4.7 |
| 215 |
* **Fixed** php warning in custom post types with capabilities mapped |
| 216 |
|
| 217 |
= Version 4.3.4 06/07/2016 = |
| 218 |
* 4.6 compatibility check |
| 219 |
|
| 220 |
= Version 4.3.3 02/04/2016 = |
| 221 |
* Fixed bug in metabox date |
| 222 |
* Tested with WP 4.5 |
| 223 |
|
| 224 |
= Version 4.3.2 19/02/2016 = |
| 225 |
* Fixed php notice error when debug active |
| 226 |
|
| 227 |
= Version 4.3.1 18/02/2016 = |
| 228 |
* Auto exclusion of dropdown if attachments < 2 |
| 229 |
|
| 230 |
= Version 4.3 23/12/2015 = |
| 231 |
* Added option to show a dropdown for ordering |
| 232 |
* Various improvements and bugfix |
| 233 |
* Added support for translate.wordpress.org |
| 234 |
|
| 235 |
= Version 4.2 02/08/2015 = |
| 236 |
* Added developer functions and filters |
| 237 |
* Minor improvements |
| 238 |
* ReadMe changes (FAQS added) |
| 239 |
|
| 240 |
= Version 4.1.2 6/07/2015 = |
| 241 |
* Added es_ES translations by Joaquín Alejandro Duro Arribas |
| 242 |
* ReadMe changes |
| 243 |
|
| 244 |
= Version 4.1.1 1/06/2015 = |
| 245 |
* Tested with latest beta version |
| 246 |
* Readme changes |
| 247 |
|
| 248 |
= Version 4.1 26/04/2015 = |
| 249 |
* **Added** option to exlude logged-in users from download counter |
| 250 |
* **Fixed** "extended" template |
| 251 |
* Minor bugfixes |
| 252 |
* Minor readme.txt changes |
| 253 |
|
| 254 |
= Version 4.0.2 = |
| 255 |
* Correct bug of 404 error when file title contains special characters (download counter only) |
| 256 |
* Minor improvements |
| 257 |
|
| 258 |
= Version 4.0.1 = |
| 259 |
* Fixed download error 404 for some permalinks when counter enable |
| 260 |
|
| 261 |
= Version 4.0 = |
| 262 |
* New and better metabox |
| 263 |
* Added download counter function |
| 264 |
* Added icon themes |
| 265 |
* Added multiple schemes |
| 266 |
* Redesigned options |
| 267 |
* Performance improvements (2x faster) |
| 268 |
* Minor improvements |
| 269 |
|
| 270 |
= Version 3.7 05/03/2015 = |
| 271 |
* Added filter and option to restrict the plugin to single and page views |
| 272 |
* Minor performance improvements |
| 273 |
* Fixed wrong version in settings panel |
| 274 |
* Better style for attachments list |
| 275 |
|
| 276 |
= Version 3.6.1 28/02/2015 = |
| 277 |
* Added check for password protected posts |
| 278 |
|
| 279 |
= Version 3.6 28/02/2015 = |
| 280 |
* Improved performance |
| 281 |
* Improved metabox (faster & nicer) |
| 282 |
* Improved option panel |
| 283 |
* Added opton to deactivate the plugin on certain pages |
| 284 |
|
| 285 |
= Version 3.5.6 21/10/2014 = |
| 286 |
* **Fixed** css conflict with italian schools WordPress theme "pasw2015" |
| 287 |
|
| 288 |
= Version 3.5.5 05/09/2014 = |
| 289 |
* **Added** plugin icon |
| 290 |
* **Added** serbian translation sr_RS |
| 291 |
* readme.txt changes |
| 292 |
|
| 293 |
= Version 3.5.4 26/07/2014 = |
| 294 |
* **Fixed** possible conflict with other plugins (ex. Members) |
| 295 |
* **Fixed** missing translation of "Update" button in the options panel (world-wide) |
| 296 |
|
| 297 |
= Version 3.5.3 20/07/2014 = |
| 298 |
* **Added** Brazilian Portuguese translations by Henrique Avila Vianna |
| 299 |
|
| 300 |
= Version 3.5.2 15/07/2014 = |
| 301 |
* **Fixed** add media button not being displayed when no file attached |
| 302 |
* **Fixed** metabox not showing up for add-new "admin" pages |
| 303 |
* **Upgraded** uploader to be the same as WordPress' integrated |
| 304 |
* **Improved** add media button style to exactly match the WordPress' standard |
| 305 |
|
| 306 |
= Version 3.5.1 12/07/2014 = |
| 307 |
* **Tested** and working on WordPress 4.0 (beta) |
| 308 |
|
| 309 |
= Version 3.5 09/07/2014 = |
| 310 |
* Added **unattach** link in media admin page |
| 311 |
* Added **unattach** link in page/post/cpt editor |
| 312 |
* **Improved** back-end metabox |
| 313 |
* **Improved** capability handling for attach/reattach/unattach functions |
| 314 |
* **Improved** some variables handling |
| 315 |
* **Added** function to check if a file doesn't exist and must skip filesize calculation (in order to avoid front-end errors) |
| 316 |
|
| 317 |
= Version 3.4 08/07/2014 = |
| 318 |
* Added **reattach** link in media admin page |
| 319 |
* Added **attach** link for unattached file in media admin page |
| 320 |
|
| 321 |
= Version 3.3 28/03/2014 = |
| 322 |
* **Added** option to open files in a new tab [in Settings -> WP Attachments] |
| 323 |
* **Fixed** conflict with "Members" plugin causing the metabox appearing in its options page |
| 324 |
* **Added** an "eye" icon in the editor metabox showing that the file will be listed front-end |
| 325 |
|
| 326 |
= Version 3.2.3 26/03/2014 = |
| 327 |
* **Solved** conflict with some newsletter plugins by addind code for avoiding the attachments list if the given post id is null |
| 328 |
|
| 329 |
= Version 3.2.2 12/03/2014 = |
| 330 |
* Added support for **MP3**, **ODT**, **ODS** |
| 331 |
* Changed size text for small files: now showing "< 1KB" instead of "n B" |
| 332 |
* Better compatibility for Internet Explorer |
| 333 |
|
| 334 |
= Version 3.2.1 03/03/2014 = |
| 335 |
* Added wp_enqueue_style for loading css style |
| 336 |
* Performance improved |
| 337 |
|
| 338 |
= Version 3.2 03/03/2014 = |
| 339 |
* New localization system. English & Italian already translations included |
| 340 |
* New back-end metabox. That's in beta, but i'm sure you will like it! |
| 341 |
* Better option page |
| 342 |
|
| 343 |
= Version 3.1.4 4/11/2013 = |
| 344 |
* Fixed missing 'Backend.php' (this function will be available in the next versions (3.2+) |
| 345 |
|
| 346 |
= Version 3.1.3 27/10/2013 = |
| 347 |
* Another bugfix |
| 348 |
|
| 349 |
= Version 3.1.2 27/10/2013 = |
| 350 |
* Fixed a bug causing content not to be loaded in some cases |
| 351 |
|
| 352 |
= Version 3.1.1 19/10/2013 = |
| 353 |
* List title is now hidden correctly |
| 354 |
|
| 355 |
= Version 3.1 15/09/2013 = |
| 356 |
* **Fixed** missing icon for images |
| 357 |
* **Added** option to exclude images from being listed |
| 358 |
* **Improved** settings page layout |
| 359 |
|
| 360 |
= Version 3.0.4 24/08/2013 = |
| 361 |
* **Readme** minor changes |
| 362 |
|
| 363 |
= Version 3.0.3 23/08/2013 = |
| 364 |
* **Improved** Css appearance |
| 365 |
|
| 366 |
= Version 3.0.2 23/08/2013 = |
| 367 |
* **Fixed** activation error: unespected output - 1 charater |
| 368 |
|
| 369 |
= Version 3.0.1 22/08/2013 = |
| 370 |
* **Fixed** missing external shortcode rendering |
| 371 |
* **Fixed** reduntant css code |
| 372 |
* **Improved** loop |
| 373 |
* List header doesn't show up anymore for empty attachments |
| 374 |
|
| 375 |
= Version 3.0 22/08/2013 = |
| 376 |
* **Added** Css for showing icons |
| 377 |
* **Added** file size |
| 378 |
* **Added** attachment data |
| 379 |
* **Added** options panel |
| 380 |
|
| 381 |
= Version 2.0 04/07/2013 = |
| 382 |
* First functional release. Enjoy! |
| 383 |
|
| 384 |
= Version 1.0 07/01/2012 = |
| 385 |
* First Release |
| 386 |
|
