=== Simple GDrive Embed ===
Contributors: lzmsweb
Tags: google drive, embed, shortcode, file browser, gdrive
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.6.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Embed a publicly shared Google Drive folder as a navigable file browser — no API key or authentication required.

== Description ==

Simple GDrive Embed lets you place any publicly shared Google Drive folder inside any post or page using a simple shortcode. Visitors can browse subfolders and preview files without ever leaving your website.

**No Google API key. No OAuth. No configuration beyond pasting a sharing link.**

= How it works =

Rather than embedding Google's own iframe (which spawns new windows on every click), the plugin fetches your folder's contents server-side via PHP and renders a clean, navigable file browser entirely within your page. Subfolder navigation uses WordPress AJAX — clicking a folder loads its contents in place. Individual files open in a preview modal on top of your page. Nothing leaves your site except folder-content requests to Google Drive itself, and — only if you opt in under Settings → GDrive Embed — anonymous error reports (see "Diagnostics" below).

= Key features =

* Subfolder navigation stays entirely within your page — no popups, no new tabs
* File preview modal with fullscreen support
* Back button and breadcrumb navigation trail
* Server-side folder caching to minimise requests to Google
* Responsive layout with dark-mode support
* No Google API key or OAuth setup required
* Two shortcode aliases: [gdrive_embed] and [simple_gdrive_embed]

= Requirement =

The Google Drive folder must be shared as **"Anyone with the link"** (Viewer access). This is a standard Google Drive sharing option. The plugin cannot bypass Google's own permissions — if a folder is private, visitors will see an error.

== Installation ==

= Installing from a ZIP file =

1. Download the `simple-gdrive-embed.zip` file.
2. Log in to your WordPress admin dashboard.
3. Go to **Plugins → Add New Plugin → Upload Plugin**.
4. Click **Choose File**, select the ZIP, then click **Install Now**.
5. After the upload completes, click **Activate Plugin**.
6. A **Settings** link will appear next to the plugin on the Installed Plugins screen. Click it to open the settings page, which contains full usage instructions.

= Installing via FTP =

1. Unzip `simple-gdrive-embed.zip` to extract the `simple-gdrive-embed` folder.
2. Upload that folder to `/wp-content/plugins/` on your server via FTP or SFTP.
3. Log in to your WordPress admin dashboard and go to **Plugins → Installed Plugins**.
4. Find Simple GDrive Embed and click **Activate**.

= Requirements =

* WordPress 5.6 or later
* PHP 7.4 or later
* PHP DOM and libxml extensions (standard on all major hosts)
* Your server must be able to make outbound HTTPS requests to `drive.google.com`

== Usage ==

= Step 1: Share your Google Drive folder publicly =

1. Open Google Drive and locate the folder you want to embed.
2. Right-click the folder and choose **Share**.
3. Under "General access", change **Restricted** to **Anyone with the link**.
4. Make sure the role is set to **Viewer**.
5. Click **Copy link**, then click **Done**.

= Step 2: Add the shortcode =

Paste the shortcode into any post, page, or widget. Replace the URL with the one you copied from Google Drive.

**Minimum example:**
`[gdrive_embed url="https://drive.google.com/drive/folders/YOUR_FOLDER_ID?usp=sharing"]`

**With all options:**
`[gdrive_embed url="https://drive.google.com/drive/folders/YOUR_FOLDER_ID?usp=sharing" title="Project Files" height="500" width="100%" show_link="no" allow_fullscreen="yes"]`

= Shortcode attributes =

* **url** _(required)_ — The full sharing URL copied from Google Drive.
* **height** — Height of the listing area in pixels. Default: 480 (or your setting).
* **width** — CSS width of the widget (px, %, em, rem, vw). Default: 100%.
* **title** — Label shown in a title bar above the browser. Default: none.
* **show_link** — `yes` or `no` — show an "Open in Google Drive" link. Default: no.
* **allow_fullscreen** — `yes` or `no` — allow fullscreen file previews. Default: yes.
* **class** — Extra CSS class name(s) added to the outer wrapper element.
* **view** — `list` or `gallery`. Gallery shows images and folders as visual tiles with a lightbox instead of a file list. Default: list.
* **layout** — `masonry` or `thumbnail`. Tile layout used when `view="gallery"`. Default: masonry.
* **per_page** — Gallery view only. How many tiles load before a "Load more" button appears. Default: 24 (or your setting).

Both `[gdrive_embed]` and `[simple_gdrive_embed]` are identical aliases.

= Gallery view =

`[gdrive_embed url="…" view="gallery"]` displays images in a masonry grid and folders as thumbnail tiles (using the first image found inside each folder), with the folder name overlaid on a solid background at the bottom. Clicking an image opens a full-size lightbox with next/previous navigation; clicking a folder navigates into it. Add `layout="thumbnail"` for a uniform square grid instead of masonry. Non-image files (Docs, Sheets, PDFs, etc.) are hidden in gallery view.

= How navigation works =

* Clicking a **subfolder** loads its contents inside the widget. The visitor never leaves your page.
* The **Back button** and **breadcrumb trail** let visitors retrace their steps.
* Clicking a **file** opens a preview modal on top of your page. Close it with the × button, by pressing Escape, or by clicking outside the modal.
* Folder listings are **cached on your server** for the configured duration (default: 5 minutes) to reduce requests to Google.

== Frequently Asked Questions ==

= Do I need a Google API key? =
No. The plugin fetches the publicly accessible version of your folder directly — the same page Google uses for embeds in Google Sites. No API key, no service account, no OAuth.

= Why do I see "Could not load folder"? =
The most common cause is that the folder is not shared publicly. Open Google Drive, right-click the folder → Share → change General access to "Anyone with the link". Then reload the page (the cache may need to expire first — or temporarily set Cache Duration to 0 in settings).

= Can individual files inside the folder have different permissions? =
Yes. Each file in Google Drive has its own sharing settings. If a file preview modal appears blank, check that the individual file is also shared as "Anyone with the link" in Google Drive.

= Does this work with Google Workspace (formerly G Suite) accounts? =
Yes, as long as the folder's sharing allows public link access. Some Google Workspace administrators restrict sharing outside the organisation, which would prevent this from working.

= How do I update the folder contents after making changes in Google Drive? =
Folder listings are cached for the duration set in Settings → GDrive Embed → Cache Duration. Changes will appear after the cache expires. To see changes immediately, temporarily set Cache Duration to 0, save, then restore your preferred value.

= Can I embed files or Google Docs directly? =
Version 2.x is focused on folder browsing. For embedding single files or Docs, use the Google Drive sharing link in an iframe shortcode or a page builder embed block instead.

= Is there a way to avoid scraping Google entirely? =
If you manage your own Ubuntu/Debian server with root access, the companion plugin **Simple GDrive for Rclone** reads folder contents directly from a local rclone mount instead of Google's public embed page. It's a separate plugin (own shortcode, own settings) so it doesn't add any complexity to sites that don't need it.

= Does gallery view load everything at once? =
No. Tiles render in batches (24 by default — adjustable in Settings → GDrive Embed → Gallery Tiles Per Page) with a "Load more" button to reveal the rest. This keeps large galleries fast to open.

= What is "Share Anonymous Error Reports" in Settings? =
It's an optional, off-by-default diagnostic feature. If enabled, the plugin sends a small technical report — plugin/WordPress/PHP version, an anonymous per-site ID, and the type of failure — only when it fails to read a Google Drive folder. It never sends folder names, folder IDs, file names, or your site's URL. This helps the developer notice quickly if Google changes something that breaks the plugin, rather than relying only on support tickets.

== Screenshots ==

1. The file browser widget showing folders and files with breadcrumb navigation.
2. A file preview modal opened on top of the page.
3. The settings / instructions page in the WordPress admin.

== Changelog ==

= 2.6.1 =
* Moved the plugin's home page to https://garryheath.com/gdriveembed/ and updated the Plugin URI and Author URI headers to match.
* Added the Requires at least (WordPress 5.6) and Requires PHP (7.4) headers to the plugin file so WordPress checks them before installing or updating.
* Verified compatibility with WordPress 7.1 and PHP 8.5. No functional changes.

= 2.6.0 =
* Editors now see a plain-language explanation and fix when a Drive folder fails to load (403/404/etc.); public visitors still see a clean empty gallery. New wp-admin notice flags recently-failed embeds.

= 2.5.5 =
* Fixed the phpcs:ignore comment placement for the settings-updated notice check — a WordPress.org plugin-check pass still flagged it because the ignore directive wasn't immediately adjacent to the flagged line.

= 2.5.4 =
* Security/hardening: added missing wp_unslash() on POSTed folder IDs in both AJAX endpoints, escaped all remaining unescaped output on the settings page and shortcode markup (style attribute, title/link HTML, options-key field names, version string), and fixed a WordPress.org plugin-check false positive on the settings-updated notice with a documented justification.
* Added the missing ABSPATH direct-access guard to the GHPDM update checker.
* Verified compatibility with WordPress 7.1; bumped "Tested up to."

= 2.5.3 =
* Performance fix: the one-level folder-thumbnail fallback added in 2.5.2 previously required two sequential AJAX round trips per "folder of folders" tile — it now resolves in one round trip via a new dedicated endpoint, halving the request count for exactly the folder structure that fallback targets.
* Added a client-side concurrency limit (4 at a time) on folder-thumbnail lookups, so a dense gallery grid can no longer fire a dozen-plus simultaneous requests that queue up behind a shared host's limited PHP worker pool. Requests now queue smoothly on the client and fire as earlier ones complete.

= 2.5.2 =
* Fixed blank folder thumbnails in gallery view for folders that contain only subfolders. When a folder has no images of its own, the plugin now looks one level deeper — into the first subfolder — and uses the first image found there instead of leaving the tile blank. Documented the full thumbnail lookup order under Settings → GDrive Embed → How to Use → Gallery view.

= 2.5.1 =
* Added a configurable number of gallery columns (Settings → GDrive Embed → Gallery Columns), with separate values for mobile, tablet, and desktop widths — default 3 / 4 / 6. Applies to both Masonry and Thumbnail layouts, replacing the previous fixed column counts.

= 2.5.0 =
* Gallery view: folder thumbnails now load lazily as tiles scroll into view, instead of every rendered tile firing a lookup request at once. Fixes slow initial gallery loads (previously up to 20-30 seconds on folders with many subfolders).
* Added background cache warming: the plugin can now periodically re-check embedded folders for new or changed files and quietly refresh the cache, so visitors rarely hit a cold cache at all. The cache is only ever updated, never cleared. Configurable under Settings → GDrive Embed → Background Cache Warming (on by default, checks every 60 minutes).
* Added an "Update Cache Now" button in settings to trigger an immediate background refresh on demand.
* Background warming automatically runs once after any plugin update, since an update may change how folders are read.

= 2.4.1 =
* Fixed the file preview close button overlapping Google's own controls inside the preview — the close (and new download) buttons now sit in a small bar above the preview on desktop, and in a slim strip at the top on mobile, instead of floating on top of the iframe.
* Added a download button to the file preview, next to close. Downloads the original file for regular uploads, and exports Google Docs/Sheets/Slides to PDF/XLSX/PPTX respectively.

= 2.4.0 =
* No functional changes to the scraper, caching, gallery, or telemetry behavior.
* Documentation update: added an FAQ entry pointing to the new companion plugin, Simple GDrive for Rclone, for self-managed servers that want to read Drive contents from a local rclone mount instead of scraping.

= 2.3.0 =
* Added pagination to gallery view: large folders now render in batches with a "Load more" button instead of drawing every tile at once (adjustable via the new Gallery Tiles Per Page setting, or the `per_page` shortcode attribute).
* Added opt-in, anonymous error telemetry (Settings → GDrive Embed → Share Anonymous Error Reports, off by default) to help catch it quickly if Google changes something that breaks folder scraping. No folder names, folder IDs, file names, or site URLs are ever sent.
* Added a per-site anonymous telemetry ID, shown in Settings for reference.

= 2.2.0 =
* Added gallery view (`view="gallery"`) as an alternative to the default file list.
* Gallery view supports masonry (default) or thumbnail layout via the `layout` attribute.
* Folders in gallery view display a thumbnail of the first image found inside them, with the folder name overlaid at the bottom.
* Clicking an image in gallery view opens a full-size lightbox with next/previous navigation and keyboard arrow support.
* Non-image files are hidden in gallery view; switch to `view="list"` (default) to see all file types.
* Wired in the GHPDM update checker so future releases reach client sites automatically.

= 2.1.0 =
* Added Settings link on the Installed Plugins screen.
* Added full installation and usage instructions to the settings page.
* Added troubleshooting table to the settings page.
* Removed hardcoded example Drive URL from plugin code.
* Updated readme.txt with complete installation and usage documentation.

= 2.0.0 =
* Complete rewrite: replaced Google iframe with a custom PHP + AJAX file browser.
* Subfolder navigation now stays entirely within the page — no new windows.
* File previews open in an on-page modal.
* Added breadcrumb navigation and Back button.
* Added server-side folder caching via WordPress transients.
* Added dark-mode CSS support.

= 1.0.0 =
* Initial release using Google's embeddedfolderview iframe.
