=== Sawir Media Folders ===
Contributors: sawirricardo
Tags: media, folders, media library, organize, attachments
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Fast, unlimited folders for the WordPress media library with drag & drop.

== Description ==

Organize your media library into folders and subfolders. No folder limits, no upsells.

* **Unlimited folders and subfolders** — no caps.
* **Fast** — the whole folder tree loads with two database queries, regardless of library size. Filtering uses WordPress's native media query.
* **Safe** — folders are virtual (a taxonomy). Physical files never move, so no URL ever breaks. Deleting a folder never deletes files.

== How it works ==

**Where folders appear**

* *Media → Library (grid view)*: the full folder tree panel with drag & drop. The panel does not appear in list view.
* *Media modals* (post editor, featured image, galleries): the same folder tree, docked on the left of the file browser. Hidden on small screens.

**The tree panel**

* *All files* shows everything; *Uncategorized* shows files not in any folder.
* Folder counts include files in subfolders.
* Folders with subfolders show a ▾ arrow — click it to collapse or expand. Collapse state is remembered per browser.
* The « button in the panel header minimizes the whole panel to a slim strip (» restores it). Remembered per browser, applies to the grid and modals alike.
* Drag the panel's right edge to resize it. The width is remembered per browser and shared between the grid and modals.
* *New* creates a top-level folder. Hover a folder for its actions: **+** new subfolder, **✎** rename, **×** delete.
* Rename inline: double-click a folder's name (or click **✎**), type the new name, press Enter. Esc cancels.
* A file lives in exactly one folder at a time.

**Sorting**

The Sort row under the panel header orders the files shown on the right — by date, modified, name, or author, ascending or descending. It applies to whichever folder (or All files) is selected. Sorting by file size isn't offered: WordPress doesn't store attachment sizes in a sortable way.

**Putting files in folders**

* Drag any file from the grid onto a folder — on the Media Library page or inside a media modal.
* To move several at once: *Bulk select* (or in a modal, just select multiple), pick files, drag the selection onto a folder.
* Drag files onto *Uncategorized* to remove them from their folder.

**Moving and reordering folders**

Drag a folder onto another folder. The drop position decides what happens:

* *Top edge* (line above): insert **before** that folder.
* *Bottom edge* (line below): insert **after** that folder.
* *Middle* (dashed outline): nest **inside** that folder, after its existing children.
* Dropping on *All files* or *Uncategorized* moves the folder to the top of the root level.
* Prefer buttons? Hover a folder: **↑ / ↓** move it among its siblings, **⇄** opens a dropdown to pick a new parent folder (or top level).
* A folder cannot be moved into its own subtree.
* Untouched folders sort alphabetically; once you drag one, its siblings keep your manual order.

**Downloading a folder**

Hover a folder and click **⬇** to download it as a zip. Subfolders are included as folders inside the zip; duplicate filenames are auto-renamed (photo.jpg, photo-2.jpg).

**Deleting a folder**

Files are kept and become uncategorized. Subfolders move up one level (to the deleted folder's parent).

== Automatic organization (for developers) ==

New uploads can be filed into folders automatically with the `sawirmf_auto_folder` filter. Return a folder path (created if missing), an existing folder ID, or null to leave the upload uncategorized. Nothing is auto-filed unless you add a rule — the default is off.

File PDFs into "Documents", and WooCommerce product images into "Products":

`add_filter( 'sawirmf_auto_folder', function ( $folder, $att_id, $attachment ) {
    if ( 'application/pdf' === $attachment->post_mime_type ) {
        return 'Documents';
    }
    if ( 'product' === get_post_type( $attachment->post_parent ) ) {
        return 'Products';
    }
    return $folder;
}, 10, 3 );`

File blog images by year ("Blog/2026"):

`add_filter( 'sawirmf_auto_folder', function ( $folder, $att_id, $attachment ) {
    if ( 'post' === get_post_type( $attachment->post_parent ) ) {
        return 'Blog/' . get_the_date( 'Y', $attachment );
    }
    return $folder;
}, 10, 3 );`

Give each uploading user their own folder:

`add_filter( 'sawirmf_auto_folder', function ( $folder, $att_id, $attachment ) {
    $user = get_userdata( $attachment->post_author );
    return $user ? 'Users/' . $user->display_name : $folder;
}, 10, 3 );`

Notes:

* Paths are slash-separated and nest ("Clients/Acme/Logos" creates three levels as needed); existing folders are reused, never duplicated.
* Rules only run for uploads made while the plugin is active; existing files are untouched.
* Returning a folder ID that doesn't exist is ignored (the upload stays uncategorized).

== Frequently Asked Questions ==

= Do folders change my file URLs? =

No. Folders are purely organizational (a hidden taxonomy on attachments). Files stay exactly where WordPress uploaded them.

= What happens if I deactivate or delete the plugin? =

Nothing breaks. Your files are untouched; folder assignments simply stop being displayed. Reactivate and they're back.

= Is there a folder limit in the free version? =

There is no paid version. Everything is free and unlimited.

= Where can I get support or report a bug? =

Use the plugin's support forum on wordpress.org, or contact us at [sawirstudio.com](https://sawirstudio.com) — email ricardo@sawirstudio.com.

== Other plugins by Sawir Studio ==

* [Sawir Live Translate](https://wordpress.org/plugins/sawir-live-translate/) — translate any front-end page live and let visitors switch languages.
* [Sawir Restock Notifier for WooCommerce](https://wordpress.org/plugins/sawir-restock-notifier-for-woocommerce/) — let customers request an email when an out-of-stock product is back.
* [Sawir Product Image Zoom for WooCommerce](https://wordpress.org/plugins/sawir-product-image-zoom-for-woocommerce/) — product image lightbox with navigation and click-to-zoom.
* [Sawir Variation Gallery Tools for WooCommerce](https://wordpress.org/plugins/sawir-variation-gallery-tools-woocommerce/) — manage variation-specific gallery images.
* [Sawir Role Capabilities Manager](https://wordpress.org/plugins/sawir-role-capabilities-manager/) — create custom user roles and manage capabilities.

== Changelog ==

= 1.0.0 =
* Initial release: folder tree in the media grid, drag & drop for files and folders, drop-zone reordering (before/after/inside), folder filter dropdown in media modals.
