=== W4 Post List ===
Contributors: sajib1223
Tags: post list, user list, post grid, category list, shortcode
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.11.0
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Build lists the Query Loop can't: posts grouped by year, category or author, term lists and user directories — via block, shortcode or widget.


== Description ==

W4 Post List builds the lists that WordPress core still can't: posts **grouped** under year, month, category or author headings; category and term indexes; user directories; and combined Terms + Posts and Users + Posts lists. You control the output with a template of plain HTML and simple template tags, so the markup stays clean, semantic and completely yours.

Place any list anywhere with the **W4 Post List block**, the `[postlist id="123"]` shortcode, or the classic widget.

= What can you build? =

* **Year/month archives** — posts grouped under date headings
* **Category, tag or custom taxonomy indexes** — with or without each term's posts listed underneath
* **Author and user directories** — list users by role, with avatars, bios and each user's posts
* **Filtered post lists** — any post type, filtered by status, taxonomy terms, custom fields, dates, authors, parents and more
* **Media lists** — image and attachment lists by mime type

= Five list types =

* Posts
* Terms
* Users
* Terms + Posts
* Users + Posts

= Query options (Posts) =

* Post type, status and mime type
* Search keyword
* Include/exclude posts by ID, exclude the current post
* Filter by parent, author, taxonomy terms (tax query), custom fields (meta query) and dates (date query)
* Items per page, with multi-page pagination

= Group results by =

* Year, month, or month + year
* Category, tag or any custom taxonomy
* Author
* Parent

= Order results by =

* ID, title, slug, publish date, modified date, menu order, comment count, custom field value, or random

= Pagination =

* Next/previous links or numeric navigation, with optional AJAX page loading

= Full control over the output =

Output is template-driven: every list has an HTML template with template tags like `[post_title]`, `[post_permalink]`, `[featured_image]`, `[post_author_name]` and `[post_meta key="..."]`. Start from a ready-made template — cards, archives, category indexes, user directories — and tweak it, or write your own markup for pixel-perfect control. A live preview in the editor shows your changes before you save. If you want a drag-and-drop visual builder, this plugin isn't that — it keeps you close to your own HTML, which is exactly why themes and developers like it.

See the [full template tag reference](https://w4dev.com/docs/w4-post-list/faqs/what-are-the-available-template-tags/) and [live examples with copy-paste templates](https://w4dev.com/wp/w4-post-list-examples/).

= Lightweight, independently measured =

[WP Hive](https://wphive.com/plugins/w4-post-list/) independently measures W4 Post List at **19 KB memory usage and +0.05 s page-speed impact — better than 99% of the plugins they test**. No bundled frameworks, no frontend bloat.


== Installation ==

1. Install from Plugins → Add New (search for "W4 Post List"), or upload the zip to `/wp-content/plugins/`.
2. Activate the plugin through the Plugins menu.
3. Find the **W4 Post List** menu (list icon) in your admin sidebar. Create a list, publish it, then place it on any page with the W4 Post List block or the `[postlist id="123"]` shortcode.


== Frequently Asked Questions ==

= How do I display a list? =

Three ways: add the **W4 Post List block** and pick your list; paste the shortcode `[postlist id="123"]` into any content; or add the W4 Post List widget to a widget area. Each list's ID and ready-made shortcode are shown in the Shortcode column on the All Lists screen.

= How do I list posts from a specific category? =

Create a Posts list, open the **Posts: Tax Query** section, and select your taxonomy and terms. You can combine multiple term filters, and filter by custom fields and dates the same way.

= Why does my list show nothing on the page? =

The usual causes, in order: the list is not **Published** yet; the shortcode ID doesn't match (check the Shortcode column on the All Lists screen); the template is missing its loop tags (a Posts list template needs `[posts]...[/posts]`, Terms needs `[terms]...[/terms]`, Users needs `[users]...[/users]`); or the query simply matched no items. Opening the list and re-checking the query options usually finds it.

= Do I have to write the template myself? =

No. Pick a layout from **Start from a template** in the list editor — thumbnail cards, a year archive, a category index, a user directory and more. It copies the markup and styles into the editable Template and Style fields, so you can use it as-is or adjust anything.

= Can I see a list before publishing it? =

Yes - the **Preview** button under the editor renders your current, unsaved settings, and refreshes automatically as you change options. It renders without your theme's stylesheet, so spacing and fonts will differ slightly on the real page.

= Can I display custom fields (including ACF)? =

Yes. Use `[post_meta key="your_field_key"]` inside the posts loop. Fields stored as plain values (text, numbers, URLs) work best; complex/serialized fields are output as stored.

= Can I group posts by year, category or author? =

Yes — that's this plugin's specialty. Set **Group by** to year, month, month + year, any taxonomy, author or parent, and the list renders grouped sections with headings. The core Query Loop block can't do this.

= Can I list users or build an author directory? =

Yes. Use the **Users** list type (filter by role, order by name/registration date) or **Users + Posts** to show each user with their latest posts. Template tags cover avatars, display names, bios and profile URLs.

= Does it work with the block editor and block themes? =

Yes. The W4 Post List block renders your list server-side with a live preview in the editor, and the shortcode works in classic editors, page builders and template files (`echo do_shortcode( '[postlist id="123"]' );`).

= Where is the documentation? =

In your admin: **W4 Post List → Documentation** (template tags reference, examples, usage). Online: [w4dev.com/docs/w4-post-list](https://w4dev.com/docs/w4-post-list/faqs/what-are-the-available-template-tags/).


== Screenshots ==

1. Start from a template — pick from ready-made layouts per list type.
2. The template editor — syntax highlighting, tag insertion, editable starter markup.
3. Live preview — see your unsaved changes rendered without leaving the editor.
4. Thumbnail cards starter on the front end.
5. Year archive starter — posts grouped under year headings.
6. User directory starter — avatars, names and bios in a card grid.
7. Helpful save-time warnings — mistakes are explained and coerced, never rejected.
8. Every list's shortcode is one click away.


== Changelog ==
= 2.11.0 =
* New: The editor now catches mistakes at save time - non-numeric values in numeric fields are coerced with a clear warning, unknown template tags get a "did you mean" suggestion, and a template missing its loop tag warns before rendering blank.
* New: Switching list type with an incompatible template shows an inline warning with a one-click "Replace with the default template" fix.
* New: The list editor form is protected by a nonce; quick edit, bulk edit and autosave can never touch list options.
* Improved: "Any" post status now excludes the concrete statuses automatically.
* New: A once-only review request appears a week after your first published list. Clicking either button - including "Leave a review" itself - resolves it forever.
= 2.10.0 =
* New: Live preview in the list editor - a Preview button renders your current, unsaved settings in an isolated pane, refreshing automatically after option changes. No more publish-and-reload loops while designing a list.
* Improved: Getting Started guide mentions the preview workflow.
= 2.9.0 =
* New: "Start from a template" - pick from 8 ready-made layouts (simple list, thumbnail cards, title & date list, year archive, category index, category index with posts, user directory, authors with posts). Picking one copies editable markup and styles into the Template and Style fields and sets the options it needs, like Group by. Developers can add layouts via the w4pl/starter_templates filter.
* New: Applying a starter shows a confirmation and opens the Template section automatically, so you immediately see what you got.
* Improved: Lists using a legacy preset keep working exactly as before; the legacy preset field only appears on those lists.
* Improved: In-plugin docs updated for the new flow; new FAQ "Do I have to write the template myself?".
* Fix: Guarded the editor form action URL against missing server variables (CLI contexts).
* Dev: Select field values are now attribute-escaped in the form engine.
= 2.8.0 =
* New: The Template, CSS and JavaScript fields are now real code editors with syntax highlighting and line numbers; template tags insert at the cursor.
* Improved: Default templates rewritten in the plain tag dialect with a visible per-item wrapper (div.post-item / .term-item / .user-item) and the [nav] pagination tag, so the loop structure is obvious at a glance. Applies to newly created lists; saved lists keep their stored template.
* New: "Display this list" box on the list editor with the copyable shortcode, a copy button and placement pointers.
* New: A wrong or missing list ID, or a rendering error, now shows logged-in editors an inline explanation - visitors see nothing (previously raw error text could leak to visitors).
* New: "No items text" is prefilled with "No items found." for new lists, so empty results are no longer an invisible blank. Existing lists are unchanged.
* Improved: The editor form refresh is debounced, disables Publish properly, and recovers gracefully from failed requests instead of freezing the screen.
* Fix: Editor layout no longer overflows when adding several Meta/Tax Query rows; height recalculates on window resize.
* Dev: Removed dead JavaScript (broken external autocomplete lineage, IE-era caret handling).
= 2.7.0 =
* New: First-run onboarding - fresh installs get a draft "Example: Recent Posts" list, so there is always a working configuration to open and learn from.
* New: A dismissible "Get started" notice after activation walks through the three steps: create a list, publish, place it with the block or shortcode.
* New: Helpful empty state on the Lists screen and a contextual Help tab on the list screens summarizing the workflow.
* Improved: The telemetry opt-in prompt now waits until after your first published list, so guidance comes first.
= 2.6.0 =
* New: Automated test suite now gates every release - characterization snapshots freeze the rendered output of all five list types (including grouped lists and pagination) so updates can no longer break existing lists unnoticed.
* New: List options now carry a schema version with a lazy migration path, protecting saved lists during future upgrades.
* New: Opt-in usage counters (lists created/published) added to the existing Appsero telemetry. Nothing is collected without your explicit consent.
* Fix: PHP 8.2+ deprecation notices from the query classes (dynamic properties).
* Fix: Unit-suffixed dimensions in template tags (e.g. [post_thumbnail width="50px"]) caused a PHP notice and broken output on PHP 7.x - dimensions are now parsed forgivingly (50px, 50 and "50" all work).
* Dev: Docs-drift guard - documentation examples, default templates and presets are verified in CI against the registered template tags.
* Dev: Coding-standards nonce exclusion scoped to legacy files only; new endpoints are always linted for nonce verification.
= 2.5.9 =
* New: Added a WordPress Playground blueprint that powers the Live Preview button on the wordpress.org plugin page.
= 2.5.8 =
* Fix: Documentation examples used unregistered template tags ([post_link], [group_name], [group_link]) and invalid HTML, so copy-pasting them produced broken output. All examples now use registered tags with valid loop markup.
* New: "Getting Started" documentation tab with a step-by-step walkthrough, now the default tab.
* Fix: The Documentation page is now visible to everyone who can edit lists (previously required the delete_users capability, hiding it from Editors).
* Fix: The "Include users" and "Exclude users" fields were incorrectly described as taking term IDs; corrected, along with a typo cleanup across admin field descriptions.
* Fix: Added missing text domain to the Appsero opt-in notice string.
= 2.5.7 =
* Improved: Rewrote the wordpress.org listing for accuracy — removed the reference to the retired TinyMCE button, repositioned the description around grouped lists and user directories, expanded the FAQ from real support questions, updated screenshots and fixed typos.
* Improved: Plugin header description.
* Note: No functional changes in this release.
= 2.5.6 =
* New: Post status options now include all registered statuses, including custom ones (e.g. "Expired" from job listing plugins) - https://github.com/w4devInc/w4-post-list/issues/88.
* Tested up to WordPress 7.0.2.
= 2.5.5 =
* Tested up to WordPress 6.9.1.
= 2.5.4 =
* Fix: Sanitized media image width and height attributes - https://github.com/w4devInc/w4-post-list/issues/64.
= 2.5.3 =
* Fix: Fixed version number.
= 2.5.1 =
* Fix: Fixed textdomain issue.


[See changelog of all versions](https://raw.githubusercontent.com/w4devInc/w4-post-list/master/CHANGELOG.txt).

== Upgrade Notice ==
= 2.11.0 =
Biggest update yet: 8 starter templates with one-click apply, live preview in the editor, and save-time validation with helpful warnings.
= 2.10.0 =
Live preview in the list editor.
= 2.9.0 =
Eight ready-made starter templates with copy-on-select editing. Legacy presets unchanged.
= 2.8.0 =
Code editors for templates, copyable shortcode box, visible error notices for editors, editor stability fixes.
= 2.7.0 =
First-run onboarding (example list, get-started guide), the post_thumbnail px-dimension fix, PHP 8.2 cleanups, and automated release testing.
= 2.6.0 =
Adds automated release testing, options versioning and PHP 8.2 deprecation fixes. No changes to list output.
= 2.5.9 =
Adds a Live Preview blueprint for the wordpress.org plugin page. No functional changes.
= 2.5.8 =
Documentation fixes: examples now copy-paste correctly, new Getting Started guide, docs visible to Editors.
= 2.5.7 =
Listing and documentation accuracy update — no functional changes.

== Privacy Policy ==
W4 Post List uses [Appsero](https://appsero.com) SDK to collect some telemetry data upon user's confirmation. This helps us to troubleshoot problems faster & make product improvements.

Appsero SDK **does not gather any data by default.** The SDK only starts gathering basic telemetry data **when a user allows it via the admin notice**. We collect the data to ensure a great user experience for all our users.

Integrating Appsero SDK **DOES NOT IMMEDIATELY** start gathering data, **without confirmation from users in any case.**

Learn more about how [Appsero collects and uses this data](https://appsero.com/privacy-policy/).
