=== Acidboxblues Visual Grid for Bandcamp ===
Contributors: thisisnotlondon
Donate link: https://paypal.me/fundmydigitakt
Tags: bandcamp, music, albums, grid, discography
Requires at least: 5.4
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.3.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display a grid of Bandcamp albums on your WordPress site with customisable layouts and automatic data caching.

== Description ==

Acidboxblues Visual Grid for Bandcamp is a WordPress plugin that allows you to display your Bandcamp discography in a responsive grid layout. Suitable for musicians, labels, and music blogs who want to showcase their Bandcamp releases on their WordPress site.

= Features =

* Responsive grid layout that adjusts to any screen size
* Customisable columns between 1 and 6 (default: 2)
* Automatic data fetching retrieves album titles, artwork, and release dates from Bandcamp
* Caches album data for faster page loads
* Sort albums by release date or title, ascending or descending
* Simple shortcode implementation
* Cache updates automatically twice daily
* **New:** Real-time visual progress bar and status updates when manually refreshing the cache
* Built with WordPress security best practices and data validation

= How It Works =

1. Add your Bandcamp album URLs to the plugin settings (one per line)
2. The plugin fetches album information (title, artwork, release date) from each URL
3. Data is cached for performance
4. Display your albums anywhere using the [acidvigr_visual_grid] shortcode
5. Cache updates automatically twice daily to keep your discography current

= Suitable For =

* Musicians displaying their discography
* Record labels displaying their catalogue
* Music blogs featuring artist collections
* Music review sites
* Bandcamp Friday promotions

== Installation ==

= Automatic Installation =

1. Log in to your WordPress admin panel
2. Go to Plugins → Add New
3. Search for "Acidboxblues Visual Grid for Bandcamp"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin zip file
2. Log in to your WordPress admin panel
3. Go to Plugins → Add New → Upload Plugin
4. Choose the zip file and click "Install Now"
5. Click "Activate Plugin"

= After Installation =

1. Go to Settings → Acidboxblues Visual Grid
2. Add your Bandcamp album URLs (one per line)
3. Adjust number of columns if desired
4. Click "Save Settings"
5. Click "Update Cache Now" to fetch your album data
6. Add the shortcode [acidvigr_visual_grid] to any page or post

== Frequently Asked Questions ==

= How do I add the grid to my page? =

Add the shortcode [acidvigr_visual_grid] to any page, post, or widget that supports shortcodes.

= What URLs should I use? =

Use the full HTTPS URL of any Bandcamp album or track page, for example: https://artist.bandcamp.com/album/album-name or https://artist.bandcamp.com/track/track-name

= Can I customise the grid layout? =

Yes. In Settings → Acidboxblues Visual Grid you can:

* Set the number of columns (1-6)
* The grid is automatically responsive on mobile devices

= How do I sort the albums? =

Use these shortcode variations:

* [acidvigr_visual_grid] - Default (newest first)
* [acidvigr_visual_grid sort="date" order="desc"] - Newest first
* [acidvigr_visual_grid sort="date" order="asc"] - Oldest first
* [acidvigr_visual_grid sort="title" order="asc"] - A-Z by title
* [acidvigr_visual_grid sort="title" order="desc"] - Z-A by title

= How often does the cache update? =

The cache updates automatically twice daily. You can also manually update it anytime from Settings → Acidboxblues Visual Grid by clicking "Update Cache Now".

= Why isn't my new release showing up? =

If you've just added a new album to Bandcamp:

1. Add the URL to your settings
2. Click "Save Settings"
3. Click "Update Cache Now"
4. The album should appear immediately.

= Can I use albums from different Bandcamp artists? =

Yes. You can mix albums from any Bandcamp artist or label. Just add all the URLs to your list.

= Will this slow down my site? =

No. The plugin caches all album data locally, so your pages load quickly. Album information is only fetched from Bandcamp during cache updates (twice daily or when manually triggered).

= Does this work with Bandcamp labels? =

Yes. You can add any Bandcamp URL, whether it's from an individual artist or a label page.

= What if a URL is invalid? =

The plugin validates all URLs and only saves valid HTTPS Bandcamp URLs. Invalid URLs are automatically filtered out when you save settings.

= Can I display multiple grids on one page? =

Yes. You can use multiple [acidvigr_visual_grid] shortcodes on the same page, each with different sorting options.

== Changelog ==

= 1.3.8 =
* Feature: Added a visual progress bar and real-time status text to the settings page when updating the cache manually.
* Improvement: Switched manual cache updates to a JavaScript-based batch process. This prevents PHP timeouts when processing large lists of URLs.
* Improvement: Better error handling during the scraping process; individual URL failures no longer stop the entire batch.

= 1.3.7 =
* Security: Implemented "late escaping" for inline CSS generation using `absint()` to prevent injection.
* Security: Enhanced input sanitization for settings using `wp_unslash` and strict field sanitization.
* Security: Hardened settings saving process by using specific input allowlists.

= 1.3.6 =
* Refactor: Implemented PHP Namespaces (`thisisnotlondon\bandcampalbumgrid`) to prevent code collisions.
* Refactor: Standardized all internal prefixes to `acidvigr_` (Classes, constants, options, and actions).
* Change: Shortcode updated to `[acidvigr_visual_grid]`.
* Performance: Separated CSS and JS into dedicated asset files.
* Performance: Implemented `wp_add_inline_style` for dynamic column handling.
* Performance: Implemented `wp_localize_script` for secure Admin JS variable handling.

= 1.3.5 =
* Renamed plugin to Acidboxblues Visual Grid for Bandcamp
* Removed: Thumbnail size setting to simplify layout and prevent CSS conflicts
* Changed: Images now automatically fill 100% of the column width
* Improved: CSS handling for square aspect ratios

= 1.3.4 =
* Fixed: Critical error on activation by ensuring WordPress is fully loaded before initialisation
* Improved: Added check for DOMDocument extension to prevent crashes on unsupported servers

= 1.3.3 =
* Fixed: CSS specificity issue where some themes would override the thumbnail size setting
* Improved: Added important flag to width styles to ensure user settings take precedence

= 1.3.2 =
* Fixed: Grid "blowout" issue where large album covers would expand columns unexpectedly
* Improved: CSS Grid definition using minmax to handle intrinsic image sizes

= 1.3.1 =
* Changed: Thumbnail size setting now uses percentages (%) instead of pixels (px) for responsiveness
* Improved: Added aspect-ratio CSS to ensure thumbnails remain square
* Improved: Images smaller than column width are now automatically centred

= 1.3.0 =
* Improved: Replaced Regex with DOMDocument for more reliable data fetching
* Improved: Cache security (hashed filenames and directory protection)
* Improved: Handling of line endings in settings
* Improved: Hidden admin error messages from public view
* Updated: Requires PHP 7.4+

= 1.2.0 =
* Added customisable column count setting
* Added adjustable thumbnail size
* Improved settings panel UI
* Enhanced security with proper escaping
* Added translation support
* Simplified default URL list
* Fixed WordPress coding standards compliance
* Performance improvements

= 1.0.0 =
* Initial release

== Upgrade Notice ==

= 1.3.8 =
Introduces a new visual progress bar for manual cache updates and batch processing to improve stability for large discographies.

= 1.3.7 =
Security maintenance release. Includes hardening of input sanitization and late escaping of output data.

= 1.3.6 =
This is a significant refactor. The shortcode has changed to `[acidvigr_visual_grid]`. Please update your posts and pages.