=== Seven Creative File List ===
Contributors: christopheseven
Tags: file list, downloads, documents, shortcode, directory
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display files from an uploads folder as a linked list, table or image grid using a simple shortcode.

== Description ==

Seven Creative File List creates a server-rendered list of public files in a folder beneath your site's WordPress uploads directory. Useful for brochures, forms, public reports, meeting minutes and other downloadable resources.

Add or remove files in the chosen folder and the list reflects those changes when the page is regenerated. Clear page caches if the public page still shows an older list.

Features:
* Linked lists, tables, image grids and plain comma-separated URLs.
* File type filters, simple filename matching and exclusion filters.
* Natural filename sorting, or sorting by modified date or file size.
* Optional sizes, dates, headings, friendly filenames and new-tab links.
* Files do not need to be registered in the Media Library.
* No JavaScript, admin settings, database tables, external service or telemetry.

This is a new implementation by Seven Creative. It does not register legacy shortcodes or reuse an earlier plugin's settings. Follow the migration guidance before replacing another file-list plugin.

IMPORTANT: This plugin is for public downloads. It does not protect files, check membership, issue private links or restrict direct access. A password-protected page alone does not protect files in uploads. Do not point it at confidential, personal or restricted documents.

== Installation ==

1. Open Plugins > Add New Plugin > Upload Plugin.
2. Upload the ZIP without extracting it and activate Seven Creative File List.
3. Put public files into a folder beneath your WordPress uploads directory, for example wp-content/uploads/downloads/.
4. Add a Shortcode block to a page or post and enter [sevencreative_files folder="downloads"].
5. Save and view the public page.

Use your hosting file manager or SFTP to create a dedicated folder and upload files. This plugin does not upload, move, edit or delete files. On sites using a customised uploads location or multisite, folder paths are relative to that site's own uploads base directory.

To list files uploaded normally into a monthly folder, use an actual folder such as folder="2026/10". The folder value is always relative to the uploads root, not the current month. Do not add ../ segments or use an absolute server path or URL.

== Usage ==

Basic list:
[sevencreative_files folder="downloads"]

PDF table with dates:
[sevencreative_files folder="downloads" types="pdf" format="table" show_date="true" prettyname="true"]

Latest 10 reports:
[sevencreative_files folder="reports" types="pdf,docx" orderby="date" order="desc" limit="10"]

Image grid:
[sevencreative_files folder="gallery" format="images" show_size="false" prettyname="true"]

Only filenames containing annual, excluding draft and internal:
[sevencreative_files folder="reports" contains="annual" exclude="draft,internal"]

Custom title and empty-folder message:
[sevencreative_files folder="downloads" title="Useful downloads" empty_text="Downloads will be added shortly."]

Hide the message when no files match:
[sevencreative_files folder="downloads" empty_text=""]

== Shortcode options ==

folder: Path relative to uploads. Default downloads. An explicitly empty value lists files directly in the uploads root, not its subfolders. Slash-separated nested folders are supported. Dot segments and hidden folder names are rejected.
format: list (default), table, images or comma. Comma returns plain URLs rather than clickable links, and ignores title, class, size and date options.
types: Comma-separated extensions without dots, for example pdf,docx. Case-insensitive. Only supported extensions are listed, even when a type is requested explicitly.
orderby: name (default), date or size. Date means the file's modification time, not its Media Library upload date.
order: asc (default) or desc. Date with desc shows newest first; size with desc shows largest first.
limit: Maximum displayed matches after filtering and sorting. Default 100; range 1 to 1000. There is no unlimited mode or pagination. Use smaller folders for larger collections.
prettyname: true replaces hyphens and underscores with spaces and removes the extension. Default false. This changes the display label, not the file.
removeextension: true removes only the extension. Default false.
show_size: true or false; default true.
show_date: true or false; default false. Dates use your WordPress date format and timezone.
target: _blank opens links in a new tab with appropriate security attributes and an accessible announcement. Default _self.
contains: Case-insensitive text that must occur in the original filename. Default empty.
exclude: Comma-separated case-insensitive text fragments. Any matching filename is omitted. Default empty.
title: Optional visible title for list, table and images formats.
class: Optional CSS class names, separated by spaces, on the outer wrapper.
empty_text: Message when there are no results; default No files available. Use an empty value to hide it. Administrators still see configuration errors when applicable.

Boolean values accept true/false, yes/no, on/off or 1/0. Prefer true and false in examples. Invalid formats fall back to list, invalid sort fields to name, and invalid order values to ascending.

Supported extensions:
pdf, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, rtf, txt, csv, zip, 7z, epub, jpg, jpeg, png, gif, webp, avif, bmp, ico, mp3, m4a, wav, ogg, mp4, m4v, webm, mov.

Image grids automatically limit results to supported image extensions. Filenames provide the visible link labels; the images are treated as decorative within those labelled links. The plugin does not produce thumbnails, so use sensibly sized images.

== Migration from another file-list plugin ==

1. Back up your pages and note their existing shortcode settings.
2. Install this plugin alongside the existing plugin while you prepare the changes.
3. Replace old shortcodes with [sevencreative_files ...]. This does not happen automatically.
4. Express folder paths relative to uploads, without ../ segments.
5. Choose list, table, images or comma and copy the applicable filter/sort options using the names above.
6. Replace size-removal options with show_size="false". Use contains and exclude for simple filename filters.
7. Check each updated page, then deactivate the previous plugin once no pages rely on it.

This plugin intentionally does not support arbitrary working directories, regex filters, custom HTML templates, custom table headings, recursive scans or legacy shortcode aliases. It never changes or deletes the original files.

== Frequently Asked Questions ==

= Why are some files missing? =
Check the selected folder, type filters, filename filters and limit. Subfolders are not scanned. Hidden files, symlinks, unsupported extensions and names containing dangerous script/backup extensions are excluded. A folder containing over 10,000 directory entries is rejected rather than partially listed.

= Does it work with cloud-offloaded media? =
Only when files remain on the local server and the configured uploads URL serves the same relative paths. It cannot enumerate a remote storage bucket or CDN by itself.

= Does it force downloads? =
No. It creates ordinary links. Browser and server settings determine whether a file opens or downloads.

= Can I use it for private documents? =
No. Use a dedicated access-controlled download system for confidential or members-only files. This plugin does not change server access controls.

= Will updates appear immediately? =
They appear when the page is regenerated. A page cache or CDN may need clearing after folder changes. The plugin does not add its own cache.

= Why is no folder created on activation? =
The plugin is read-only. Create a folder and upload public files with your host's file manager or SFTP.

= What happens when I remove it? =
Your files remain untouched. Remove its shortcodes from your pages to prevent them displaying as plain text.

= Is this free to redistribute? =
Yes, under GPL version 2 or later. Preserve the applicable copyright and licence notices. See LICENSE.txt.

== Changelog ==

= 1.0.1 =
* Documented a Plugin Check false positive on the filename exclusion option with a narrowly scoped annotation. No database queries or shortcode behaviour changed.

= 1.0.0 =
* Initial Seven Creative implementation with uploads-only folder containment, escaped output, safe file-type filtering, natural sorting and responsive layouts.
